tdg-personal/api-design
REST API design patterns including resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting for production APIs.
70
70%
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 excellent natural trigger terms that developers would use. Its main weakness is the absence of an explicit 'Use when...' clause, which limits Claude's ability to confidently select this skill over related ones. 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, implementing pagination or filtering, or structuring API error responses.'
Consider adding file type or context triggers like 'OpenAPI spec', 'Swagger', or 'API endpoint design' to further distinguish from general backend development skills.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions/topics: resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting. These are all concrete, well-defined aspects of REST API design. | 3 / 3 |
Completeness | Clearly answers 'what does this do' by listing specific REST API design patterns, but lacks an explicit 'Use when...' clause or equivalent trigger guidance. The 'when' is only implied by the domain context. | 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', and 'production APIs'. These cover a wide range of terms a developer would naturally use. | 3 / 3 |
Distinctiveness Conflict Risk | While 'REST API design patterns' is a fairly 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 is a thorough and highly actionable REST API design reference with excellent concrete examples across multiple languages and clear good/bad comparisons. However, it suffers from being a monolithic wall of content that includes much that Claude already knows (HTTP methods, basic status codes, auth patterns), and would benefit significantly from splitting into a concise overview with linked sub-documents for detailed topics like pagination strategies, implementation examples, and filtering patterns.
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.
Remove or drastically condense sections covering knowledge Claude already has (HTTP method semantics table, basic auth header format, standard status code definitions) — focus on the opinionated choices and patterns specific to this project.
Add a brief progressive disclosure structure: keep the URL structure, response format, and checklist in SKILL.md, and link out to separate files for pagination strategies, filtering patterns, and versioning details.
Add a validation/verification step to the workflow — e.g., 'After implementing, validate against OpenAPI spec' or 'Test with curl examples to verify status codes match expectations.'
| 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 after implementation or verifying API contract compliance. | 2 / 3 |
Progressive Disclosure | The entire skill is a monolithic document with no references to external files. The implementation examples in three languages, the detailed pagination section, and the filtering/sorting section could all be split into separate reference files. At ~300+ lines, this would greatly benefit from a concise overview with links to detailed sub-documents. | 1 / 3 |
Total | 8 / 12 Passed |
Validation
81%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 9 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
skill_md_line_count | SKILL.md is long (524 lines); consider splitting into references/ and linking | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 9 / 11 Passed | |
Reviewed
Table of Contents