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.
92
88%
Does it follow best practices?
Impact
100%
1.09xAverage score across 3 eval scenarios
Passed
No known issues
Quality
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 skill description that clearly articulates specific capabilities and provides explicit usage triggers. The main weakness is moderate trigger term coverage - while it captures the core terminology, it could benefit from additional natural variations users might employ when requesting API design help.
Suggestions
Add common trigger term variations like 'REST API', 'endpoints', 'routes', 'API schema', or 'OpenAPI' to improve discoverability
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'proper resource naming, HTTP methods, status codes, and response formats' - these are distinct, actionable capabilities in 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'). | 3 / 3 |
Trigger Term Quality | Includes good terms like 'RESTful APIs', 'API conventions', and 'developer-friendly interfaces', but misses common variations users might say like 'REST API', 'endpoints', 'routes', 'API schema', or 'OpenAPI'. | 2 / 3 |
Distinctiveness Conflict Risk | Clear niche focused specifically on RESTful API design with distinct triggers; unlikely to conflict with general coding skills or other document/data skills. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
92%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a strong, well-crafted reference skill that efficiently covers REST API design conventions. It excels at conciseness and actionability through concrete examples and tables. The only minor weakness is the lack of references to extended documentation for topics like OpenAPI/Swagger that are mentioned but not elaborated.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely lean and efficient. No unnecessary explanations of what REST is or why conventions matter. Every section delivers actionable information through examples and tables without padding. | 3 / 3 |
Actionability | Provides concrete, copy-paste ready examples throughout: actual URL patterns, complete JSON response structures, query parameter syntax. The good/bad comparison for resource naming is immediately applicable. | 3 / 3 |
Workflow Clarity | For a reference/convention skill (not a multi-step process), the organization is clear and logical. Sections flow naturally from naming → methods → status codes → response formats. No destructive operations requiring validation checkpoints. | 3 / 3 |
Progressive Disclosure | Content is well-organized with clear sections, but everything is inline in one file. For a skill of this size (~80 lines), this is acceptable, but the 'Best Practices' section mentions OpenAPI/Swagger without linking to examples or further documentation. | 2 / 3 |
Total | 11 / 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
90d6bd7
- 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.