Content
63%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 well-structured and genuinely actionable — the API examples match the shipped hooks_manager.py and the stop-hook mechanics are documented with concrete JSON and exit codes. Its weaknesses are redundancy (repeated install examples and safety checks), an inlined 50-line script that belongs in the bundle, and a References/Scripts section that mostly points at files that do not exist in the bundle.
Suggestions
Ship the referenced files or fix the lists: either add references/HOOK-MECHANICS.md, STOP-HOOK.md, SAFETY.md and scripts/autonomous-loop.sh, analyze.py, hook_installer.py to the bundle, or trim the References/Scripts sections to what actually exists.
Deduplicate: drop the "Safety Mechanisms" section (it re-pastes checks already visible in the loop script) and merge "Hook Types" install examples into "Operations", replacing repeated code with one-line signatures.
Move the full autonomous-loop.sh out of SKILL.md into the scripts file and keep only the decision logic (stop_hook_active check, limits, exit codes) inline; also replace "$FILE" in the PostToolUse example with the actual stdin JSON extraction.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly dense code and config, which is good, but there is real duplication: the "Safety Mechanisms" section re-pastes the doom-loop, iteration, and cost checks already shown in full inside the inlined autonomous-loop.sh; "Hook Types" repeats the install calls from Quick Start and "Operations" repeats them again. The complete ~50-line bash script inlined in SKILL.md ("## Autonomous Loop Script") is content that belongs in the scripts/ file, matching the 3 anchor ("could be tightened") rather than the trimmed 4. | 3 / 5 |
Actionability | The Python examples (install_autonomous_hooks, get_status, remove_hook, validate) match the shipped scripts/hooks_manager.py API, the settings.json blocks are concrete, and the stop-hook input/output JSON with exit codes is executable guidance. Minor gaps hold it below 5: the PostToolUse example uses `npx prettier --write "$FILE"` where $FILE is not a documented hook variable, the Quick Start omits `await hooks.initialize()`, and the inlined loop script references a `scripts/analyze.py` that is not in the bundle. | 4 / 5 |
Workflow Clarity | The stop-hook flow is clearly sequenced ("How It Works" steps 1-4 with explicit CONTINUE/COMPLETE decisions), and installation has a validate/status checkpoint (`errors = await hooks.validate()`). It falls short of anchor 5 because there is no feedback loop telling Claude what to do when validation reports errors or how to recover a clobbered settings.json, and the documented loop script diverges from the one actually shipped in hooks_manager.py (state file vs. config file, missing analyzer). | 4 / 5 |
Progressive Disclosure | Section structure is clear and the References/Scripts lists are well-labeled, but scored against the actual bundle they are largely dead: the references/ directory does not exist (HOOK-MECHANICS.md, STOP-HOOK.md, SAFETY.md are all missing) and 3 of the 4 listed scripts are absent — only scripts/hooks_manager.py ships. Combined with the full bash script inlined rather than referenced, this fits anchor 3 ("references present but" effectively unusable, "content that should be separate is inline") rather than the well-placed anchor 4. | 3 / 5 |
Total | 14 / 20 Passed |