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.
62
44%
Does it follow best practices?
Impact
91%
1.03xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/data/02-architect-apidesign/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 aspirational buzzwords ('intuitive, scalable, maintainable, delight developers') instead of listing concrete capabilities, and it lacks the breadth of trigger terms that would help Claude reliably select it over related skills.
Suggestions
Replace vague aspirational language ('intuitive, scalable, and maintainable APIs that delight developers') with specific concrete actions like 'define resource naming conventions, design pagination and filtering, structure error responses, plan versioning strategies'.
Expand trigger terms in the 'Use when...' clause to include natural variations like 'endpoints', 'routes', 'OpenAPI spec', 'swagger', 'API versioning', 'error codes', or 'schema design'.
| 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 'error handling'. | 2 / 3 |
Distinctiveness Conflict Risk | The focus on REST and GraphQL API design is somewhat specific, but 'API design' could overlap with skills about backend development, microservices architecture, or general software architecture. The phrase 'delight developers' is fluff that doesn't help distinguish it. It could be more distinct by specifying concrete deliverables like naming conventions, status codes, or schema patterns. | 2 / 3 |
Total | 9 / 12 Passed |
Implementation
22%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill reads more like a tutorial or textbook chapter on API design than an actionable skill for Claude. It spends significant tokens explaining concepts Claude already knows (HTTP methods, REST principles, GraphQL basics) while lacking a clear design workflow or decision-making process. The code examples provide some value but are incomplete and the overall document is far too verbose for its purpose.
Suggestions
Remove the 'Core Concepts' section entirely — Claude already knows HTTP methods, REST principles, and GraphQL basics. Focus only on project-specific conventions or non-obvious design decisions.
Add a concrete, sequenced workflow for API design (e.g., 1. Gather requirements → 2. Define resources → 3. Design endpoints/schema → 4. Validate against checklist → 5. Generate OpenAPI spec) with explicit validation checkpoints.
Move the large code examples (pagination, error handling, GraphQL schema, DataLoader) into the referenced files (assets/ and references/) and keep only minimal, focused examples inline.
Replace the generic 'Best Practices' and 'Common Pitfalls' bullet lists with a concise decision table or checklist that Claude can apply during design reviews.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~400+ lines. Explains concepts Claude already knows well (HTTP method semantics, what REST resources are, what GraphQL queries/mutations/subscriptions are). The 'Core Concepts' section is almost entirely redundant knowledge. Best practices and common pitfalls sections are generic advice Claude doesn't need to be taught. | 1 / 3 |
Actionability | Contains concrete Python/GraphQL code examples that are mostly executable (FastAPI endpoints, Ariadne resolvers, DataLoader patterns). However, many examples depend on undefined helper functions (build_query, fetch_users, count_users, etc.), making them not truly copy-paste ready. The skill is more of a reference/teaching document than actionable instructions for a specific task. | 2 / 3 |
Workflow Clarity | There is no clear workflow or sequenced process for API design. The 'Interactive Design Process' section mentions clarifying requirements and feedback loops but provides no concrete steps. For a skill about designing APIs, there should be a clear design workflow (e.g., define resources → design endpoints → define schemas → validate → document), but none exists. | 1 / 3 |
Progressive Disclosure | The Resources section references external files (references/, assets/, scripts/) which is good progressive disclosure structure. However, the main body contains massive inline code blocks that could be split into referenced files, and the core concepts section that should be omitted entirely bloats the main file significantly. | 2 / 3 |
Total | 6 / 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 (534 lines); consider splitting into references/ and linking | Warning |
Total | 10 / 11 Passed | |
- Repository
- majiayu000/claude-skill-registry
- Commit
d156cd1
- 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.