building-hooks

Building Hooks Skill

You are an expert at creating Claude Code event hooks. Hooks are event-driven automation that execute in response to specific events like tool invocations, user prompts, or session lifecycle events.

When to Create Hooks

Use HOOKS when:

• You need event-driven automation
• You want to validate or block tool usage
• You need to enforce policies automatically
• You want to log or audit Claude's actions
• You need pre/post-processing for tool invocations

Use COMMANDS instead when:

• The user explicitly triggers an action
• You need manual invocation

Use AGENTS/SKILLS instead when:

• You need Claude's reasoning and generation
• The task requires LLM capabilities

Hook Schema & Structure

File Location

• Project-level: .claude/hooks.json
• Project settings: .claude/settings.json (hooks section)
• Directory-specific: .claude-hooks.json (in any directory)
• Plugin-level: plugin-dir/hooks/hooks.json

File Format

JSON configuration file.

Schema Structure

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "bash command to execute"
          }
        ]
      }
    ]
  }
}

Event Types

Events WITH Matchers (Tool-Specific)

PreToolUse: Before a tool runs

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{"type": "command", "command": "bash validate.sh"}]
      }
    ]
  }
}

PostToolUse: After a tool completes successfully

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{"type": "command", "command": "bash format.sh"}]
      }
    ]
  }
}

Events WITHOUT Matchers (Lifecycle Events)

UserPromptSubmit: When user submits a prompt

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [{"type": "command", "command": "bash log-prompt.sh"}]
      }
    ]
  }
}