Content
38%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 skill body is lean and well-sectioned but hollow: the instructions are abstract headings with no concrete guidance, and its single pointer to detailed material targets a nonexistent path while all four real bundle files go unmentioned. Both actionability and progressive disclosure fail against the actual bundle structure.
Suggestions
Fix the broken reference: replace `resources/implementation-playbook.md` with pointers to the real bundle files (e.g., 'REST patterns: see references/rest-best-practices.md; GraphQL types: see references/graphql-schema-design.md; review checklist: see assets/api-design-checklist.md'), and list each file under Resources with a one-line description.
Ground the four instruction steps in concrete detail, e.g. 'Specify errors, versioning, pagination, and auth strategy — use the error-model and pagination patterns in references/rest-best-practices.md' or embed one concrete example (an error envelope or resource-naming rule) per step.
Delete the opening line that duplicates the frontmatter description, and state the playbook/bundle pointer once (either in Instructions or in Resources) to remove the duplication.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is short and assumes Claude's intelligence (no concept explanations), but it repeats the frontmatter description almost verbatim in the opening line ('Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers and stand the test of time') and the 'Use this skill when' bullets duplicate the description's triggers, plus the playbook reference is stated twice (Instructions and Resources). Anchor 3 ('mostly efficient but could be tightened') fits; not 4 because the duplication is systematic rather than a couple of stray instances, and not 2 because there is no padded concept explanation or filler beyond the duplication. | 3 / 5 |
Actionability | The Instructions are pure abstractions: 'Define consumers, use cases, and constraints', 'Choose API style and model resources or types', 'Specify errors, versioning, pagination, and auth strategy' — no concrete commands, code, examples, or specific patterns; everything actionable is deferred to `resources/implementation-playbook.md`. This matches anchor 2 ('minimal concrete guidance; high-level hints but missing the specific steps to execute'); not 1 because a coherent high-level outline with named concerns (errors, versioning, pagination, auth) is present, and not 3 because there is no concrete or executable detail anywhere in the body. | 2 / 5 |
Workflow Clarity | The four numbered steps form a recognizable design sequence, and step 4 ('Validate with examples and review for consistency') gestures at validation, but there are no checkpoints, criteria, or feedback loops for what to do when validation fails. Anchor 3 ('steps listed but validation gaps; checkpoints missing or implicit') is the best fit; not 4 because 'validate with examples' is too vague to count as a real checkpoint, and not 2 because the sequence is well-ordered with defined steps rather than gappy. | 3 / 5 |
Progressive Disclosure | Scored against the actual bundle: the body's only reference, `resources/implementation-playbook.md`, does not exist (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 detail content undiscoverable. This matches anchor 2's broken navigation ('minimal structure... references are buried'); not 1 because SKILL.md itself has clear sections and intended one-level-deep references rather than a monolith or nested chain, and not 3 because navigation to the actual detail files is impossible, not merely unclear. | 2 / 5 |
Total | 10 / 20 Passed |