Content
73%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-architected skill body: the flow is unambiguous with strong validation loops, and reference delegation is clean with all cited files present. The main costs are redundancy — core rules like P7 and 'never auto-merge' are restated three to five times — and a few steps that name an operation without showing one concrete instance of it.
Suggestions
State each hard rule once and cross-reference by number: P7 is repeated in the intro, Step 1, Step 2, and Hard nevers; the intro's STUCK paragraph and the P7 bullet say the same thing. Cutting to 'P7 (see Hard nevers)' would save ~15 lines without losing information.
Add one concrete mini-example for the thinnest steps — a sample changelog.md entry and a two-line snippet of local-checks.sh lint wiring — so 'wire it into scripts/local-checks.sh' and 'Append a changelog.md entry' are copy-paste executable rather than directional.
Collapse the duplicated invocation narrative: the second intro paragraph ('You run headless…') and the 'Invocation & output contract' section both describe the memory loop, worktree, and watermark; merge them into the contract section and keep a one-line pointer in the intro.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with project-specific, non-obvious design decisions, but key rules are restated repeatedly: P7 (human-authored memory edits are ground truth) appears in the intro, P7 itself, Step 1, Step 2, and Hard nevers; 'never an auto-merge' appears three times; 'a lint is a rule the agent cannot ship past' twice; and the worktree/loop invocation setup is described in both the intro and the Invocation contract. Not 4: the repetition goes beyond minor trimming — each point could be stated once and cross-referenced by its P-number; not 2: nothing explains concepts Claude already knows, and every repetition is at least project-specific substance. | 3 / 5 |
Actionability | Concrete commands and paths throughout: 'claude -p "/learn --since <sha> --sha <sha>"', 'git ls-remote origin learn/<sha>', 'scripts/check-agents-md.sh', '.claude/skills/expert/references/*.md', 'scripts/lints/' plus concrete parameters (2–3 reviewers, 2/3 threshold, five-predicate bar). Not 5: some steps stop at direction — 'wire it into scripts/local-checks.sh' and the changelog entry lack a concrete example, and execution mechanics are deferred to the references without an inline sample of a shard diff or changelog entry. | 4 / 5 |
Workflow Clarity | Steps 0–6 are clearly sequenced with explicit validation checkpoints and feedback loops: the drafted lint 'MUST pass against the just-merged code before you include it — run it; if it fails on current main it's wrong', Step 5 re-runs check-agents-md.sh and the lint, Step 0 has an idempotency pre-check, and 'Hard nevers' acts as a checklist. Not 4: validation is explicit at every risky point (idempotency, consensus gate, lint verification, post-write check), not mostly present. | 5 / 5 |
Progressive Disclosure | The five references (routing-rules, expert-shards, agents-md-guidance, invariant-discovery, consensus) all exist in the bundle, are one level deep, and each is signaled with a one-line purpose statement; the body is an overview that delegates detail appropriately. Not 5: the ~160-line body inlines substantial philosophy (P1–P8 plus a standalone 'Ground truth' section) that a leaner overview would partially delegate, and 'scripts/learn-tick.sh' is named as the loop driver but is absent from the bundle, leaving a dangling pointer. Not 3: the split between body and references is genuinely good and easy to navigate. | 4 / 5 |
Total | 16 / 20 Passed |