hooks-automation

name	hooks-automation
description	Create and manage Claude Code hooks — auto-trigger scripts on events like PreToolUse, PostToolUse, PreCommit, UserPromptSubmit, and more. Trigger on /hooks-automation, or when setting up automation workflows, pre-commit checks, tool guards, or session lifecycle hooks.
user-invocable	true
allowed-tools	Read, Grep, Glob, Bash, Edit

Hooks Automation

Claude Code hooks let you auto-run scripts or prompts on specific events. Configured in .claude/settings.json.

Hook Events

Session Lifecycle

• SessionStart — On session start/resume/clear/compact. Use: env setup, cache warm, context injection.
• SessionEnd — On session end. Use: cleanup, telemetry, log summary.

User Interaction

• UserPromptSubmit — Each time user submits a prompt. Use: inject branch name, time, env context.

Tool Execution

• PreToolUse — Before any tool call (Bash, Edit, Write, Read, etc.). Use: block dangerous commands, validate tool args, scan for secrets.
• PostToolUse — After any tool call. Use: log results, trigger follow-ups, validate output.

File Operations

• FileCreate — When a file is created. Use: auto-format, add header, lint new files.
• FileUpdate — When a file is modified. Use: type-check changed files, run formatter.

Git Operations

• PreCommit — Before git commit. Use: run linter, check for secrets, validate commit message format.
• PostCommit — After git commit. Use: notify, update changelog.
• PrePush — Before git push. Use: run full test suite, check CI status.

Agent Lifecycle

• Stop — When main agent decides to stop. Use: validate completion criteria.
• SubagentStart — When a subagent starts. Use: inject subagent-specific context.
• SubagentStop — When a subagent stops. Use: validate subagent output, approve/block completion.

Hook Types

1. Prompt hooks — Ask Claude to evaluate something. Flexible, context-aware.
2. Command hooks — Run shell commands. Deterministic, fast. Use %CLAUSE_ROOT% for paths.

Example: settings.json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if this bash command is destructive (rm -rf, git reset --hard, etc). If yes, block with reason."
          }
        ]
      }
    ],
    "PreCommit": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "cd '%CLAUSE_ROOT%' && npx oxlint --quiet"
          }
        ]
      }
    ]
  }
}

Rules

• Prefer prompt hooks for flexible checks, command hooks for deterministic operations.
• Set timeouts for command hooks to avoid hanging.
• Use specific matchers to scope hooks (tool name, file pattern).
• Test hooks with claude --debug to verify behavior.
• Do not add hooks that create friction for common workflows.

Experience Log

This skill learns from experience. Mechanism:

• Read .claude/experience/hooks-automation.md at skill start to benefit from past lessons.

• Write to .claude/experience/hooks-automation.md after use if you learned something new.

• Format: YYYY-MM-DD: <lesson> — one line per entry.

• Evolve: If the same issue repeats 3+ times, update this SKILL.md itself.

This skill improves over time. After each use, append lessons learned.

Record format: YYYY-MM-DD: <lesson> Read this at skill start to apply past lessons.