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.
An exemplary tool-skill body: fully executable commands, sequenced workflows with validation for destructive operations, and clean one-level-deep progressive disclosure. The one real weakness is token efficiency — several prose sections (onboarding policy, late agent rules, exit-code repetition) are run-on and redundant and could be cut or compressed.
Suggestions
Rewrite the 'Onboarding And Insight' section as a short bulleted decision list instead of a single run-on paragraph — it is the densest prose block in the file and much of it repeats conditions stated elsewhere.
Compress Agent Rules 9-14 (telemetry, type-aware gating, statusline, similar-code) into shorter rules with detail moved to the relevant reference file (e.g. the similar-code workflow detail in rule 14 largely duplicates references/similar-code.md).
Drop the second full exit-code explanation in 'Exit Codes' — the section restates rule 2 and points at `fallow schema.exit_codes`, so a single sentence plus the JSON error example would suffice.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with fallow-specific facts Claude cannot know, but sections are noticeably padded: the "Onboarding And Insight" run-on paragraph, Agent Rules 9-14, and repeated exit-code explanations could all be tightened. Anchor 3 ("mostly efficient but... could be tightened") fits; not 4 because the trimming needed is more than minor, not 2 because it never explains concepts Claude already knows. | 3 / 5 |
Actionability | Commands throughout are copy-paste ready with concrete flags (e.g. `fallow dead-code --format json --quiet --workspace 'apps/*,!apps/legacy'`), plus JSON envelope examples, exit-code semantics, and suppression-comment syntax. Fully executable guidance covering the common cases; anchor 5. | 5 / 5 |
Workflow Clarity | Multi-step workflows are explicitly sequenced with validation checkpoints: the destructive fix cycle mandates `--dry-run` preview then `fix --yes` then re-verification, baselines are save-then-gate, and the similar-code workflow fails closed on stale source with explicit abstention rules. The destructive/batch cap does not apply because validation is present. | 5 / 5 |
Progressive Disclosure | The body is an overview with a task-routing matrix, and the bulk catalogues (CLI reference, MCP tools, issue types, gotchas, patterns, similar-code, node bindings) are pushed to real one-level-deep reference files, each verified to exist and clearly signaled with descriptive links plus a References section. Anchor 5. | 5 / 5 |
Total | 18 / 20 Passed |