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 clearly communicates trigger scenarios, which is its strongest aspect. However, it relies on vague aspirational language ('delight developers') instead of listing concrete actions, and its trigger terms could be broader to capture more natural user queries. The specificity of capabilities would benefit from enumerating concrete design tasks rather than using marketing-style adjectives.
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'.
Expand trigger terms to include common variations users would naturally say, such as 'endpoints', 'OpenAPI', 'Swagger', 'HTTP methods', 'schema design', 'API versioning', or 'route 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 '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 or backend development skills. The phrase 'Master REST and GraphQL API design principles' is somewhat distinctive but could still conflict with broader web development or backend skills. | 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 comprehensive API design tutorial or textbook chapter than a focused skill for Claude. It is extremely verbose, spending significant tokens explaining concepts Claude already knows (HTTP methods, REST principles, GraphQL basics) while lacking a clear actionable workflow for when Claude needs to design or review an API. The code examples are decent but illustrative rather than executable, and the massive inline content should be distributed across the referenced files.
Suggestions
Drastically reduce the SKILL.md to a concise overview (~50-80 lines) with a clear step-by-step API design workflow (e.g., 1. Identify resources, 2. Define endpoints/schema, 3. Validate against checklist, 4. Review error handling), and move detailed patterns into the referenced files.
Remove all explanations of concepts Claude already knows (HTTP method semantics, what REST/GraphQL are, basic principles) and focus only on project-specific conventions or non-obvious decisions.
Add an explicit design review workflow with validation checkpoints, such as a checklist to verify before finalizing an API design (e.g., 'Verify pagination on all collection endpoints', 'Confirm error response format consistency').
Make code examples either fully executable with all dependencies defined, or replace them with concise references to the template files listed in Resources.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~400+ lines. Explains basic concepts Claude already knows (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 already possesses. | 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 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 skill presents patterns and best practices but never guides Claude through a step-by-step API design process with validation checkpoints. For a skill about 'designing new APIs' or 'reviewing API specifications,' there should be a clear design workflow with review/validation steps. | 1 / 3 |
Progressive Disclosure | The Resources section at the end references external files appropriately, but the main body is a monolithic wall of content that should have been split across those referenced files. The inline content is far too long for a SKILL.md overview — the detailed patterns (pagination, error handling, HATEOAS, DataLoader) belong in the referenced files, not the main skill. | 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
6e3d68c
- 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.