Content
0%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill reads like a generic API design tutorial rather than an actionable skill for Claude. It is filled with concepts Claude already knows (HTTP methods, REST principles, GraphQL basics), lacks any concrete code examples or executable templates, and provides no workflow for actually designing an API. The single external reference points to a file that doesn't exist in the bundle.
Suggestions
Replace the explanatory content (HTTP methods, what REST/GraphQL are) with concrete, executable examples: e.g., a complete OpenAPI spec snippet for a well-designed endpoint, a GraphQL schema example with proper pagination and error handling.
Add a clear step-by-step workflow for API design tasks (e.g., 1. Define resources → 2. Draft endpoint schema → 3. Validate against checklist → 4. Generate OpenAPI spec) with validation checkpoints.
Remove or create the referenced 'references/details.md' file, and ensure any cross-references point to actual bundle files with substantive content.
Cut at least 60% of the content that restates common knowledge (HTTP method semantics, 'use plural nouns', 'APIs without limits are vulnerable') and replace with project-specific patterns, decision frameworks, or copy-paste-ready templates.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is verbose and explains many concepts Claude already knows well—HTTP method semantics, what REST resources are, what GraphQL queries/mutations/subscriptions do, basic best practices like 'use HTTP status codes correctly,' and common pitfalls that are general knowledge. The 'When to Use This Skill' section is also padded. Very little here adds novel, actionable knowledge. | 1 / 3 |
Actionability | The skill provides abstract descriptions and general advice rather than concrete, executable guidance. There are no real code examples, no API design templates, no executable commands, and no specific patterns to follow. Statements like 'Use plural nouns for collections' and 'Always paginate large collections' are vague directions without showing how. | 1 / 3 |
Workflow Clarity | There is no clear multi-step workflow for designing an API. The content is organized as a reference list of principles and best practices without any sequenced process, validation checkpoints, or decision points that would guide Claude through an actual API design task. | 1 / 3 |
Progressive Disclosure | The skill references 'references/details.md' for detailed patterns, but no bundle files are provided, making this a dead reference. The main content is a monolithic wall of general knowledge with no meaningful structure separating overview from detail. The reference to a non-existent file is worse than having no reference at all. | 1 / 3 |
Total | 4 / 12 Passed |