Content
46%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 skill documents a genuinely well-designed gate with concrete configuration guidance, but SKILL.md itself is a monolithic implementation spec. The invoke-time guidance an agent needs (how to respond to a denial, how to enable the hook) is drowned by hundreds of lines of internal matching rules, and the referenced scripts and docs are not shipped in the bundle.
Suggestions
Move the prior-search credit, comment/whitespace-only, sibling-collapse, and sensitive/hard-link rule sections into reference files (e.g., references/credit-rules.md, references/change-profile.md) and keep only a one-paragraph summary with links in SKILL.md.
Ship the referenced files or fix the links: scripts/hooks/gateguard-fact-force.js, scripts/gateguard-report.js, and docs/gateguard/change-profile.md are cited but absent from the bundle.
Move Quick Start near the top and add a verification step (e.g., a sample edit to trigger and confirm a first-touch denial, or a command to check the hook is registered) before the detailed gate-behavior sections; include the actual hooks.json snippet for Option A.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is ~700 lines of dense implementation spec — prior-search credit stem matching, exclusion parsing for rg/grep/fd/tree/git, 8.3 short names, ADS-style path handling, hard-link realpathing — that is hook-internal behavior, not guidance the agent needs at invocation time. Anchor 2 ("noticeably verbose; several unnecessary explanations or padded sections") fits: it is not explaining things Claude already knows, but much of it is edge-case enumeration that could be trimmed or moved to reference files, which is below the mostly-efficient anchor 3. | 2 / 5 |
Actionability | Quick Start gives two concrete install paths ("pip install gateguard-ai\ngateguard init", enabling scripts/hooks/gateguard-fact-force.js via hooks.json), a full env-var table with defaults, an executable metrics report command, and a copy-paste JSON env example. Minor gaps keep it below 5: Option A never shows the actual hooks.json snippet to enable the hook, and no command verifies the hook is active. | 4 / 5 |
Workflow Clarity | The operative sequence exists (enable hook → set env vars → handle first-touch denials by presenting facts and retrying, with the parallel-batch warnings), but there is no checkpoint verifying the gate is installed and firing before relying on it, and the installation steps are buried under ~500 lines of gate-behavior spec that precedes Quick Start. A destructive/batch-adjacent tool skill without an explicit validation step cannot exceed 3. | 3 / 5 |
Progressive Disclosure | No references/, scripts/, or assets/ directories exist in the bundle, yet the body cites scripts/hooks/gateguard-fact-force.js, scripts/gateguard-report.js, and docs/gateguard/change-profile.md as if present — key navigation targets are dangling. Meanwhile ~400 lines of matching-rule spec (prior-search credit, comment-only edits, sibling collapse) that clearly belongs in separate reference files are inlined in SKILL.md, matching anchor 2. | 2 / 5 |
Total | 11 / 20 Passed |