What is hooks-creator?

This Claude skill provides a comprehensive framework for creating and managing Claude Code hooks—user-defined shell commands that execute at specific lifecycle points. It enables developers to extend Claude's capabilities by automating environment setup, enforcing custom security guardrails, and integrating external workflows directly into the agentic coding process.

When should I use hooks-creator?

hooks-creator is useful in the following scenarios: • Automated Code Quality: Running linters or formatters (like Prettier or Black) automatically after Claude finishes a code modification to ensure style consistency. • Security Guardrails: Implementing PreToolUse hooks to intercept and block potentially dangerous shell commands or unauthorized API calls before they execute. • Environment Initialization: Using SessionStart hooks to automatically export environment variables, authenticate with cloud providers, or pull the latest git changes when a session begins. • Custom Notifications: Configuring Notification hooks to send real-time alerts to team communication tools like Slack or Discord when Claude requires manual permission or finishes a long-running task. • Workflow Logging: Utilizing SessionEnd hooks to automatically export session transcripts or performance metrics to external databases for audit and evaluation.

name	hooks-creator
description	Guide for creating Claude Code hooks - user-defined shell commands that execute at lifecycle points. Use when the user wants to create, add, or configure a hook for Claude Code, including PreToolUse, PostToolUse, Notification, UserPromptSubmit, Stop, SubagentStop, PreCompact, SessionStart, or SessionEnd hooks.

Hooks Creator

Create Claude Code hooks - shell commands that execute automatically at specific lifecycle points.

Quick Reference: Hook Events

Event	When it Runs	Can Block	Matcher	Common Use
PreToolUse	Before tool call	Yes	Yes	Validate/block commands, modify inputs
PermissionRequest	Permission dialog	Yes	Yes	Auto-allow/deny permissions
PostToolUse	After tool succeeds	No	Yes	Format code, log, provide feedback
Notification	Notification sent	No	Yes	Custom alerts (permission_prompt, idle_prompt)
UserPromptSubmit	User submits prompt	Yes	No	Validate prompts, inject context
Stop	Claude finishes	Yes	No	Evaluate completion, force continue
SubagentStop	Subagent finishes	Yes	No	Evaluate subagent completion
PreCompact	Before compaction	No	Yes	Pre-compact cleanup (manual, auto)
SessionStart	Session begins	No	Yes	Setup env, load context (startup, resume, clear, compact)
SessionEnd	Session ends	No	No	Cleanup, logging

Workflow

Step 1: Determine Hook Requirements

Ask the user:

What should trigger the hook? (which event from table above)
What should the hook do? (the action to take)
Should it block/modify behavior? (for events that support blocking)

Step 2: Determine Installation Scope

Ask where to install the hook:

Scope	Path	Use Case
Project (shared)	`.claude/settings.json`	Team-shared hooks, committed to git
Project (local)	`.claude/settings.local.json`	Personal project hooks, not committed
User global	`~/.claude/settings.json`	Personal hooks for all projects
User profile	`~/.claude-<profile>/settings.json`	Profile-specific hooks

For user-level hooks, ask which profile or if using default ~/.claude/.

Step 3: Create the Hook

Configuration Format

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "path/to/script.py",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

Matcher Patterns

Exact match: "Write" - matches only Write tool
Wildcard: "*" or "" - matches all tools
Regex: "Edit|Write" - matches Edit OR Write
MCP tools: "mcp__server__tool" pattern

Events WITHOUT matcher support: UserPromptSubmit, Stop, SubagentStop, SessionEnd

Hook Script Template

Create a Python script that:

Reads JSON from stdin
Processes the input
Outputs JSON for control (optional)
Exits with appropriate code

#!/usr/bin/env python3
import json
import sys

try:
    input_data = json.load(sys.stdin)
except json.JSONDecodeError:
    sys.exit(0)

# Process input_data based on hook event
# Common fields: session_id, transcript_path, cwd, permission_mode, hook_event_name

# Exit codes:
#   0 = Success (allow)
#   2 = Block (stderr used as error message)
#   other = Non-blocking error

sys.exit(0)

Step 4: Hook Input/Output Reference

See references/hook-events.md for detailed input/output fields per event.

See references/examples.md for complete working examples.

Environment Variables

Variable	Available In	Description
`CLAUDE_PROJECT_DIR`	All hooks	Project root directory
`CLAUDE_CODE_REMOTE`	All hooks	"true" if remote, empty if local
`CLAUDE_ENV_FILE`	SessionStart only	File to persist env vars

Security Considerations

Hooks run with your user credentials
Always validate and sanitize inputs
Quote shell variables: "$CLAUDE_PROJECT_DIR"
Block path traversal: reject paths with ..
Set reasonable timeouts (default 60s)
Never access .env, credentials, private keys

hooks-creator

When & Why to Use This Skill

Use Cases