What is the Hooks Validator?

A tool that validates the hooks configuration and the hook scripts defined in .claude/settings.json to prevent runtime errors.

What does 'type' = 'command' mean?

It means the hook runs an external script as a command; the script path must exist and the script must be executable.

What should I do if a script fails validation?

Inspect the specific failure (missing file, non-executable, bad JSON output, or missing shebang), fix the issue, and re-run hooks-check until all checks pass.

hooks-check

npx machina-cli add skill claude-world/director-mode-lite/hooks-check --openclaw

Files (1)

SKILL.md

1.2 KB

Hooks Validator

Validate hooks configuration in .claude/settings.json and hook scripts.

Validation Steps

1. Check settings.json

Verify hooks section exists and is valid.

2. Validate Hook Structure

{
  "hooks": {
    "PreToolUse": [...],
    "PostToolUse": [...],
    "Stop": [...],
    "Notification": [...]
  }
}

3. Validate Each Hook Entry

type is "command"
command path exists
Script is executable

4. Validate Hook Scripts

File exists and is executable
Outputs valid JSON
Has appropriate shebang

Output Format

## Hooks Validation Report

### Configuration Status: VALID / INVALID

### Configured Hooks
| Type | Matcher | Script | Status |
|------|---------|--------|--------|
| Stop | * | auto-loop-stop.sh | OK |

### Script Validation
| Script | Exists | Executable | Valid Output |
|--------|--------|------------|--------------|
| auto-loop-stop.sh | OK | OK | OK |

### Issues Found
1. [Issue and fix]

Auto-Fix

Make scripts executable
Add missing shebang
Create missing hook scripts

Source

git clone https://github.com/claude-world/director-mode-lite/blob/main/skills/hooks-check/SKILL.mdView on GitHub

Overview

Hooks Validator checks the .claude/settings.json hooks and the related scripts. It ensures the configuration has a valid hooks object, each entry has type 'command', the script path exists and is executable, and the hook scripts themselves produce valid JSON with a proper shebang. This helps prevent runtime errors when Claude runs PreToolUse, PostToolUse, Stop, or Notification hooks.

How This Skill Works

The validator reads .claude/settings.json, confirms a hooks object with PreToolUse, PostToolUse, Stop, and Notification. It then checks each hook entry for type 'command', that the script path exists and is executable, and validates the corresponding script's output JSON and shebang.

When to Use It

Configuring Claude to run hooks for tool use (PreToolUse, PostToolUse, Stop, Notification)
Adding or updating hook scripts to ensure correct behavior
CI/CD to enforce valid hook setup before merges
Troubleshooting failing hooks caused by invalid config or permissions
Before deploying to production to verify hooks are ready

Quick Start

Step 1: Ensure .claude/settings.json contains a hooks object with PreToolUse, PostToolUse, Stop, and Notification
Step 2: For each hook, set type to 'command', provide a valid script path, and make the script executable
Step 3: Run the hooks-check tool and address any reported issues until all checks pass

Best Practices

Document each hook's purpose and expected inputs/outputs
Validate paths and permissions in CI to catch issues early
Ensure each script outputs valid JSON and uses a proper shebang
Keep scripts small and idempotent to avoid side effects
Run hooks-check regularly as part of release pipelines

Example Use Cases

Hooks config with PreToolUse, PostToolUse, Stop and Notification all pointing to valid scripts
A missing or non-executable script is caught and reported by hooks-check
Hook entry has incorrect type or missing fields and is flagged as invalid
Script outputs JSON but lacks a shebang and is detected
Auto-fix creates missing scripts and fixes permissions to pass validation

Frequently Asked Questions

Add this skill to your agents