jbvc/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.
58
58%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Quality
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 vague aspirational language ('delight developers', 'intuitive, scalable, and maintainable') instead of listing concrete capabilities, and its trigger terms could be broader to capture more natural user queries. The specificity of actions and trigger coverage would benefit from improvement.
Suggestions
Replace vague aspirational language ('delight developers', 'intuitive, scalable, and maintainable') with concrete actions like 'define resource naming conventions, design pagination and filtering, structure error responses, plan API versioning strategies'.
Expand trigger terms to include natural variations users would say: 'endpoints', 'routes', 'OpenAPI', 'Swagger', 'schema design', 'HTTP methods', 'API versioning', 'request/response format'.
| 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, backend development skills, or OpenAPI/Swagger-specific skills. The phrase 'delight developers' is fluffy and doesn't help differentiation. | 2 / 3 |
Total | 9 / 12 Passed |
Implementation
35%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is essentially a thin wrapper that defers all substantive content to an external playbook file. The SKILL.md itself provides no concrete, actionable guidance — no API naming conventions, no example endpoints, no error format patterns, no code snippets. While the structure is reasonable, the body content fails to give Claude enough information to act without the referenced resource.
Suggestions
Add concrete, executable examples directly in SKILL.md — e.g., a sample REST endpoint design with URL pattern, HTTP methods, request/response JSON, and error format.
Include at least 2-3 specific, actionable design rules inline (e.g., 'Use plural nouns for collection endpoints: /users not /user', 'Return 201 with Location header on resource creation') rather than only abstract steps.
Add a brief but concrete example of a GraphQL type/query design to complement the REST example, since the skill claims to cover both paradigms.
Expand the workflow steps with specific validation criteria — e.g., 'Validate: ensure every endpoint has documented error responses for 400, 401, 404, and 500 status codes.'
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The 'Use this skill when' and 'Do not use this skill when' sections are somewhat verbose and explain things Claude could infer. The instructions section itself is lean, but the overall content has padding that doesn't add actionable value. | 2 / 3 |
Actionability | The instructions are extremely vague — 'Define consumers, use cases, and constraints' and 'Choose API style and model resources or types' are abstract directions with no concrete examples, code snippets, naming conventions, URL patterns, or specific guidance. Everything actionable is deferred to an external file. | 1 / 3 |
Workflow Clarity | There is a numbered 4-step sequence which provides some structure, but the steps are too high-level to be truly useful. There are no validation checkpoints, no feedback loops, and no concrete criteria for when each step is complete. | 2 / 3 |
Progressive Disclosure | The skill references an external file (resources/implementation-playbook.md) for detailed content, which is appropriate progressive disclosure. However, the SKILL.md itself provides almost no substantive overview content — it's essentially just a pointer to another file with minimal standalone value. | 2 / 3 |
Total | 7 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
Reviewed
Table of Contents