Content
45%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 dominated by generic REST reference material Claude already knows, buried in a single monolithic file with no progressive disclosure to detail files. The skill-specific value — three executable tools and a re-run-until-clean review flow — is present and concrete but accounts for a small fraction of the token budget.
Suggestions
Strip the generic REST tutorial sections (HTTP methods, status codes, pagination/auth/error JSON, HATEOAS, idempotency, backward-compat, security best-practices, anti-patterns) — Claude already knows this; keep only the tool invocations, the review flow, and skill-specific scoring rules.
Move the bulk of the reference material into one-level-deep files (e.g. references/rest-conventions.md, references/breaking-changes.md) and replace the inlined content with clearly signaled links, so SKILL.md becomes a concise overview.
Either bundle the referenced scripts/api_linter.py, breaking_change_detector.py, and api_scorecard.py so the commands actually run, or remove the script invocations and describe the review procedure without referencing files that are absent.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The ~430-line body extensively explains REST concepts Claude already knows — HTTP method semantics, status code lists, pagination JSON, auth header formats, HATEOAS, idempotency, backward-compatibility lists, security best-practices, and anti-patterns — leaving only the Quick Start and Tools sections as skill-specific, which matches the 'severely verbose; heavily padded' score-1 anchor. | 1 / 5 |
Actionability | Quick Start provides copy-paste-ready commands with flags for all three tools ('python3 scripts/api_linter.py openapi.json --format json -o lint.json', etc.) and CI/CD plus pre-commit examples, but the Tools section lists features rather than full CLI usage and the referenced scripts are not bundled, leaving minor gaps below the score-5 anchor. | 4 / 5 |
Workflow Clarity | The review flow has an explicit feedback loop — 'run all three, report... fix, then re-run until the linter is clean, --exit-on-breaking passes... and the scorecard meets the agreed --min-grade' — with gating checkpoints, but it is written in prose rather than a crisp numbered sequence with per-step validation, sitting at the score-4 anchor. | 4 / 5 |
Progressive Disclosure | SKILL.md is a monolithic 430-line reference manual with no bundle files; material that clearly belongs in separate files (REST principles, pagination, auth, error formats) is inlined, and the referenced scripts/*.py do not exist, matching the score-2 anchor where content that belongs in separate files is inlined. | 2 / 5 |
Total | 11 / 20 Passed |