Content
75%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 efficiently written, well-structured policy layer with explicit preflight and verification checkpoints. Its main gap is actionability: it names the tools and the rules of engagement but never provides the actual render, compile, or download commands an agent would run.
Suggestions
Add one copy-paste-ready command per tool (e.g., mmdc -i diagram.mmd -o diagram.png, marp deck.md --pdf --pptx, markitdown file.pdf) in each Tool Defaults section.
Add an explicit feedback loop in Verification for failed renders/compiles: inspect the error, fix the source, and re-run the command before regenerating dependent outputs.
Consider moving per-tool command details and flag references into short one-level-deep reference files (e.g., references/mermaid.md) to keep the overview tight while restoring executable depth.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is uniformly lean bullets with no concept explanations or padding ('Store editable diagrams as .mmd files', 'Verify required tools with command -v'), assuming Claude's competence at every step. | 5 / 5 |
Actionability | Policy guidance is concrete but the core execution details are missing: no mmdc render command, no marp compile command, no yt-dlp or markitdown invocations appear anywhere, so only the preflight and check commands are actually executable. | 3 / 5 |
Workflow Clarity | 'Before You Start' sequences a 5-step preflight and 'Verification' supplies explicit checkpoints ('Do not claim an artifact was regenerated unless the render or compile command succeeded', 'make check'), but there is no explicit validate-fix-retry loop to reach the top anchor. | 4 / 5 |
Progressive Disclosure | Sections are well-organized with no nested references and no bundle files, but at ~75 lines across six tools the per-tool command details that belong in one-level-deep reference files are simply omitted rather than split out. | 4 / 5 |
Total | 16 / 20 Passed |