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.
72
41%
Does it follow best practices?
Impact
93%
1.13xAverage score across 6 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./plugins/backend-development/skills/api-design-principles/SKILL.mdQuality
Discovery
67%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 has a solid structure with an explicit 'Use when...' clause and identifies its domain clearly (REST and GraphQL API design). However, it relies on vague aspirational language ('delight developers', 'intuitive, scalable, and maintainable') instead of listing concrete capabilities, and its trigger terms could be broader to capture more natural user queries. The specificity of actions and trigger coverage would benefit from improvement.
Suggestions
Replace vague aspirational language ('delight developers', 'intuitive, scalable, and maintainable') with concrete actions like 'define resource naming conventions, design pagination and filtering, structure error responses, plan API versioning strategies'.
Expand trigger terms to include natural variations users would say: 'endpoints', 'routes', 'OpenAPI', 'Swagger', 'schema design', 'HTTP methods', 'API versioning', 'request/response format'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (REST and GraphQL API design) and mentions some actions ('designing new APIs, reviewing API specifications, establishing API design standards'), but the core description uses vague aspirational language ('intuitive, scalable, and maintainable APIs that delight developers') rather than listing concrete specific actions like 'define resource naming conventions, design pagination schemes, structure error responses'. | 2 / 3 |
Completeness | Clearly answers both 'what' (REST and GraphQL API design principles) and 'when' with an explicit 'Use when...' clause covering three trigger scenarios: designing new APIs, reviewing API specifications, or establishing API design standards. | 3 / 3 |
Trigger Term Quality | Includes some relevant keywords like 'REST', 'GraphQL', 'API design', 'API specifications', and 'API design standards', but misses common natural variations users might say such as 'endpoints', 'routes', 'OpenAPI', 'Swagger', 'schema design', 'versioning', 'pagination', or 'HTTP methods'. | 2 / 3 |
Distinctiveness Conflict Risk | The focus on API design principles for REST and GraphQL provides some distinctiveness, but 'designing new APIs' and 'reviewing API specifications' could overlap with general coding skills, backend development skills, or OpenAPI/Swagger-specific skills. The phrase 'delight developers' is fluffy and doesn't help differentiation. | 2 / 3 |
Total | 9 / 12 Passed |
Implementation
14%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill reads like a tutorial or reference guide rather than an actionable skill for Claude. It is extremely verbose, explaining fundamental concepts Claude already knows (HTTP methods, REST principles, GraphQL basics), while lacking a clear workflow for actually designing an API. The content would benefit enormously from being condensed to a concise overview with references to detailed pattern files.
Suggestions
Reduce the SKILL.md to a concise overview (~50-80 lines) with a clear decision workflow (e.g., 1. Identify resources 2. Choose paradigm 3. Design endpoints/schema 4. Define error handling 5. Add pagination), and move detailed patterns into separate referenced files like REST_PATTERNS.md and GRAPHQL_PATTERNS.md.
Remove all explanations of concepts Claude already knows: HTTP method semantics, what REST resources are, what GraphQL queries/mutations/subscriptions are, and basic best practices like 'use plural nouns' or 'use HTTP status codes correctly'.
Add a clear decision framework or workflow for when to choose REST vs GraphQL, and a step-by-step API design process with validation checkpoints (e.g., 'validate schema against OpenAPI spec before implementing').
Make code examples either fully executable with all dependencies shown, or replace with specific command/tool invocations rather than patterns relying on undefined helper functions.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~400+ lines. Explains basic concepts Claude already knows (what HTTP methods mean, what REST resources are, what GraphQL queries/mutations/subscriptions are). The 'When to Use This Skill' section, 'Core Concepts' explaining REST and GraphQL fundamentals, and bullet-point best practices are all padding that adds no novel knowledge for Claude. | 1 / 3 |
Actionability | Contains concrete Python/FastAPI code examples and GraphQL schema definitions that are mostly executable, but many rely on undefined helper functions (build_query, fetch_users, count_users, etc.) making them not truly copy-paste ready. The code serves more as illustrative patterns than executable guidance. | 2 / 3 |
Workflow Clarity | There is no clear workflow or sequenced process for designing an API. The content is a reference dump of patterns and best practices without any step-by-step process, validation checkpoints, or decision framework for when to apply which pattern. For an API design skill, there should be a clear workflow: gather requirements → choose paradigm → design resources/schema → validate → document. | 1 / 3 |
Progressive Disclosure | Monolithic wall of text with no references to external files. All content is inline despite being far too long for a SKILL.md overview. REST patterns, GraphQL patterns, DataLoader examples, and best practices should each be in separate referenced files. | 1 / 3 |
Total | 5 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
skill_md_line_count | SKILL.md is long (519 lines); consider splitting into references/ and linking | Warning |
Total | 10 / 11 Passed | |
- Repository
- wshobson/agents
- Commit
91fe43e
- 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.