Content
66%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 delivers an exceptionally rigorous, validated workflow: every step has an executable command, machine-checkable gates, and explicit error-recovery loops. Its main defect is token efficiency — a large fraction of the file is hook/classifier operational policy and maintenance procedure that should live in one-level-deep reference files like the existing source-manifest and visual-result-reuse docs, which would also sharpen progressive disclosure.
Suggestions
Move the Companion hooks section's classifier filter cases, opt-out phrasing table, and --reclassify-requirement maintenance procedure into a dedicated reference file (e.g., references/hook-policy.md), keeping in SKILL.md only the install commands and a summary of what each hook enforces.
Add one worked retrieve example with realistic --business-outcome/--outcome-term/--term values so the placeholder templates ('distinctive entity', 'old workflow name') become concrete, copy-paste-ready guidance.
Merge the zero-candidate and returned-results-uninspected passages into a single 'closing both directions' subsection to remove the repetition ("Pair this with the zero-candidate clause above") that currently re-explains the same rule twice.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | At ~465 lines the body is noticeably verbose: it does not explain basics Claude knows (good), but it inlines extensive policy edge-case prose — e.g., the hook classifier filter taxonomy ("Internal templates (`You are a/an …`)... never arm a requirement"), the reclassify-requirement maintenance mode, and the twice-explained zero-candidate vs returned-results dismissal rules ("Pair this with the zero-candidate clause above"). This matches anchor 2's "several unnecessary explanations or padded sections" relative to a skill body; it does not reach 3 because much of this material is not needed at point-of-use in SKILL.md at all. | 2 / 5 |
Actionability | Commands are concrete and executable throughout: `uv run --no-project python scripts/prior_work.py --manifest <path> validate-manifest`, a fully worked verify_artifact.py invocation with real-looking values (`--candidate /tmp/agent-backup.zip --member skills/editor/SKILL.md`), the complete/check commands, and hook selftest/install invocations. It falls short of anchor 5 because the central retrieve command's arguments are placeholder templates ('the observable result the user actually needs', 'distinctive entity') with no worked example showing what good terms look like. | 4 / 5 |
Workflow Clarity | A five-step numbered workflow (read context → validate manifest → retrieve → verify at authority → complete receipt) with an explicit five-condition completion contract, machine-enforced checkpoints (`scripts/prior_work.py check` must accept the receipt; "Only after this passes should substantial production begin"), exit-code semantics for verification (0/1/2), and a clear feedback loop ("If completion reports changed source evidence or scope, retrieve again... inspect the affected results and complete the new run"). This matches anchor 5's sequence + validation + feedback loops + checklist pattern. | 5 / 5 |
Progressive Disclosure | The bundle structure is used well: both reference files exist and are clearly signaled at point of need ("The schema and carrier examples are in `references/source-manifest.md`", "[visual-result reuse](references/visual-result-reuse.md)", a deep-linked anchor `references/source-manifest.md#source-fields`), and referenced scripts all exist, one level deep. It falls short of anchor 5 because substantial content that belongs in a reference — the ~120-line Companion hooks section with classifier filter cases, opt-out phrase tables, and the reclassify-requirement maintenance procedure — is inlined in SKILL.md rather than split out. | 4 / 5 |
Total | 15 / 20 Passed |