api-design
REST API design patterns including resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting for production APIs.
75
66%
Does it follow best practices?
Impact
94%
1.30xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/api-design/SKILL.mdQuality
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 boundary language to reduce overlap with general backend/web development skills, e.g., 'Not for GraphQL, gRPC, or WebSocket patterns.'
| 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 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 REST API design reference with excellent actionability—concrete examples, good/bad comparisons, and executable code in multiple languages. However, it suffers from being too comprehensive for a single SKILL.md file, including much that Claude already knows (HTTP method semantics, basic status codes), and lacking any progressive disclosure through external file references. The content would benefit significantly from trimming common knowledge and splitting detailed sections into linked reference files.
Suggestions
Move the multi-language implementation examples (TypeScript, Python, Go) into a separate IMPLEMENTATIONS.md file and link to it from the main skill.
Remove or drastically condense the HTTP methods table and basic status codes—Claude already knows these. Focus only on the 'Common Mistakes' section which adds unique value.
Split pagination, filtering/sorting, and rate limiting into separate reference files (e.g., PAGINATION.md, FILTERING.md) with brief summaries and links in the main skill.
Add a concise 'Quick Reference' section at the top summarizing the key conventions (URL format, response envelope, error format) so Claude can get the essentials without reading the full document.
| 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 schemas. Every section contains concrete, actionable guidance. | 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 adequate but the versioning strategy section has a clear numbered sequence which helps. The skill is more reference-oriented than workflow-oriented. | 2 / 3 |
Progressive Disclosure | This is a monolithic wall of content with no references to external files. At ~350+ lines, the pagination details, multi-language implementations, and detailed filtering patterns should be split into separate reference files. Everything is inline with no navigation structure beyond section headers. | 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 | |
- Repository
- affaan-m/everything-claude-code
- Commit
5df943e
- 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.