Content
86%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-engineered instruction skill: crisp workflow with genuine idempotency checkpoints, highly actionable bucket actions with enumerated forbidden directives, and exemplary one-level-deep reference splitting. The main costs are a redundant 'Hard nevers' checklist that restates in-line rules and a missing post-fix verification step for Clear fixes before pushing.
Suggestions
Cut the duplication between the 'Hard nevers' checklist and the in-line rule statements — keep the checklist and drop the prose restatements (or vice versa) — trimming roughly 10-15 lines without losing any rule.
Add an explicit verification step for Clear fixes before push, e.g. 'after the fix, re-run ./prds/<feature>/run-prd-test.sh and only commit/push when it exits 0', closing the workflow's only validation gap.
Tighten the 'one-way model' bullets, which pre-explain the dispatcher's STUCK escalation that the 'Contract with the dispatcher' section already states authoritatively.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and imperative with no padding of concepts Claude already knows, but the 'Hard nevers' section (~10 lines) restates rules already given in-line ('Never reply to a Clear finding', the suppression list, the skip rule, 'never create a stub', round tracking), and the one-way-model bullets repeat dispatcher/STUCK escalation details covered again in 'Contract with the dispatcher'. This matches 'Efficient; minor instances of over-explanation that could be trimmed' rather than the every-token-earns-its-place of score 5. | 4 / 5 |
Actionability | Fully actionable: exact paths and commands are cited ('prds/<feature>/prd.md', 'see references/gh-mechanics.md for the exact commands' — verified to contain copy-paste-ready gh/GraphQL/git commands), each bucket gets an exact action, and the forbidden-suppression list is enumerated down to specific directives ('eslint-disable*', '@ts-ignore', '# noqa', '.skip', 'xfail'). Per the rubric's instruction-skill note, absence of inline code is not penalized when guidance is this concrete. | 5 / 5 |
Workflow Clarity | The four-step sequence (re-derive with idempotency checks → ground in PRD/Expert → triage → act per bucket → exit) is clear with real checkpoints (two idempotency checks, the never-silence/skip rules, one-pass exit), matching 'Clear sequence with most checkpoints present'. Score 5 is withheld because a Clear fix has no explicit post-fix verification before push — nothing says re-run './prds/<f>/run-prd-test.sh' after the change — a minor validation gap in a code-modifying workflow. | 4 / 5 |
Progressive Disclosure | Textbook structure: the SKILL.md body keeps decision logic and rules inline, while the two external files exist in the bundle, are one level deep, and are clearly signaled with their purpose ('The taxonomy, boundary heuristics, and examples live in references/triage.md — read it'; gh-mechanics.md holds 'the fiddly gh / GraphQL / REST commands... kept out of the skill's narrative'). Both referenced files were verified present and hold exactly the promised content. | 5 / 5 |
Total | 18 / 20 Passed |