hooks-json-valid

hooks.json must be valid JSON with proper hook configuration structure

Severity	error
Autofix	-
Since	v0.1.0
Category	Skills, Agents, Hooks

Why

hooks.json configures commands that run automatically on agent events. Invalid JSON, unknown event types, or misconfigured handler objects will cause hooks to fail silently — the command never runs and no error is surfaced to the user.

Examples

Bad:

{
  "hooks": {
    "PostToolUse": {"command": "npm run lint"}
  }
}

Good:

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {"type": "command", "command": "npm run lint"}
        ]
      }
    ]
  }
}

How to fix

Fix the structural issue identified in the violation message. Common problems: event values must be arrays of config objects, each config must have a hooks array, each handler needs a type field, and type-specific fields (command, url, prompt) must match the handler type.

Configuration

rules:
  hooks-json-valid:
    enabled: true  # true | false | auto
    severity: error

Run skillsaw explain hooks-json-valid to see this documentation and the rule's effective configuration in your terminal.