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 highly actionable with concrete commands and config, and the nine-step workflow is clearly sequenced with verification steps. Its main weaknesses are some repeated caveats and large inline config blocks that could be split into reference files for better progressive disclosure.
Suggestions
Consolidate the repeated 'if default branch is not main' caveat into a single note referenced once instead of repeating it in steps 6 and 9.
Move the full hooks JSON example and the complete CLAUDE.md template into reference files (e.g. references/claude-template.md, references/hooks.json) and link to them from SKILL.md to improve progressive disclosure.
Add brief error-recovery guidance for the verification steps (e.g., what to check if 'codemap .' fails after install).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly concrete with little concept over-explanation, but the 'default branch is not main' caveat is repeated across steps 6 and 9, and the full 60+ line hooks JSON duplicates the Available Hooks table, so it could be tightened. | 3 / 5 |
Actionability | Provides fully executable, copy-paste-ready commands and config throughout (brew/scoop install, codemap invocations, exact CLAUDE.md content, exact settings.json hooks), covering the common cases comprehensively. | 5 / 5 |
Workflow Clarity | Nine clearly numbered steps with verification checkpoints (step 5 verify install, step 8 test); the operations are non-destructive setup so the absence of a validate-fix-retry loop is acceptable, though no explicit error-recovery guidance is given. | 4 / 5 |
Progressive Disclosure | Well-sectioned single file, but at ~230 lines the full CLAUDE.md template and the large complete-hooks JSON example are content that could live in reference files and is inlined; no bundle files exist to offload it. | 3 / 5 |
Total | 15 / 20 Passed |