Content
85%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 a dense, highly actionable orchestration document with gated phases, explicit validation and feedback loops, and disciplined on-demand loading — the conciseness and workflow quality of a top-tier skill. Its one real defect is bundle completeness: most of the rules/ and templates/ files it points to are not present, which undercuts the otherwise excellent progressive-disclosure design.
Suggestions
Ship the referenced rules/ and templates/ files with the bundle (or inline the few the workflow cannot run without, e.g. run-first.md Steps 1–2), since the Required Reading table and most in-body links currently point to files that are not present.
Fold 'Core Principles' into the phase sections that already operationalize it (Phases 1–3 carry the run-first and traceability rules) to reclaim tokens without losing guidance.
Trim the Diagnose section's prose describing the diagnostic-surface contract to a one-line pointer, since rules/diagnostic-surface.md and templates/diagnostic-surface.template.md are already linked there.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body assumes competence ('Detailed rules live in `rules/*.md` and templates in `templates/*.md`; load them on demand') with no basic-concept explanations, but 'Core Principles' restates rules already embedded in Phases 1–3 ('A skill is the list of what the agent got wrong') and the diagnose section inlines contract detail ('phase model, failure taxonomy, existing-guards table, source root, hard invariants') that its referenced file carries. This is the 4 anchor — efficient with minor instances that could be trimmed — rather than the every-token-earns-its-place 5. | 4 / 5 |
Actionability | Guidance is fully executable: exact commands ('node ${CLAUDE_SKILL_DIR}/scripts/validate-skill.mjs <dir> [--portable]', 'claude -p "/skill-doctor"', 'bash scripts/sync-symlinks.sh'), concrete ledger paths ('.agent/{branch}/skill-run-<task-slug>.md'), expected output strings ('Self-check: FAIL — 1 failing', 'Verify: PASS — fresh run, 0 of <n> corrections recurred'), plus a ledger-routing table and wrong/right examples. Matches the copy-paste-ready 5 anchor; the minor deferral of procedure detail to referenced files is standard progressive disclosure, not a gap. | 5 / 5 |
Workflow Clarity | All three workflows have a gated phase table ('The job ran on the real input with no skill and passes its definition of done… every correction is in the ledger'), explicit validation checkpoints (Phase 4 validate PASS, Phase 5 fresh-run verify), a concrete error-recovery loop ('A recurring correction means the line meant to prevent it is wrong or missing: fix that line and re-run once'), and per-mode Definition-of-Done checklists. Destructive prune operations are gated by 'the user's explicit yes per skill' with caller migration, so the destructive-op cap does not bind. | 5 / 5 |
Progressive Disclosure | The in-body structure is excellent — one-level-deep links and a 'Required Reading by Phase' table with 'Load these on demand — do not preload them all' — and the files that do ship (references/run-first-rationale.md, references/lift-and-prune-rationale.md, scripts/validate-skill.mjs) all resolve. However, the majority of referenced paths (rules/run-first.md, rules/diagnose-mode.md, templates/SKILL.minimal.md, and 10+ other rules/ and templates/ files) are absent from the provided bundle, so most navigation pointers break. Not a 4 because the gap is not minor; not a 2 because the body's own signaling is clear and the core workflow remains usable inline. | 3 / 5 |
Total | 17 / 20 Passed |