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.
75
68%
Does it follow best practices?
Impact
Pending
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
100%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 skill description that clearly articulates specific capabilities (resource naming, HTTP methods, status codes, response formats), includes natural trigger terms users would employ, and explicitly states both what the skill does and when to use it. It uses proper third-person voice and is concise without being vague.
| 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. | 3 / 3 |
Completeness | Clearly answers both what ('Designs RESTful APIs with proper resource naming, HTTP methods, status codes, and response formats') and when ('Use when building new APIs, establishing API conventions, or designing developer-friendly interfaces') with explicit trigger guidance. | 3 / 3 |
Trigger Term Quality | Includes strong natural keywords users would say: 'RESTful APIs', 'API conventions', 'resource naming', 'HTTP methods', 'status codes', 'developer-friendly interfaces'. These cover common terms a user would use when requesting API design help. | 3 / 3 |
Distinctiveness Conflict Risk | Clearly scoped to RESTful API design specifically — the combination of resource naming, HTTP methods, status codes, and response formats creates a distinct niche unlikely to conflict with general coding or other skills. | 3 / 3 |
Total | 12 / 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 showing how to apply these conventions when building a new API, and provides no executable implementation code. The content would benefit from focusing on opinionated decisions and project-specific conventions rather than restating widely-known REST standards.
Suggestions
Add a step-by-step workflow for designing an API: e.g., 1) Identify resources, 2) Define relationships, 3) Design endpoints, 4) Define response schemas, 5) Validate with OpenAPI spec
Remove or drastically condense the HTTP methods and status codes tables since Claude already knows these; focus instead on opinionated choices (e.g., when to use PUT vs PATCH, when 422 vs 400)
Add executable code examples showing how to implement these patterns in at least one framework (e.g., Express, FastAPI) to make the skill actionable
Include an error response format example and guidance on consistent error handling, which is a common pain point in API design
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is mostly efficient with good use of tables and examples, but includes information Claude already knows well (HTTP methods, status codes, basic REST conventions). This is essentially a reference card for widely-known REST standards rather than novel guidance. | 2 / 3 |
Actionability | Provides concrete examples of URL patterns, response formats, and query parameters, but lacks executable code for actually implementing an API (e.g., route handlers, middleware). The examples are illustrative rather than copy-paste ready for building something. | 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 how to apply them step-by-step when designing a new API, no decision points, and no validation steps. | 1 / 3 |
Progressive Disclosure | The content is reasonably organized with clear section headers, but it's a monolithic file with no references to deeper materials (e.g., authentication patterns, error handling guide, OpenAPI spec examples). Some sections like response format could benefit from linking to more detailed examples. | 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.
88da5ff
Table of Contents
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.