tessl-labs/api-design-patterns
REST API design patterns — response envelopes, pagination, filtering, status codes, and resource naming
87
83%
Does it follow best practices?
Impact
98%
1.78xAverage score across 4 eval scenarios
Passed
No known issues
Quality
Discovery
85%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 is a strong skill description that clearly articulates specific capabilities (six distinct REST API patterns) and provides explicit trigger guidance. The main weakness is limited trigger term coverage - it relies heavily on 'REST API' without including common synonyms or related terms users might naturally use.
Suggestions
Add trigger term variations like 'web API', 'HTTP endpoints', 'routes', 'RESTful services', or 'API controllers' to improve discoverability
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'response envelopes, pagination, filtering, status codes, resource naming, and PATCH semantics' - these are all distinct, concrete API design concerns. | 3 / 3 |
Completeness | Clearly answers both what ('REST API design patterns — response envelopes, pagination...') and when ('Apply AUTOMATICALLY whenever building any REST API endpoints') with explicit trigger guidance. | 3 / 3 |
Trigger Term Quality | Includes 'REST API' and 'API endpoints' which are natural terms, but misses common variations users might say like 'web API', 'HTTP endpoints', 'routes', 'controllers', or specific frameworks. | 2 / 3 |
Distinctiveness Conflict Risk | Clear niche focused specifically on REST API design patterns with distinct technical triggers; unlikely to conflict with general coding skills or other API-related skills due to specific pattern enumeration. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
77%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a strong, actionable skill with excellent code examples and clear structure. The main weaknesses are verbosity (multiple WRONG/RIGHT examples per section, some explanatory text Claude doesn't need) and the monolithic structure that could benefit from splitting detailed patterns into separate reference files. The checklist and verifier references are valuable additions.
Suggestions
Reduce WRONG/RIGHT example pairs to one per pattern—Claude understands the contrast from a single comparison
Remove explanatory sentences like 'Unbounded list queries will eventually crash or timeout as data grows'—Claude knows this
Consider splitting detailed implementations (pagination, filtering, bulk operations) into separate reference files, keeping SKILL.md as a concise overview with links
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is comprehensive but includes some redundancy—multiple WRONG/RIGHT examples per section when one would suffice, and some explanatory text that Claude would already understand (e.g., explaining why unbounded queries are bad). Could be tightened by ~30%. | 2 / 3 |
Actionability | Excellent actionability with fully executable TypeScript code examples throughout. Every pattern includes copy-paste ready implementations with proper error handling, query building, and response formatting. | 3 / 3 |
Workflow Clarity | Clear structure with numbered sections, explicit rules after each pattern, and a comprehensive checklist at the end. The skill covers discrete patterns rather than multi-step workflows, but each pattern's implementation steps are unambiguous. | 3 / 3 |
Progressive Disclosure | Content is well-organized with clear sections and a checklist, but the skill is monolithic (~400 lines) with no references to external files for advanced topics. The verifiers section at the end suggests external files exist but aren't leveraged for progressive disclosure of detailed content. | 2 / 3 |
Total | 10 / 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 (537 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