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
94%
1.13xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./tests/ext_conformance/artifacts/agents-wshobson/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 that covers key scenarios, earning good marks for completeness. However, it relies on aspirational buzzwords ('delight developers', 'intuitive, scalable, and maintainable') instead of listing concrete actions, and it misses many natural trigger terms users would use when seeking API design help. The description would benefit from more specific capabilities and broader keyword coverage.
Suggestions
Replace vague aspirational language ('intuitive, scalable, and maintainable APIs that delight developers') with concrete actions like 'define resource naming, design pagination, structure error responses, plan versioning strategies'.
Add more natural trigger terms users would say, such as 'endpoints', 'OpenAPI', 'Swagger', 'API versioning', 'schema design', 'request/response format', '.yaml spec'.
| 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', 'API versioning', 'request/response format', or 'API documentation'. | 2 / 3 |
Distinctiveness Conflict Risk | The focus on REST and GraphQL API design is somewhat specific, but 'designing new APIs' and 'reviewing API specifications' could overlap with general coding skills, backend development skills, or architecture skills. The phrase 'delight developers' is fluffy and doesn't help distinguish it. | 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 like a comprehensive API design tutorial or textbook chapter rather than a concise skill file for Claude. It spends significant tokens explaining concepts Claude already knows (HTTP methods, REST principles, GraphQL basics) while lacking a clear workflow for actually applying these patterns during API design tasks. The code examples provide some value but are not fully executable and would be better placed in referenced files with the main skill providing a lean decision framework.
Suggestions
Remove the 'Core Concepts' section entirely—Claude already knows what REST, GraphQL, HTTP methods, and versioning strategies are. Replace with a brief decision framework for when to use REST vs GraphQL.
Add a clear sequential workflow for API design tasks (e.g., 1. Identify resources → 2. Define endpoints/schema → 3. Design error responses → 4. Review against checklist → 5. Validate with OpenAPI/schema introspection).
Move the detailed code examples (pagination, error handling, DataLoader, resolver patterns) into the referenced files (rest-best-practices.md, graphql-schema-design.md) and keep only minimal examples inline.
Add validation checkpoints to the workflow, such as 'Run the OpenAPI validator before proceeding' or 'Review schema against the api-design-checklist.md before implementing resolvers.'
| 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 'Core Concepts' section is almost entirely redundant knowledge. Lists like 'GET: Retrieve resources (idempotent, safe)' and 'Resources are nouns, not verbs' are textbook material Claude doesn't need. | 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 code is more illustrative than executable. | 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 guiding Claude through a design process. No validation checkpoints, no decision points for choosing between approaches, and no feedback loops for reviewing API designs. | 1 / 3 |
Progressive Disclosure | References to external files are listed at the end (references/, assets/, scripts/), which is good structure. However, the main file is a monolithic wall of content that should have much of its detail pushed into those referenced files. The inline code examples for pagination, error handling, HATEOAS, GraphQL schemas, resolvers, and DataLoaders could all be in separate reference files. | 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 (529 lines); consider splitting into references/ and linking | Warning |
Total | 10 / 11 Passed | |
- Repository
- Dicklesworthstone/pi_agent_rust
- Commit
dad585c
- 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.