Claude Code Hooks Setup Skill

This skill guides you through setting up Claude Code hooks with a thorough interview process to ensure the hook configuration exactly matches user requirements.

Critical Workflow

ALWAYS follow this interview-first approach:

1. •Interview the user - Never skip this step, even if they provide initial details
2. •Confirm understanding - Summarize back what you understood
3. •Generate the hook configuration - Create the JSON structure
4. •Safely apply to settings - Merge with existing settings or create new

Step 1: Interview Questions

Ask these questions to fully understand the user's needs. Ask 2-3 at a time max to avoid overwhelming them.

Essential Questions (Always Ask)

1. •

   What should the hook do?

   • •"What specific action or behavior do you want to automate?"
   • •"Can you describe the problem this hook should solve?"
2. •

   When should it trigger?

   • •"Which hook event should trigger this?" (Show the list below)
   • •"Should it run for all tools or only specific ones?"
3. •

   What's the desired outcome?

   • •"Should it block operations, modify them, log them, or just observe?"
   • •"What should happen when the hook runs successfully vs fails?"

Hook Event Options (Present to User)

Matcher Questions (For PreToolUse, PostToolUse, PermissionRequest)

1. •Which tools should this affect?
   • •"Should this apply to all tools (*) or specific ones?"
   • •Common matchers: Bash, Write, Edit, Read, Glob, Grep, Task, WebFetch, WebSearch
   • •"You can combine with regex: Edit|Write matches both"

Implementation Questions

1. •

   How should the hook be implemented?

   • •command type: Run a bash command/script
   • •prompt type: Use LLM evaluation (only for Stop/SubagentStop)
2. •

   What should the hook output?

   • •Exit code 0: Success (continues normally)
   • •Exit code 2: Block the operation (shows stderr to Claude)
   • •JSON output: For advanced control (decisions, modified inputs)
3. •

   Where should this hook be stored?

   • •User settings (~/.claude/settings.json): Applies to all projects
   • •Project settings (.claude/settings.json): Shared with team
   • •Local settings (.claude/settings.local.json): Personal, not committed

Context Questions

1. •

   Does the hook need project context?

   • •Scripts can use $CLAUDE_PROJECT_DIR for project-relative paths
   • •Environment variables available to hooks
2. •

   Should there be a timeout?

   • •Default: 60 seconds
   • •Can specify custom timeout per hook

Step 2: Confirm Understanding

Before proceeding, summarize back:

Based on our discussion, here's what I'll set up:

- **Hook Event**: [event name]
- **Matcher**: [pattern or "all tools"]
- **Action**: [what the hook does]
- **Implementation**: [command/prompt and what it does]
- **Output Behavior**: [what happens on success/failure]
- **Storage Location**: [which settings file]

Does this match what you need? Any adjustments?

Step 3: Generate Hook Configuration

JSON Structure Reference

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "your-command-here",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

For Events Without Matchers

UserPromptSubmit, Stop, SubagentStop, Notification, SessionStart, SessionEnd, PreCompact don't use matchers:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/validator.py"
          }
        ]
      }
    ]
  }
}

Step 4: Safely Apply Configuration

CRITICAL: Never corrupt existing settings files.

Check for Existing Settings

# Check if settings file exists
if [ -f ".claude/settings.json" ]; then
    echo "Existing settings found"
else
    echo "No existing settings"
fi

Safe Merge Strategy

1. •Read existing file (if exists)
2. •Parse as JSON to validate
3. •Merge hooks - Don't overwrite, append to existing arrays
4. •Write back with proper formatting

Helper Script Usage

Use the provided scripts/apply_hooks.py script:

python3 "$SKILL_DIR/scripts/apply_hooks.py" \
    --settings-file ".claude/settings.json" \
    --hook-event "PostToolUse" \
    --matcher "Edit|Write" \
    --command "npx prettier --write \"\$(jq -r '.tool_input.file_path')\"" \
    --timeout 30

Or use scripts/apply_hooks_json.py for full JSON input:

echo '{"hooks":{"PostToolUse":[...]}}' | python3 "$SKILL_DIR/scripts/apply_hooks_json.py" --settings-file ".claude/settings.json"

Common Hook Recipes

See references/hook-recipes.md for tested, ready-to-use configurations including:

• •Code formatting (Prettier, Black, gofmt)
• •File protection
• •Command logging
• •Desktop notifications
• •Git safeguards
• •Test runners
• •Linting

Hook Input/Output Reference

See references/hook-io-reference.md for complete documentation on:

• •Input JSON schemas for each event
• •Output formats (exit codes vs JSON)
• •Decision control options
• •Advanced JSON output fields

Debugging Hooks

If hooks aren't working:

1. •Check registration: Run /hooks in Claude Code
2. •Verify syntax: Ensure valid JSON in settings
3. •Test commands: Run hook command manually with sample input
4. •Check permissions: Ensure scripts are executable
5. •Review logs: Use claude --debug for detailed output