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 is well-structured and token-efficient with sensible use/anti-use sections, but it provides almost no actionable design guidance and its progressive disclosure is broken: the single referenced file does not exist and the four real bundle files are never linked. Fixing the reference path and adding concrete guidance would lift both the actionability and navigation substantially.
Suggestions
Fix the broken reference: replace 'resources/implementation-playbook.md' with the actual bundle files (references/rest-best-practices.md, references/graphql-schema-design.md, assets/api-design-checklist.md, assets/rest-api-template.py), each with a one-line description of when to consult it.
Add concrete actionable guidance to the Instructions (e.g., naming rules like 'plural nouns for resources', an error envelope example, cursor vs offset pagination guidance) instead of four abstract one-liners.
Make step 4's validation explicit — what to check (naming consistency, error coverage, auth on every endpoint) and how to iterate when the review fails — and drop the duplicated playbook pointer or the verbatim description repetition.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean with no explanation of concepts Claude already knows, but the opening sentence duplicates the frontmatter description verbatim and the playbook pointer is stated twice (in Instructions and Resources). Not 5 because those redundancies are tokens that could be trimmed. | 4 / 5 |
Actionability | The four instructions ('Define consumers, use cases, and constraints', 'Choose API style and model resources or types', etc.) are high-level hints with no concrete examples, naming conventions, or commands — all specifics are deferred to a reference file. Not 3 because nothing in the body itself is concretely executable; not 1 because the numbered sequence still gives minimal direction. | 2 / 5 |
Workflow Clarity | A clear four-step sequence is present, but the only validation ('Validate with examples and review for consistency') is implicit with no checkpoints or feedback loop for how to validate or what to do on failure. Not 4 because checkpoints are missing entirely, not just minor gaps. | 3 / 5 |
Progressive Disclosure | The only reference, 'resources/implementation-playbook.md', does not exist — there is no resources/ directory — while the four real bundle files (references/rest-best-practices.md, references/graphql-schema-design.md, assets/api-design-checklist.md, assets/rest-api-template.py) are never mentioned, leaving the actual detailed content unreachable from SKILL.md. This matches 'references are buried/broken' minimal structure; not 3 because the structure fails to navigate to any real content, which is worse than weakly-signaled but present references. | 2 / 5 |
Total | 11 / 20 Passed |