Content
88%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 highly actionable, well-sequenced multi-phase workflow with real validation gates and feedback loops, backed by real one-level-deep references and executable scripts. The main weaknesses are moderate redundancy across Performance Notes/Troubleshooting and the phases, and an inline attach sub-flow that inflates the always-loaded body.
Suggestions
Trim Performance Notes to only the new information (timing facts, validator implementation notes) and rely on Phase 2/4/8 for the max-per-kind, diff, and service-reuse rules it currently repeats.
Move the 'Attach a discovered service' sub-flow (~50 lines) into a reference file such as references/attach-service.md, keeping a one-line pointer in the body, since it only runs when the user explicitly asks in a later turn.
State the reuse-a-service-on-every-branch rule once (Phase 8) and cross-reference it from Phase 2 and Troubleshooting instead of restating it in four places.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense, operational, and never explains concepts Claude already knows, but the Performance Notes section restates rules already given in the phases ("--max-per-kind 80", the diff/skip logic, one-read-per-file), and the service-reuse-on-every-branch rule appears four times across Phase 2, Phase 8, Performance Notes, and Troubleshooting. This is more than zero trimmable redundancy (not a 5), but the rest is lean with no conceptual padding or fluff (better than the "some unnecessary explanation" of a 3). | 4 / 5 |
Actionability | Fully executable guidance throughout: copy-paste commands with complete arguments ("python3 \"$SKILL_DIR/scripts/inventory.py\" --repo \"$REPO\" --out \"$TMP/inventory.json\" --max-per-kind 80 [--since COMMIT]"), exact MCP call shapes with filter bodies, a concrete dispositions.json example, URL-normalization rules, an identity regex, hard caps ("at most 8 findings per module and 100 per scan"), and a troubleshooting table mapping exact error strings to fixes. | 5 / 5 |
Workflow Clarity | Ten clearly sequenced phases with hard validation gates ("It must exit 0 before you onboard or submit anything" for coverage.py; validate_evidence.py drops before Phase 9) and explicit feedback loops: read uncovered/badDispositions, add a finding or real disposition, rerun; fix dropped findings only when the reason is a genuine mistake. It also includes a baseline regression check, 404-baseline and 409-submit recovery, and confirm:true retry semantics — matching the checklist/feedback-loop anchor. The batch-operation cap does not apply because validation is present. | 5 / 5 |
Progressive Disclosure | All three references exist, are one level deep, and are linked exactly where the relevant phase needs them (Phase 3 → failure-modes.md, Phase 5 → rule-authoring.md, Phase 6 → evidence-contract.md), and scripts are invoked rather than inlined. However, the ~50-line attach-a-discovered-service sub-flow — a separate user-initiated operation — and repeated onboarding normalization detail are inlined in a 430-line body that loads on every invocation; these are minor organization gaps rather than the cleanly split structure of the top anchor. | 4 / 5 |
Total | 18 / 20 Passed |