jbvc/api-design
REST API design patterns including resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting for production APIs.
58
73%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Quality
Discovery
82%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 description excels at specificity and trigger term coverage, listing seven concrete REST API design topics that align well with natural developer language. Its main weakness is the absence of an explicit 'Use when...' clause, which would help Claude know precisely when to select this skill over others. Adding trigger guidance would elevate this from a good to excellent description.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when the user asks about designing REST APIs, choosing HTTP status codes, structuring API endpoints, or implementing pagination/filtering.'
Consider adding file format or technology triggers like 'OpenAPI', 'Swagger', or 'HTTP endpoints' to capture additional natural user phrasing.
| 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' with the list of REST API design patterns, but lacks an explicit 'Use when...' clause or equivalent trigger guidance. The 'when' is only implied by the topic itself. | 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 | Clearly scoped to REST API design patterns specifically, with distinct triggers like 'resource naming', 'status codes', 'pagination', and 'rate limiting' that are unlikely to conflict with other skills. The niche is well-defined. | 3 / 3 |
Total | 11 / 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 is a thorough and highly actionable API design reference with excellent concrete examples across multiple languages and patterns. However, it suffers from being a monolithic document that tries to cover everything inline — the three full implementation examples, detailed pagination strategies, and auth patterns significantly inflate token cost. The content would benefit greatly from splitting into focused reference files with the SKILL.md serving as a concise overview.
Suggestions
Split implementation examples (TypeScript, Python, Go) into a separate IMPLEMENTATIONS.md file and reference it from the main skill, keeping at most one inline example.
Move detailed pagination, filtering, and rate limiting sections into separate reference files (e.g., PAGINATION.md, FILTERING.md) with brief summaries and links in the main SKILL.md.
Trim content Claude already knows well — the HTTP methods table, basic auth header examples, and explanations of what status codes mean can be reduced to just the decision-relevant parts (e.g., when to use 422 vs 400).
Add a brief workflow section that guides through the API design process (e.g., 1. Define resources → 2. Design URLs → 3. Define schemas → 4. Validate against checklist) with explicit review steps.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is comprehensive but overly long (~350+ lines). Some sections like the method semantics table, authentication patterns, and three full implementation examples in different languages add significant token cost. Claude already knows HTTP methods, status codes, and basic auth patterns. The three language-specific implementations could be trimmed to one or referenced externally. | 2 / 3 |
Actionability | Highly actionable with concrete URL patterns, exact status codes, complete JSON response schemas, executable code in TypeScript/Python/Go, specific query parameter syntax for filtering/sorting/pagination, and a ready-to-use checklist. Everything is copy-paste ready and specific. | 3 / 3 |
Workflow Clarity | The checklist at the end provides a good sequence for shipping endpoints, but there are no explicit validation checkpoints or feedback loops. For a design patterns skill (not a destructive operation), this is less critical, but the skill doesn't guide through the process of iterating on API design — it's more of a reference than a workflow. | 2 / 3 |
Progressive Disclosure | This is a monolithic wall of content with no references to external files. The implementation examples in three languages, pagination strategies, filtering patterns, auth patterns, rate limiting, and versioning could all be split into separate reference files. Everything is inline in one large document with no navigation structure beyond headers. | 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