jbvc/api-design
REST API design patterns including resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting for production APIs.
72
72%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Quality
Discovery
75%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 excels at listing specific, concrete capabilities with strong natural trigger terms that developers would use. Its main weakness is the absence of an explicit 'Use when...' clause, which would help Claude distinguish when to select this skill versus other API-related or backend development skills. Adding trigger guidance would elevate this from a good description to an excellent one.
Suggestions
Add a 'Use when...' clause such as 'Use when designing REST APIs, choosing HTTP status codes, structuring API endpoints, or implementing pagination/filtering patterns.'
Include boundary language to reduce overlap, e.g., 'Not for GraphQL APIs, WebSocket protocols, or API client/SDK implementation.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions/topics: resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting. These are clearly defined, actionable areas of REST API design. | 3 / 3 |
Completeness | Clearly answers 'what does this do' by listing REST API design patterns and specific subtopics, but lacks an explicit 'Use when...' clause or equivalent trigger guidance, which caps this dimension at 2 per the rubric. | 2 / 3 |
Trigger Term Quality | Includes strong natural keywords users would say: 'REST API', 'resource naming', 'status codes', 'pagination', 'filtering', 'error responses', 'versioning', 'rate limiting', 'production APIs'. These are terms developers naturally use when seeking API design guidance. | 3 / 3 |
Distinctiveness Conflict Risk | While 'REST API design patterns' is a reasonably specific niche, it could overlap with general API development skills, backend development skills, or web framework skills. The lack of explicit trigger boundaries increases potential conflict with adjacent skills. | 2 / 3 |
Total | 10 / 12 Passed |
Implementation
57%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is highly actionable with excellent concrete examples across multiple languages and clear good/bad comparisons. However, it suffers from being a monolithic document that includes substantial content Claude already knows (HTTP methods, basic status codes, auth patterns) and would benefit significantly from splitting into a concise overview with references to detailed sub-files for implementation patterns, pagination strategies, and language-specific examples.
Suggestions
Split implementation examples (TypeScript, Python, Go) into a separate IMPLEMENTATIONS.md file and reference it from the main skill, keeping only one example inline.
Move detailed pagination, filtering/sorting, and rate limiting sections into separate reference files (e.g., PAGINATION.md, FILTERING.md) with brief summaries in the main skill.
Remove or drastically condense the HTTP methods table and basic status code reference — Claude already knows these. Focus only on the 'Common Mistakes' section which adds genuine value.
Add a validation/review workflow with explicit checkpoints, e.g., 'After designing endpoints: 1. Validate against checklist 2. Generate OpenAPI spec 3. Review for breaking changes against existing API'.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is comprehensive but overly long for what Claude already knows about REST API design. The HTTP methods table, basic auth patterns, and much of the status code reference are common knowledge. The multi-language implementation examples (TypeScript, Python, Go) add significant length and could be trimmed or moved to separate files. | 2 / 3 |
Actionability | The skill provides fully executable code examples across three languages, concrete URL patterns with good/bad comparisons, specific SQL queries for pagination implementations, and copy-paste ready response JSON schemas. Every section contains concrete, actionable guidance. | 3 / 3 |
Workflow Clarity | The checklist at the end provides a good sequence for shipping endpoints, and the versioning strategy has a clear numbered process. However, there are no validation checkpoints or feedback loops for the design process itself — e.g., no guidance on testing endpoints, validating OpenAPI specs, or iterating on API contracts before shipping. | 2 / 3 |
Progressive Disclosure | This is a monolithic wall of text at ~350+ lines with no references to external files. The implementation examples in three languages, the detailed pagination section, and the filtering/sorting patterns could all be split into separate reference files. Everything is inline with no navigation structure beyond headings. | 1 / 3 |
Total | 8 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
skill_md_line_count | SKILL.md is long (523 lines); consider splitting into references/ and linking | Warning |
Total | 10 / 11 Passed | |
Reviewed
Table of Contents