hook-quality-validator

Hook Quality Validator

A Claude Code skill for validating hook.json configuration files. Produces a 0-100 quality score with a detailed breakdown and actionable issue list.

---

Capabilities

• Required-field validation — confirms event, command, and timeout are present and correctly typed
• Event-type validation — verifies event is one of the seven recognised Claude Code lifecycle events
• Matcher specificity check — rewards hooks that target specific tools; penalises overly broad PostToolUse hooks with no matcher
• Command safety analysis — detects dangerous shell patterns (rm -rf, chmod 777, sudo rm)
• Timeout sanity check — ensures the timeout is present and greater than zero
• Secret detection — scans command for AWS key patterns, hard-coded passwords, and .env credential references
• Score aggregation — returns a single 0-100 integer with a per-category breakdown

---

Input Requirements

The validator accepts either:

1. A Python dict — the already-parsed hook JSON object
2. A file path string — absolute or relative path to a hook.json file

Minimum viable hook.json

{
  "event": "PostToolUse",
  "command": "echo hook fired",
  "timeout": 30
}

Well-scored hook.json

{
  "event":     "PostToolUse",
  "matcher":   { "tool_name": "Write" },
  "command":   "python3 scripts/lint.py",
  "timeout":   60,
  "description": "Run linter after every file write"
}

---

Output Format

HookQualityValidator.validate() returns a dict with four keys:

{
  "score":     85,           # int  0-100
  "passed":    True,         # bool — True when score >= 80
  "breakdown": {
    "required_fields":    25,   # max 25
    "matcher_specificity": 20,  # max 25
    "command_safety":     20,   # max 20
    "timeout":            15,   # max 15
    "no_secrets":         15,   # max 15
  },
  "issues": [
    "Matcher missing on PostToolUse hook — hook fires on every tool call"
  ]
}

---

Scripts

File	Purpose
validator.py	Core HookQualityValidator class
README.md	Installation and usage guide

Typical invocation

from validator import HookQualityValidator

result = HookQualityValidator().validate("path/to/hook.json")
print(result["score"])    # e.g. 85
print(result["passed"])   # True / False
print(result["issues"])   # list of human-readable problems

---

Quality Criteria

Category	Max pts	Pass condition
Required fields	25	event, command, timeout all present
Event type	—	event is a recognised Claude Code lifecycle event (checked inside required-fields category)
Matcher specificity	25	tool_name or other specific matcher present on applicable events
Command safety	20	No rm -rf (unscoped), chmod 777, or sudo rm
Timeout	15	timeout key present and > 0
No secrets	15	No AWS key patterns, hard-coded passwords, or .env credential references

Passing threshold: score >= 80

---

When NOT to Use

• Validating Claude Code agent .md files (use validating-agents instead)
• Validating slash command definitions (use validating-commands instead)
• Checking runtime hook behaviour — this skill only validates configuration structure
• General JSON schema validation unrelated to Claude Code hooks

Review checklist

Before treating a validator score as authoritative:

• The hook config under review is valid JSON before scoring begins
• Event type is one Claude Code actually emits (verified against the docs reference)
• Matcher specificity is checked, not just presence
• Command was scanned for embedded credentials (AWS keys, tokens, passwords)
• Destructive patterns (rm -rf, force-pushes, unbounded loops) trigger critical-severity issues
• Timeout value is finite and proportionate to the work the command does