Content
57%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The skill is highly actionable with concrete, executable commands and well-structured step-by-step guidance for setting up Codemap CLI. Its main weaknesses are the monolithic structure—embedding large JSON configs and markdown templates inline rather than referencing separate files—and the lack of explicit error handling or validation feedback loops for potentially fragile operations like merging settings files or handling installation failures.
Suggestions
Extract the full hooks JSON example and the CLAUDE.md template content into separate bundle files (e.g., HOOKS_FULL_CONFIG.json, CLAUDE_TEMPLATE.md) and reference them from the main skill to improve progressive disclosure and reduce token usage.
Add validation/error recovery guidance for key steps: what to do if installation fails, how to handle merging hooks into an existing settings.json that already has content, and how to verify the settings file is valid JSON after editing.
Remove or condense the options table in the CLAUDE.md block—Claude can reference the README directly, and duplicating CLI documentation increases maintenance burden and token cost.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill includes some unnecessary verbosity—the full hooks JSON example is quite long and could be referenced externally, and the CLAUDE.md content block is extensive. However, it mostly avoids explaining concepts Claude already knows and stays focused on actionable setup steps. | 2 / 3 |
Actionability | The skill provides fully executable commands for installation (brew, scoop), verification, and configuration. JSON configs are copy-paste ready, CLI flags are documented with concrete examples, and conditional logic (e.g., non-main default branch) is clearly specified. | 3 / 3 |
Workflow Clarity | Steps are clearly numbered and sequenced (1-9), and there's a verification step after installation. However, there are no explicit validation checkpoints or error recovery loops—e.g., what to do if `codemap -help` fails for reasons other than not being installed, or if `brew install` fails. The settings file creation step lacks validation that the JSON is correctly merged with existing settings. | 2 / 3 |
Progressive Disclosure | The skill is a monolithic wall of content with no references to external files. The full hooks JSON example (~40 lines), the complete CLAUDE.md content block, and the options table are all inline. These could be split into separate reference files (e.g., HOOKS_REFERENCE.md, CLAUDE_TEMPLATE.md) with the SKILL.md serving as an overview. | 1 / 3 |
Total | 8 / 12 Passed |