Content
82%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 content is a strong, dense reference for a niche API Claude would not know: executable examples, precise semantics (shallow-merge updated_input, config-order aggregation, deny>allow precedence), and useful debugging guidance. Weak spots are minor: one placeholder in the rewrite example, no explicit hook-testing verification step in the authoring workflow, and an unlinked external reference pointer with no bundle files.
Suggestions
Replace the `some-rewriter` placeholder in the rewrite example with a concrete (even trivial) transformation — e.g. `sed 's/npm test/npm test -- --runInBand/'` — so the example is copy-paste executable.
Add a verification step to the Authoring Checklist, such as testing the hook against a sample stdin payload (`echo '{"tool_name":"bash",...}' | ./hooks/my-hook.sh`) before wiring it into crush.json, closing the workflow's validation gap.
Turn the `docs/hooks/README.md` mention into a proper markdown link, and if the skill grows, move the env-var and exit-code tables into a `references/` file to strengthen progressive disclosure.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean and dense — configuration schema, env-var and exit-code tables, and four canonical examples with no padding and no explanation of concepts Claude already knows (e.g., no tutorial on regex, JSON, or shell scripting). It matches the score-5 anchor ('lean and efficient; assumes Claude's competence; every token earns its place'); score 4 would require identifiable instances of over-explanation to trim, and none stand out. | 5 / 5 |
Actionability | Three of the four canonical examples are copy-paste executable (the rm -rf blocker, the inline allow echo, the Go context injector), and the config snippets are concrete. It falls short of the score-5 anchor because the rewrite example pipes through an unexplained placeholder — `jq -r '.tool_input.command' | some-rewriter` — so that example is not executable as written; the user-specific rewriting logic is implicitly but not explicitly justified, which is exactly the 'minor gaps' of the score-4 anchor. | 4 / 5 |
Workflow Clarity | The Authoring Checklist gives a clear 5-step sequence (shebang/set flags, chmod, config entry, intent decision, shallow-merge reminder) and the Debugging section supplies error-recovery guidance (timeout behavior, non-2/49 exits, stderr logging, matcher regex). It does not reach 5 because there is no explicit verification checkpoint such as testing the hook against a sample stdin payload before wiring it into crush.json — the 'minor validation gaps' of the score-4 anchor. The destructive-operations cap does not apply since the workflow authors hooks rather than performing destructive/batch operations. | 4 / 5 |
Progressive Disclosure | The single file (~205 lines) is well organized into scannable sections (Events, Configuration, Input, Output, Aggregation, Examples, Checklist, Debugging, Compatibility) with a one-level pointer to the full reference ('For the full reference, see docs/hooks/README.md'). It stops short of the score-5 anchor because that pointer is not a proper link and no bundle file exists, so reference-grade detail (env-var/exit-code tables) is inlined rather than split out — the 'minor organization gaps' and 'references mostly clear' of the score-4 anchor; it is well above score 3, where structure would be weak or references buried. | 4 / 5 |
Total | 17 / 20 Passed |