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 multi-mode procedure with phased gates, validation scripts, feedback loops, and destructive-operation safeguards — near the top of the rubric for actionability and workflow clarity. Its main weaknesses are restating the same material across four sections (links, reading table, principles, definition of done) and a bundle that omits almost all of the `rules/` and `templates/` files the body depends on, breaking progressive disclosure in practice.
Suggestions
Ship the referenced bundle files: the body defers core procedure to `rules/run-first.md`, `rules/diagnose-mode.md`, `rules/prune-mode.md`, and `templates/SKILL.minimal.md`, none of which exist in the provided bundle — either include them or inline the minimal procedure for Phases 0–2 so the skill is self-sufficient.
Consolidate the four passes over the same content: the inline rule links, the "Required Reading by Phase" table, "Core Principles", and the "Definition of Done" checklists largely restate each other; keep one navigation map and one checklist and cut the rest to reclaim ~40 lines.
In "Phase 1 — Run", state what happens when the user rejects the output after several iterations (e.g. an escalation or stop condition), since the loop 'repeat until they accept it' is the only unbounded step in the scaffold workflow.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Quotes: "Never add a step the agent did correctly in the run, a heading with no ledger row under it, or frontmatter the run did not need"; "Load these on demand — do not preload them all" — the body assumes Claude's competence and adds only skill-specific procedure, with compact ✗/✓ examples. Not 5: the same material is restated across passes — inline rule links, the "Required Reading by Phase" table, "Core Principles", and the "Definition of Done" checklists repeat the phase gates and run-first rationale, so several dozen lines could be trimmed. Not 3: there is no padding or explanation of concepts Claude already knows; the redundancy is navigational, not educational. | 4 / 5 |
Actionability | Quotes: "Run `node ${CLAUDE_SKILL_DIR}/scripts/validate-skill.mjs <dir> [--portable]`"; "/create-skill diagnose <target-skill-name> [--symptom "..."] [--scope <phase|companion>] [--apply] [--pr] [--no-write]"; "Report `Verify: PASS — fresh run, 0 of <n> corrections recurred`"; the ledger path `.agent/{branch}/skill-run-<task-slug>.md` — commands, file paths, invocation syntax, and exact report lines are copy-paste ready, and the wrong/right dialogs give concrete behavioral contrasts. The instruction-only guidance is fully actionable without code. | 5 / 5 |
Workflow Clarity | Quotes: the phased gate table ("Phase 1 — Run ... every correction is in the ledger — or the run was waived with a recorded reason"), "fix every `FAIL`, and report its `Self-check:` line verbatim", and "A recurring correction means the line meant to prevent it is wrong or missing: fix that line and re-run once" — explicit validation gates, feedback loops for error recovery, and per-mode checklists in the Definition of Done. Destructive operations are covered: prune requires "the user's explicit yes per skill before deleting or trimming anything" and caller migration, and diagnose's `--apply` is gated at "confidence(analysis) ≥ 90 %" with explicit confirmation before `git apply`, so the destructive/batch cap at 3 does not apply. | 5 / 5 |
Progressive Disclosure | Quotes: "Detailed rules live in `rules/*.md` and templates in `templates/*.md`; load them on demand" and the "Required Reading by Phase" table — the body is designed for one-level-deep, clearly signaled, on-demand references. But scored against the actual bundle, only `references/run-first-rationale.md`, `references/lift-and-prune-rationale.md`, and `scripts/validate-skill.mjs` exist; the 16 referenced `rules/*.md` and `templates/*.md` paths (e.g. `rules/run-first.md`, which holds "The full procedure for Phases 0–2") are absent, so the disclosure chain cannot actually be followed. Not 4: missing the majority of referenced files is not a "minor organization gap"; not 2: the SKILL.md itself is well-structured and every reference is clearly signaled and correctly scoped, not buried or inlined. | 3 / 5 |
Total | 17 / 20 Passed |