CtrlK
BlogDocsLog inGet started
Tessl Logo

api-design-principles

Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers. Use when designing new APIs, reviewing API specifications, or establishing API design standards.

56

Quality

62%

Does it follow best practices?

Impact

No eval scenarios have been run

SecuritybySnyk

Passed

No known issues

Fix and improve this skill with Tessl

tessl review fix ./plugins/backend-development/skills/api-design-principles/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

50%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is a reasonably lean, well-organized overview of API design principles with some concrete specifics, but it spends tokens restating well-known basics, mixes actionable advice with vague platitudes, lacks any sequenced workflow with validation, and only points to one of its five bundle files.

Suggestions

Cut explanations of basics Claude already knows (HTTP method idempotency, 'resources are nouns', query/mutation/subscription roles) and keep only the non-obvious design guidance.

Tighten vague best-practice items into concrete rules — e.g., 'Rate Limiting' -> 'Return 429 with Retry-After and X-RateLimit-* headers'; 'Documentation' -> 'Emit an OpenAPI 3.1 spec and validate it in CI'.

Surface all bundle files from the overview with one-level-deep links (e.g., a 'References' section pointing to rest-best-practices.md, graphql-schema-design.md, assets/api-design-checklist.md, and assets/rest-api-template.py), not just details.md.

DimensionReasoningScore

Conciseness

The body is terse and list-based rather than verbose, but it re-explains concepts Claude already knows (HTTP method semantics like 'GET: idempotent, safe', 'resources are nouns not verbs', and GraphQL query/mutation/subscription basics). Not a 3 because those well-known basics do not earn their tokens; not a 1 because the presentation is lean bullet form rather than padded prose.

2 / 3

Actionability

It mixes concrete actionable guidance ('Use plural nouns for collections (`/users`, not `/user`)', 'Use cursor-based pagination (Relay spec)', 'Use @deprecated directive', versioning URL/header examples) with vague platitudes ('Protect your API with rate limits', 'Plan for breaking changes from day one', 'Documentation: Use OpenAPI/Swagger'). Not a 3 because much of it is descriptive rather than copy-paste-ready instruction; not a 1 because several items are specific and applicable.

2 / 3

Workflow Clarity

The content is organized by topic (When to Use, Core Concepts, Versioning, Best Practices, Pitfalls) but there is no sequenced multi-step design workflow and no validation checkpoints or feedback loops. Not a 3 because there are no explicit validation/error-recovery steps; not a 1 because the structure is clear and organized rather than unclear or missing, and no destructive batch workflow requires a cap.

2 / 3

Progressive Disclosure

The body clearly signals one one-level-deep reference ('Detailed pattern documentation lives in references/details.md'), but it does not surface the other four bundle files (references/graphql-schema-design.md, references/rest-best-practices.md, assets/api-design-checklist.md, assets/rest-api-template.py). Not a 3 because navigation to most bundle materials is missing; not a 1 because the one signaled reference is well-structured and not deeply nested.

2 / 3

Total

8

/

12

Passed

Description

75%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description cleanly answers both 'what' and 'when' with an explicit Use-when clause and a distinct REST/GraphQL API-design niche. It is held back from a perfect score by buzzword padding in the lead phrase and somewhat abstract, limited-coverage trigger terms.

Suggestions

Replace the buzzword clause 'intuitive, scalable, and maintainable APIs that delight developers' with concrete design actions (e.g., 'define resource-oriented endpoints, version breaking changes, structure GraphQL schemas').

Broaden trigger-term coverage with natural variations users actually say, such as 'API endpoints', 'API schema', 'REST vs GraphQL', and 'API documentation/review'.

DimensionReasoningScore

Specificity

It names the domain ('REST and GraphQL API design') and three actions ('designing new APIs', 'reviewing API specifications', 'establishing API design standards'), but these are high-level categories rather than granular concrete actions, and 'intuitive, scalable, and maintainable APIs that delight developers' is buzzword padding. Not a 3 because the actions are abstract platitudes rather than specific concrete operations like the 'extract text, fill forms, merge documents' anchor; not a 1 because the domain and several actions are explicitly named.

2 / 3

Completeness

It explicitly answers both what ('Master REST and GraphQL API design principles to build... APIs') and when via an explicit 'Use when designing new APIs, reviewing API specifications, or establishing API design standards' trigger clause. Not a 2 because the 'when' is explicit rather than missing or implied, matching the 'Use when... PDFs, forms, or document extraction' anchor.

3 / 3

Trigger Term Quality

It includes relevant natural terms ('REST', 'GraphQL', 'API design', 'API specifications', 'API design standards') that users would say, but coverage is limited to a few phrases and omits common variations such as 'endpoints', 'API schema', 'REST vs GraphQL', or 'API documentation'. Not a 3 because it does not give good coverage of natural term variations; not a 1 because the terms present are natural rather than jargon.

2 / 3

Distinctiveness Conflict Risk

REST and GraphQL API design/review/standards is a clear, specific niche with distinct triggers unlikely to conflict with unrelated skills. Not a 2 because it is more specific than 'Works with document files'-style overlap; the scoped REST/GraphQL API-design framing keeps it distinct.

3 / 3

Total

10

/

12

Passed

Validation

100%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository
wshobson/agents
Reviewed

Table of Contents

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.