rest-api-design
tessl i github:secondsky/claude-skills --skill rest-api-designDesigns 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.
Validation
81%| Criteria | Description | Result |
|---|---|---|
metadata_version | 'metadata' field is not a dictionary | Warning |
license_field | 'license' field is missing | Warning |
body_steps | No step-by-step structure detected (no ordered list); consider adding a simple workflow | Warning |
Total | 13 / 16 Passed | |
Implementation
92%This is a strong, well-crafted skill that efficiently delivers REST API design conventions through concrete examples and clear tables. It respects Claude's intelligence by avoiding explanatory fluff and focuses on actionable patterns. Minor improvement could come from linking to extended examples or OpenAPI templates for teams wanting deeper guidance.
| 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 a separate reference file. | 2 / 3 |
Total | 11 / 12 Passed |
Activation
85%This is a well-crafted skill description that clearly articulates specific capabilities and 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 |
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.