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 the domain clearly. However, it relies on somewhat high-level language and buzzwords ('delight developers', 'scalable and maintainable') rather than listing concrete, specific actions. Adding more specific capabilities and natural trigger terms would strengthen it.
Suggestions
Replace vague qualifiers like 'intuitive, scalable, and maintainable APIs that delight developers' with concrete actions such as 'define resource naming, design pagination, structure error responses, plan versioning strategies'.
Expand trigger terms to include common user phrases like 'endpoints', 'OpenAPI', 'swagger', 'API versioning', 'schema design', 'REST endpoints', '.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 these are fairly high-level and don't list 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 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 REST and GraphQL API design is somewhat specific, but 'API design' could overlap with skills related to backend development, microservices architecture, or general software architecture. The phrase 'that delight developers' is vague fluff that doesn't aid distinctiveness. | 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 spends significant tokens explaining concepts Claude already knows (HTTP methods, REST principles, GraphQL basics) while lacking a clear workflow for actually applying these principles. The content would benefit enormously from being condensed to decision-relevant guidance and split across referenced files.
Suggestions
Remove all explanations of basic concepts Claude already knows (HTTP method semantics, what REST/GraphQL are, what resources/queries/mutations are) and focus only on project-specific conventions or non-obvious design decisions.
Add a clear workflow: e.g., '1. Identify resources → 2. Define endpoints/schema → 3. Design error responses → 4. Add pagination → 5. Review against checklist' with validation steps at each stage.
Split content into separate files (e.g., REST_PATTERNS.md, GRAPHQL_PATTERNS.md, ERROR_HANDLING.md) and keep SKILL.md as a concise overview with navigation links.
Make code examples fully executable by either providing complete working examples or explicitly noting which functions need implementation, rather than referencing undefined helpers like build_query() and fetch_users().
| 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. | 1 / 3 |
Actionability | Contains concrete Python/GraphQL code examples that are mostly executable (FastAPI endpoints, Ariadne resolvers, DataLoader patterns), but many rely 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 any step-by-step guidance on how to approach API design, review an API spec, or migrate between paradigms. No validation checkpoints or decision points are provided. | 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 single skill file. REST patterns, GraphQL patterns, best practices, and common pitfalls could all be separate referenced documents. | 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
70444e5
- 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.