Content
78%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.
A well-structured, lean workflow skill: sequenced steps with confirmation gates, concrete commands, and exemplary progressive disclosure — every referenced bundle file (classification guide, three YAML templates, three schemas, two validators) exists exactly one level deep. The main defects are small: one Quick Commands path points to a non-existent `templates/REFERENCE-tool.md`, the duplicate-check is stated three times, and validation scripts are listed separately rather than wired into the workflow steps.
Suggestions
Fix the Quick Commands copy line: `cp templates/REFERENCE-tool.md references/<slug>.md` references a file that does not exist — the actual template is `assets/templates/REFERENCE-tool.yaml`, which step 5 correctly cites.
Wire the validators into the workflow: add 'run `./scripts/validate-reference-tool.sh references/<slug>.md`' as an explicit sub-step of step 5 (and the analysis validator to step 10) so validation is a checkpoint, not an aside in Quick Commands.
State the duplicate-check guidance once (Workflow step 2) and let the anti-pattern reference it, removing the repeated instruction in Quick Commands.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and imperative with no explanation of concepts Claude already knows — steps like "Record: tool name, author/org, license, language, latest version/commit" and tight section bullets assume competence. Minor trimming opportunities remain: the duplicate-check instruction appears three times (Workflow step 2, Quick Commands, and an anti-pattern), and the trailing table-format comment in Quick Commands duplicates step 7. Not a 5 because of that small redundancy; well above the padded 3 anchor. | 4 / 5 |
Actionability | Mostly executable guidance: concrete commands (`grep -i "<slug>" REVIEWED.md references/REFERENCE_INDEX.md`, `git submodule add <repo-url> tools/<repo-name>`, `./scripts/validate-reference-tool.sh references/<slug>.md`), exact file templates, and a literal table row format. The gap keeping it from 5: `cp templates/REFERENCE-tool.md references/<slug>.md` references a non-existent path (the real template is `assets/templates/REFERENCE-tool.yaml`), and the workflow steps defer some specifics (e.g., running the validator after step 5) rather than stating them inline. | 4 / 5 |
Workflow Clarity | Ten numbered steps in a coherent order with real checkpoints: step 2's duplicate check with "If already present, report it and stop", explicit user-confirmation gates before vendoring (step 6) and promotion (steps 9-10), and schema validators for outputs. A 5 would embed the validation scripts directly into the workflow steps (e.g., "run validate-reference-tool.sh after step 5") with an explicit fix-and-retry loop rather than leaving them in Quick Commands. | 4 / 5 |
Progressive Disclosure | Clear overview with well-signaled, one-level-deep references that all exist on disk: [classification guide](references/classification-guide.md) for taxonomy, `assets/templates/*.yaml` for field structures, `assets/schemas/*.schema.json`, and the two validator scripts — each deferred detail lives in exactly one bundle file and is linked with its purpose. The body holds only workflow-level guidance, matching the 5 anchor's structure. | 5 / 5 |
Total | 17 / 20 Passed |