Content
46%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The body contains genuinely useful, largely executable REST/GraphQL design patterns, but it violates progressive disclosure severely: it inlines a full design guide while pointing to seven bundle files that do not exist, and it spends much of its length on concepts and boilerplate Claude already knows. Converting it into a lean overview with a sequenced design workflow and real companion files would address its core weaknesses.
Suggestions
Either create the seven referenced bundle files (references/, assets/, scripts/) or remove the dangling Resources section; currently every cited path is broken.
Cut the SKILL.md body to a lean overview: move the full pattern implementations into the reference/asset files and drop basic-concept explanations (HTTP method semantics, HATEOAS primer) that Claude already knows.
Replace the pattern catalog with a sequenced design workflow — e.g., identify resources → define schema → choose versioning strategy → validate against a checklist — with an explicit validation checkpoint step referencing a real checklist file.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | At 527 lines the body inlines large amounts of material Claude already knows — HTTP method semantics ('GET: Retrieve resources (idempotent, safe)'), a HATEOAS primer, full pagination/resolver/DataLoader implementations — plus aspirational padding ('APIs that delight developers and stand the test of time'). This matches anchor 2 (noticeably verbose, several unnecessary explanations); not 1 because the prose is structured rather than padded, and not 3 because the bloat is pervasive, not a few trimmable spots. | 2 / 5 |
Actionability | Mostly executable, concrete guidance: complete FastAPI pagination and error-handling endpoints, a full GraphQL schema, ariadne resolvers, and DataLoader classes. Minor gaps keep it below anchor 5 — undefined helpers (fetch_users, build_query, encode_cursor, hash_password, paginate_orders), missing imports (Any, ValidationError), and a bare @app.get('/api/users/{user_id}') example without its route decorator context. | 4 / 5 |
Workflow Clarity | The body is a pattern catalog, not a workflow: sections are organized by topic, but there is no sequenced design process (e.g., identify resources → define schema → version → validate against checklist) and no validation checkpoints. The one artifact that would act as a checkpoint (assets/api-design-checklist.md) is referenced but missing. This matches anchor 3 (content present but checkpoints/sequence missing); not 2 because the section structure is coherent and navigable. | 3 / 5 |
Progressive Disclosure | The Resources section cites seven bundle files (references/rest-best-practices.md, assets/rest-api-template.py, scripts/openapi-generator.py, etc.), but no references/, assets/, or scripts/ directories exist — every reference is dangling. Meanwhile ~450 lines of pattern content that clearly belongs in those files is inlined in SKILL.md itself. This matches anchor 2 (content that belongs in separate files is inlined, references broken); not 1 because section headers provide real navigation, and not 3 because the references are not merely under-signaled — they are nonexistent. | 2 / 5 |
Total | 11 / 20 Passed |