Content
62%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's execution contract is exemplary — a rigorously sequenced, validated, blocking workflow with real error recovery. Its quality is dragged down by severe duplication (nearly the entire second half restates the first) and the absence of any file-level decomposition, making it far more token-expensive than the procedure warrants.
Suggestions
Delete the duplicated second-half sections ("What This Workflow Does", "How It Works" Stages A-D, "Implementation Instructions") that restate the Execution Contract, keeping one authoritative 7-step sequence.
Move the ~100-line Example 1 (auth definition) and the illustrative banner template into a separate EXAMPLES.md / references file and link to them from the body.
Trim repeated boilerplate to a single occurrence: the banner text appears in both Step 1 and "Visual Indicators", and cost/provider details appear in both the banner and the "Cost Awareness" section.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The ~745-line body duplicates itself heavily: the 7-step sequence is restated in "Implementation Instructions", the banner template appears twice, the orchestrate.sh command appears three times, and "How It Works" (Stages A-D) re-narrates Steps 4-7. A ~100-line worked example and a second copy of provider/cost information add further padding; this goes well beyond "some unnecessary explanation" but stops short of explaining basic concepts Claude already knows. | 2 / 5 |
Actionability | Mostly executable: full provider-check bash with awk parsing and allowlist handling, exact script paths, concrete AskUserQuestion specs, and a real synthesis-file verification block. However, placeholder-laden sections (user_flow="[Answer from question 1]", "$USER_REQUEST", TaskUpdate({taskId: "..."})) and the fragile grep-based decision extraction prevent full copy-paste readiness. | 4 / 5 |
Workflow Clarity | Seven explicitly sequenced, individually blocking steps each gated by a "DO NOT PROCEED until..." checkpoint; Step 1 validates provider availability with exit-on-fail, Step 5 verifies the synthesis file exists, and the error-handling section defines per-step failure recovery (show logs, suggest /octo:setup, never substitute direct analysis). A quality checklist covers completion. | 5 / 5 |
Progressive Disclosure | A single 745-line monolith with no bundle files; the worked examples, banner templates, and cost/provider tables clearly belong in separate reference files. Section headers do provide navigable structure and the two external references (skills/blocks/*.md) are signaled, so structure exists but organization into files is absent. | 3 / 5 |
Total | 14 / 20 Passed |