Content
70%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 tool-facing half of this skill is excellent — executable commands, gated thresholds, and a rigorous re-run review loop. The reference half works against it: hundreds of lines of textbook REST knowledge are inlined while the two purpose-built reference files in the bundle go unmentioned. Converting the inlined reference material into links to the existing files would fix both the token bloat and the orphaned references at once.
Suggestions
Link the existing references/ files from SKILL.md (e.g. under a '## References' section: 'REST design rules: See references/rest_design_rules.md; Anti-pattern catalog: See references/api_antipatterns.md') — they are currently orphaned and undiscoverable.
Move the textbook sections (HTTP method semantics, status code list, pagination/auth/error payloads, HATEOAS, idempotency, generic security advice) into references/rest_design_rules.md and api_antipatterns.md, keeping only the Quick Start, review flow, scorecard weighting, and tool documentation in SKILL.md.
Trim 'Best Practices Summary' and 'Common Anti-Patterns to Avoid' to one-liners or delete them — they restate content already covered in the body sections and in the reference files.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Roughly 300 of ~430 lines explain concepts Claude already knows: HTTP method semantics ('GET: Retrieve resources (safe, idempotent)'), standard status code meanings (400–500 list), OAuth/Bearer/API-key auth schemes, HATEOAS, idempotency definitions, generic pagination payload examples, and platitudes like 'Use HTTPS everywhere' and 'Validate all input parameters'. Not 1 because the Quick Start, tool sections, and review flow are skill-specific and earn their tokens; not 3 because the padding is not 'some' unnecessary explanation but the majority of the document. | 2 / 5 |
Actionability | The Quick Start gives three copy-paste-ready commands with exact flags ('--exit-on-breaking', '--min-grade B', '-o lint.json'), and the CI/CD YAML and pre-commit hook sections are directly executable. The review flow ('run all three, report... fix, then re-run until...') plus the scorecard's concrete dimension weights make the common cases fully covered. | 5 / 5 |
Workflow Clarity | The review flow is explicitly sequenced with validation gates and a feedback loop: run all three tools, report findings, fix, 're-run until the linter is clean, --exit-on-breaking passes... and the scorecard meets the agreed --min-grade', plus a hard rule 'Never sign off an API review on prose alone — attach the tool outputs'. The tools are read-only analysis, so the destructive-operation cap does not apply. | 5 / 5 |
Progressive Disclosure | The bundle contains references/rest_design_rules.md and references/api_antipatterns.md, but the body never links to either — they are orphaned — while the body simultaneously inlines large blocks of the same material (REST Design Principles, naming conventions, anti-patterns list) that clearly belong in those files. Scripts are properly referenced in Quick Start, so structure exists, but references are absent rather than merely unclear. Not 4 because anchor 4 requires 'references mostly clear'; not 2 because the document is well-sectioned and the tool entry points are discoverable. | 3 / 5 |
Total | 15 / 20 Passed |