Content
81%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.
Highly actionable content with excellent validation-gated workflows for destructive operations and a well-organized reference bundle. The main weakness is length: at roughly 450 lines with a duplicated exit-code explanation and several inline enumerations that duplicate the reference files, it could be substantially tightened. Moving more catalogue-level detail into the existing references would improve both conciseness and the overview role of SKILL.md.
Suggestions
Remove the duplicated exit-code 0/1 explanation: keep it in the Exit Codes section and have Agent Rule 2 reference that section (and `fallow schema.exit_codes`) instead of restating it verbatim.
Trim the inline flag enumerations in the flags, health/CODEOWNERS, and baseline workflows down to the core command plus one sentence, and move the full option tables into references/cli-reference.md or references/patterns.md which already exist for this purpose.
Move the walkthrough-guide judgment-file JSON schema and its validation rules out of Common Workflows into a reference file (e.g. references/patterns.md), keeping only the three-command sequence and the key stale-hash rule inline.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with tool-specific facts and does not explain concepts Claude already knows, but at ~450 lines it is verbose with real duplication: the 0/1 exit-code semantics appear near-verbatim in Agent Rule 2 and again in the Exit Codes section, the task matrix is stated to duplicate `fallow schema`, and the `flags --retirement` workflow enumerates every reason code, sort option, and output format inline. This fits 'mostly efficient but could be tightened' (anchor 3) rather than anchor 4, since the rubric penalizes verbosity even when accurate. | 3 / 5 |
Actionability | Fully executable throughout: copy-paste commands with exact flags (`fallow dead-code --format json --quiet --unused-exports`), JSON parsing rules, a typed import path (`import type { CheckOutput, ... } from "fallow/types"`), non-TTY requirements (`--yes` or exit 2), and concrete workflow blocks covering the common cases. Nothing is pseudocode or merely descriptive. | 5 / 5 |
Workflow Clarity | Multi-step processes are explicitly sequenced with validation and feedback loops: the destructive fix path mandates `--dry-run` preview then verify; `fallow doctor` preflight gives per-check remediation with fail/warn semantics and re-run guidance; the walkthrough workflow validates judgments against a live graph and handles the stale case ('On `stale: true`, fetch the guide again'); baselines follow a save-then-gate sequence. This matches the anchor with explicit validation steps and error-recovery loops. | 5 / 5 |
Progressive Disclosure | Good structure with seven real one-level-deep reference files (cli-reference.md, mcp.md, issue-types.md, gotchas.md, patterns.md, similar-code.md, node-bindings.md), each with a one-line purpose in the References section and point-of-use links, and the bulk catalogues (e.g. the 236KB CLI reference) correctly split out of SKILL.md. However, the body itself inlines manual-level detail — full flag enumerations for flags/health, the CODEOWNERS caveat, and the judgment-file JSON schema — that belongs in those references, so it stops short of the lean-overview anchor 5. | 4 / 5 |
Total | 17 / 20 Passed |