rest-api-design
Designs RESTful APIs with proper resource naming, HTTP methods, status codes, and response formats. Use when building new APIs, establishing API conventions, or designing developer-friendly interfaces.
55
61%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./plugins/rest-api-design/skills/rest-api-design/SKILL.mdQuality
Discovery
85%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a well-crafted description that clearly communicates both what the skill does and when to use it. The specificity of capabilities (resource naming, HTTP methods, status codes, response formats) is strong, and the explicit 'Use when...' clause provides clear trigger guidance. The main weakness is that trigger terms could include more natural user variations like 'REST API', 'endpoints', or 'routes'.
Suggestions
Expand trigger terms to include common variations users might say, such as 'REST API', 'endpoints', 'routes', 'API schema', 'URL structure', or 'OpenAPI'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'proper resource naming, HTTP methods, status codes, and response formats' — these are distinct, concrete aspects of API design rather than vague language. | 3 / 3 |
Completeness | Clearly answers both 'what' (designs RESTful APIs with resource naming, HTTP methods, status codes, response formats) and 'when' (explicit 'Use when building new APIs, establishing API conventions, or designing developer-friendly interfaces'). | 3 / 3 |
Trigger Term Quality | Includes good terms like 'RESTful APIs', 'API conventions', and 'developer-friendly interfaces', but misses common user variations like 'REST API', 'endpoints', 'routes', 'API schema', or 'OpenAPI'. Coverage of natural terms is decent but not comprehensive. | 2 / 3 |
Distinctiveness Conflict Risk | The focus on RESTful API design with specific aspects like resource naming, HTTP methods, and status codes creates a clear niche that is unlikely to conflict with other skills like general coding or documentation skills. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
37%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill reads as a REST API cheat sheet covering conventions Claude already knows well (HTTP methods, status codes, resource naming). It lacks a design workflow or decision-making process that would add genuine value, and provides no executable implementation code. The content is well-structured but largely redundant for an LLM with strong existing knowledge of REST conventions.
Suggestions
Add a step-by-step workflow for designing an API: e.g., 1) identify resources, 2) define relationships, 3) choose response format, 4) document with OpenAPI — with validation checkpoints.
Focus content on non-obvious decisions and tradeoffs Claude might not default to correctly (e.g., when to use PUT vs PATCH, nested vs flat resources, error response conventions specific to the project).
Include executable code examples showing actual route handler implementations in a framework, rather than just URL pattern listings.
Remove or drastically condense the HTTP methods and status codes tables, as these are basic knowledge Claude already has — replace with project-specific conventions or edge cases.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is reasonably efficient but includes information Claude already knows well — HTTP methods, status codes, and basic REST conventions are foundational knowledge. The tables and examples are clean but largely redundant for Claude. | 2 / 3 |
Actionability | Provides concrete examples of URL patterns, response formats, and query parameters, but these are reference/convention examples rather than executable code. There are no actual implementation snippets (e.g., Express/Flask route handlers) that Claude could directly use when building an API. | 2 / 3 |
Workflow Clarity | There is no workflow or sequenced process for designing an API. The content is a reference sheet of conventions with no guidance on the order of steps, decision points, or how to apply these patterns when designing a new API from scratch. | 1 / 3 |
Progressive Disclosure | The content is organized into clear sections with good headers, but everything is inline in a single file with no references to deeper materials. For a conventions-focused skill this is acceptable but could benefit from linking to examples of error handling, authentication patterns, or OpenAPI spec templates. | 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.
- Repository
- secondsky/claude-skills
- Commit
5e92b71
- 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.