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 the domain clearly, but it leans toward aspirational language ('delight developers') rather than concrete capabilities. The specificity of actions and trigger term coverage could be improved to better distinguish this skill and help Claude select it accurately.
Suggestions
Replace vague aspirational language ('delight developers') with specific concrete actions like 'define resource naming, structure error responses, design pagination, plan versioning strategies'.
Expand trigger terms to include common user phrases and file types: 'OpenAPI', 'Swagger', 'endpoints', 'routes', 'API versioning', 'schema design', '.yaml spec files'.
| 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 these are fairly high-level and lack concrete specific actions like 'define resource naming conventions, structure error responses, design pagination schemes'. | 2 / 3 |
Completeness | Clearly answers both 'what' (REST and GraphQL API design principles for building intuitive, scalable, maintainable APIs) 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 relevant keywords like 'REST', 'GraphQL', 'API design', 'API specifications', and 'API design standards', but misses common user variations like 'endpoints', 'routes', 'OpenAPI', 'Swagger', 'schema design', 'versioning', or 'API documentation'. | 2 / 3 |
Distinctiveness Conflict Risk | The focus on API design principles is somewhat specific, but 'REST' and 'GraphQL' are broad enough that this could overlap with skills focused on API implementation, backend development, or general software architecture. The description doesn't carve out a sufficiently narrow niche. | 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 is an extensive API design reference document rather than an efficient, actionable skill for Claude. It spends significant tokens explaining concepts Claude already knows (HTTP methods, REST principles, what GraphQL is) while lacking a clear design workflow. The code examples are illustrative but not fully executable, and the referenced bundle files don't exist.
Suggestions
Drastically reduce content by removing explanations of concepts Claude already knows (HTTP method semantics, what REST/GraphQL are, basic best practices) and focus only on project-specific conventions or non-obvious patterns.
Add a clear, sequenced workflow for API design (e.g., 1. Gather requirements → 2. Choose paradigm → 3. Design resource model → 4. Define endpoints/schema → 5. Validate against checklist → 6. Generate documentation) with explicit validation checkpoints.
Move the detailed code patterns into separate referenced files (e.g., rest-patterns.md, graphql-patterns.md) and keep SKILL.md as a concise overview with navigation links.
Either create the referenced bundle files (rest-best-practices.md, api-design-checklist.md, etc.) or remove the references to avoid pointing to non-existent resources.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~400+ lines. Explains basic concepts Claude already knows well (REST methods, what resources are, HTTP status codes, what GraphQL is). The 'When to Use This Skill' section with 7 bullet points, the 'Core Concepts' section explaining GET/POST/PUT/PATCH/DELETE semantics, and the 'Common Pitfalls' list of well-known API design advice all waste tokens on knowledge Claude already possesses. | 1 / 3 |
Actionability | Contains concrete Python/GraphQL code examples that are mostly executable (FastAPI endpoints, Pydantic models, Ariadne resolvers, DataLoaders), but many rely on undefined helper functions (build_query, fetch_users, count_users, etc.) making them not truly copy-paste ready. The skill reads more like a tutorial/reference than actionable instructions for Claude to follow when designing APIs. | 2 / 3 |
Workflow Clarity | There is no clear workflow or sequenced process for API design. The content is organized as a reference catalog of patterns rather than a step-by-step design process. The 'Interactive Design Process' section mentions clarifying requirements and feedback loops but provides no concrete sequence. For a skill about 'designing APIs,' there should be a clear workflow: gather requirements → choose paradigm → design resources/schema → validate → document. | 1 / 3 |
Progressive Disclosure | References to external files (references/rest-best-practices.md, assets/rest-api-template.py, scripts/openapi-generator.py, etc.) are listed in a Resources section, but none of these files exist in the bundle. The main content is a monolithic wall of patterns and examples that could benefit from being split into separate files, with the SKILL.md serving as a concise overview. | 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
eb39638
- 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.