Content
71%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 an efficient, highly actionable instruction set with a well-sequenced workflow and explicit validation and confirmation gates for destructive operations. Its main weakness is bundle navigation: four reference files exist but are completely unsignaled from the body, and at least one is stale relative to the current workflow, so detailed material (analysis layers, document templates, the text-optimize fallback) is undiscoverable when needed.
Suggestions
Link each reference file from the relevant workflow step, e.g. step 5/6 → "See [analysis-layers.md](references/analysis-layers.md) for the 20 analysis layers" and step 7 → "See [conventions-guide.md](references/conventions-guide.md) for document templates".
Point step 8 at [rules-guide.md](references/rules-guide.md) for the rule-extraction procedure, and step 10 at [text-optimize-fallback.md](references/text-optimize-fallback.md) as the fallback when $brewtools:text-optimize is unavailable.
Update text-optimize-fallback.md to reference the current workflow steps instead of stale P4/P5/P6 phase labels so the reference matches the body.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense, imperative, and free of explanations of concepts Claude already knows ("stop on ownership/collision errors", "Never ship unresolved placeholders"), but the mode-resolution and AGENTS.md paragraphs are run-on dense and slightly repeat the mode table, so minor trimming is possible. | 4 / 5 |
Actionability | Guidance is largely executable: a concrete status command (`sh <skill-directory>/scripts/convention.sh status`), exact paths (.codex/convention/{reference-patterns,testing-conventions,project-architecture}.md), literal PLAN tokens, and exact AGENTS.md columns. Minor gaps remain, e.g. "run the script's install command" never states the actual invocation. | 4 / 5 |
Workflow Clarity | The 11-step workflow is clearly sequenced with explicit validation checkpoints ("Validate before installing loading guidance", "Validate the complete rule index after every mutation", step 11 re-validation) and confirmation gates for destructive modes. It falls short of 5 because error handling is 'stop' rather than fix-and-retry loops, and the dense mode-resolution paragraph obscures the entry sequence. | 4 / 5 |
Progressive Disclosure | The body itself is well-structured (modes table, numbered workflow) and the script reference resolves to a real file, but none of the four references/ files (analysis-layers.md, conventions-guide.md, rules-guide.md, text-optimize-fallback.md) are mentioned anywhere in the body — rules-guide.md maps to workflow step 8 and text-optimize-fallback.md to step 10, yet a reader has no navigation to them, and the fallback file references P4/P5/P6 phases that no longer exist in the body. | 3 / 5 |
Total | 15 / 20 Passed |