creating-claude-hooks

Use this skill when creating, improving, or publishing Claude Code hooks. Provides essential guidance on hook format, event handling, I/O conventions, and package structure.

When to Use This Skill

Activate this skill when:

• User asks to create a new Claude Code hook
• User wants to publish a hook as a PRPM package
• User needs to understand hook format or events
• User is troubleshooting hook execution
• User asks about hook vs skill vs command differences

Quick Reference

Two Hook Configuration Methods

Method 1: JSON Configuration (Recommended)

• Configure in .claude/settings.json, ~/.claude/settings.json, or plugin's hooks.json
• Supports both command hooks and prompt hooks
• More flexible, supports matchers and timeouts

Method 2: Executable Files (Legacy)

• Place executables in .claude/hooks/<event-name>
• Simpler but less configurable

Hook Types

| Type | Description | Speed | Use Case | |------|-------------|-------|----------| | Command | Runs external script | Fast (ms) | Formatting, logging, file checks | | Prompt | Uses LLM reasoning | Slow (2-10s) | Complex validation, security analysis |

Available Events

| Event | When It Fires | Can Block? | Common Use Cases | |-------|---------------|------------|------------------| | PreToolUse | Before tool execution | Yes (exit 2) | Validation, permission checks, input modification | | PostToolUse | After tool completes | No | Formatting, logging, cleanup | | UserPromptSubmit | Before user input processes | Yes | Prompt validation, enhancement | | SessionStart | New session begins | No | Environment setup, context loading | | Stop | When assistant finishes | No | Cleanup, summary, verification | | SubagentStop | When subagent finishes | No | Subagent result processing | | PreCompact | Before context compaction | No | Save important context | | Notification | During alerts | No | Desktop notifications, logging | | PermissionRequest | When permission needed | Yes | Custom permission handling |

Exit Codes

| Code | Meaning | Behavior | |------|---------|----------| | 0 | Success | Continue normally | | 2 | Block | Stop operation (PreToolUse only) | | 1 or other | Error | Log error, continue |

JSON Hook Configuration

Settings-Based Hooks

Configure hooks in .claude/settings.json (project) or ~/.claude/settings.json (global):

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "/path/to/validate-write.sh",
        "timeout": 5000
      }]
    }],
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "/path/to/format-file.sh"
      }]
    }],
    "Stop": [{
      "matcher": "*",
      "hooks": [{
        "type": "prompt",
        "prompt": "Verify all requested changes were completed."
      }]
    }]
  }
}

Plugin hooks.json

For PRPM packages, use hook.json:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write",
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh",
        "timeout": 5000
      }]
    }]
  }
}

Matcher Patterns

| Pattern | Matches | |---------|---------| | "Write" | Only Write tool | | "Write\|Edit" | Write OR Edit tools | | "Bash" | Only Bash tool | | "mcp__github__*" | All GitHub MCP tools | | "*" | All tools (use sparingly) |

Hook Options

{
  "type": "command",
  "command": "./my-hook.sh",
  "timeout": 5000,
  "once": true,
  "continue": true,
  "stopReason": "Message when blocked",
  "suppressOutput": false,
  "systemMessage": "Warning to show user"
}

| Option | Type | Default | Description | |--------|------|---------|-------------| | timeout | number | 60000 | Max execution time in ms | | once | boolean | false | Run only once per session | | continue | boolean | true | Continue after hook completes | | stopReason | string | - | Message when continue=false | | suppressOutput | boolean | false | Hide stdout from transcript | | systemMessage | string | - | Warning message to user |

Command Hooks

Command hooks run external scripts. They're fast and deterministic.

Shell Script Hook

#!/bin/bash
set -euo pipefail

# Read JSON input
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.input.file_path // empty')

# Validate
[[ -n "$FILE" ]] || exit 0
[[ -f "$FILE" ]] || exit 0

# Block sensitive files
case "$FILE" in
  *.env|*.pem|*.key)
    echo "Blocked: $FILE is sensitive" >&2
    exit 2
    ;;
esac

exit 0

TypeScript Hook

#!/usr/bin/env node
import { readFileSync } from 'fs';

const input = JSON.parse(readFileSync(0, 'utf-8'));
const filePath = input.input?.file_path;

if (!filePath) process.exit(0);

// Block .env files
if (filePath.endsWith('.env')) {
  console.error('Blocked: Cannot modify .env files');
  process.exit(2);
}

process.exit(0);

Prompt Hooks

Prompt hooks use LLM reasoning for complex validation. Use sparingly - they take 2-10 seconds.

Basic Prompt Hook

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write",
      "hooks": [{
        "type": "prompt",
        "prompt": "Check if the content being written contains hardcoded secrets, API keys, or credentials. If found, block the operation."
      }]
    }]
  }
}

Prompt Hook with Schema Validation

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "prompt",
        "prompt": "Analyze the file content for security issues. Return your decision.",
        "schema": {
          "type": "object",
          "properties": {
            "decision": {
              "type": "string",
              "enum": ["allow", "block"]
            },
            "reason": {
              "type": "string"
            },
            "severity": {
              "type": "string",
              "enum": ["low", "medium", "high", "critical"]
            }
          },
          "required": ["decision"]
        }
      }]
    }]
  }
}

When to Use Prompt Hooks

Good use cases:

• Security analysis that requires understanding code context
• Detecting logic errors or anti-patterns
• Validating architectural decisions
• Complex permission checks

Avoid for:

• Simple pattern matching (use command hooks)
• File extension checks
• Path validation
• Anything that can be done with regex

File-Based Hooks (Legacy)

Simpler approach - place executables directly in hooks directory.

File Location

Project hooks:

.claude/hooks/PreToolUse
.claude/hooks/PostToolUse
.claude/hooks/SessionStart

User-global hooks:

~/.claude/hooks/PreToolUse
~/.claude/hooks/Stop

Requirements

Every file-based hook MUST:

1. Have a shebang line:

#!/bin/bash
#!/usr/bin/env node
#!/usr/bin/env python3

2. Be executable:

chmod +x .claude/hooks/PreToolUse

3. Handle JSON input from stdin

4. Exit with appropriate code

JSON Input Structure

Hooks receive JSON via stdin:

{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.jsonl",
  "current_dir": "/path/to/project",
  "tool_name": "Write",
  "input": {
    "file_path": "/path/to/file.ts",
    "content": "file contents...",
    "command": "npm test",
    "old_string": "...",
    "new_string": "..."
  }
}

Tool-Specific Input Fields

| Tool | Available Fields | |------|------------------| | Write | file_path, content | | Edit | file_path, old_string, new_string | | Read | file_path | | Bash | command | | Glob | pattern, path | | Grep | pattern, path |

Environment Variables

Available in hook execution:

| Variable | Description | |----------|-------------| | CLAUDE_PROJECT_DIR | Project root directory | | CLAUDE_CURRENT_DIR | Current working directory | | CLAUDE_PLUGIN_ROOT | Hook installation directory | | CLAUDE_ENV_FILE | File for persisting variables | | SESSION_ID | Current session identifier |

Common Patterns

Pattern 1: Format on Save

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",
        "timeout": 5000
      }]
    }]
  }
}

Pattern 2: Block Sensitive Files

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write|Edit|Read",
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/scripts/block-sensitive.sh"
      }]
    }]
  }
}

Pattern 3: Test Verification Before Stop

{
  "hooks": {
    "Stop": [{
      "matcher": "*",
      "hooks": [{
        "type": "prompt",
        "prompt": "Before finishing, verify: 1) All tests pass 2) No linting errors 3) Types check. If any issues, list them."
      }]
    }]
  }
}

Pattern 4: Session Context Loading

{
  "hooks": {
    "SessionStart": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh",
        "once": true
      }]
    }]
  }
}

Pattern 5: Multi-Stage Validation

Combine PreToolUse (validate) with PostToolUse (verify):

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write",
      "hooks": [{
        "type": "command",
        "command": "./validate-before.sh"
      }]
    }],
    "PostToolUse": [{
      "matcher": "Write",
      "hooks": [{
        "type": "command",
        "command": "./verify-after.sh"
      }]
    }]
  }
}

Common Mistakes

| Mistake | Problem | Solution | |---------|---------|----------| | Not quoting variables | Breaks on spaces | Always use "$VAR" | | Missing shebang | Won't execute | Add #!/bin/bash | | Not executable | Permission denied | Run chmod +x hook-file | | Logging to stdout | Clutters transcript | Use stderr: echo "log" >&2 | | Wrong exit code | Doesn't block when needed | Use exit 2 to block | | No input validation | Security risk | Always validate JSON fields | | Slow operations | Blocks Claude | Run in background or use PostToolUse | | Absolute paths missing | Can't find scripts | Use ${CLAUDE_PLUGIN_ROOT} | | Using * matcher | Runs on everything | Be specific: Write\|Edit | | Prompt hooks everywhere | Slow experience | Use only for complex logic |

Best Practices

1. Keep Hooks Fast

Target < 100ms for PreToolUse hooks:

• Cache results where possible
• Run heavy operations in background
• Use specific matchers, not wildcards

2. Handle Errors Gracefully

# Check dependencies exist
if ! command -v jq &> /dev/null; then
  echo "jq not installed, skipping" >&2
  exit 0
fi

# Validate input
FILE=$(echo "$INPUT" | jq -r '.input.file_path // empty')
if [[ -z "$FILE" ]]; then
  echo "No file path provided" >&2
  exit 1
fi

3. Use Shebangs

Always start with shebang:

#!/bin/bash
#!/usr/bin/env node
#!/usr/bin/env python3

4. Secure Sensitive Files

BLOCKED=(".env" ".env.*" "*.pem" "*.key")
for pattern in "${BLOCKED[@]}"; do
  case "$FILE" in
    $pattern)
      echo "Blocked: $FILE is sensitive" >&2
      exit 2
      ;;
  esac
done

5. Quote All Variables

# WRONG - breaks on spaces
prettier --write $FILE

# RIGHT - handles spaces
prettier --write "$FILE"

6. Log for Debugging

LOG_FILE=~/.claude-hooks/debug.log

# Log to file
echo "[$(date)] Processing $FILE" >> "$LOG_FILE"

# Log to stderr (shows in transcript)
echo "Hook running..." >&2

Publishing as PRPM Package

Package Structure

my-hook/
├── prpm.json          # Package manifest
├── HOOK.md            # Hook documentation
└── hook-script.sh     # Hook executable

prpm.json

{
  "name": "@username/hook-name",
  "version": "1.0.0",
  "description": "Brief description shown in search",
  "author": "Your Name",
  "format": "claude",
  "subtype": "hook",
  "tags": ["automation", "security", "formatting"],
  "main": "HOOK.md"
}

HOOK.md Format

---
name: session-logger
description: Logs session start/end times for tracking
event: SessionStart
language: bash
hookType: hook
---

# Session Logger Hook

Logs Claude Code session activity for tracking and debugging.

## Installation

This hook will be installed to `.claude/hooks/session-start`.

## Behavior

- Logs session start time to `~/.claude/session.log`
- Displays environment status
- Runs silent dependency checks

## Requirements

- bash 4.0+
- write access to `~/.claude/`

## Source Code

\`\`\`bash
#!/bin/bash
echo "Session started at $(date)" >> ~/.claude/session.log
echo "Environment ready"
exit 0
\`\`\`

Publishing Process

# Test locally first
prpm test

# Publish to registry
prpm publish

# Version bumps
prpm publish patch  # 1.0.0 -> 1.0.1
prpm publish minor  # 1.0.0 -> 1.1.0
prpm publish major  # 1.0.0 -> 2.0.0

Security Requirements

Input Validation

# Parse JSON safely
INPUT=$(cat)
if ! FILE=$(echo "$INPUT" | jq -r '.input.file_path // empty' 2>&1); then
  echo "JSON parse failed" >&2
  exit 1
fi

# Validate field exists
[[ -n "$FILE" ]] || exit 1

Path Sanitization

# Prevent directory traversal
if [[ "$FILE" == *".."* ]]; then
  echo "Path traversal detected" >&2
  exit 2
fi

# Keep in project directory
if [[ "$FILE" != "$CLAUDE_PROJECT_DIR"* ]]; then
  echo "File outside project" >&2
  exit 2
fi

User Confirmation

Claude Code automatically:

• Requires confirmation before installing hooks
• Shows hook source code to user
• Warns about hook execution
• Displays hook output in transcript

Hooks vs Skills vs Commands

| Feature | Hooks | Skills | Commands | |---------|-------|--------|----------| | Format | Executable code | Markdown | Markdown | | Trigger | Automatic (events) | Automatic (context) | Manual (/command) | | Language | Any executable | N/A | N/A | | Use Case | Automation, validation | Reference, patterns | Quick tasks | | Security | Requires confirmation | No special permissions | Inherits from session |

Examples:

• Hook: Auto-format files on save
• Skill: Reference guide for testing patterns
• Command: /review-pr quick code review

Related Resources

• claude-hook-writer skill - Detailed hook development guidance
• typescript-hook-writer skill - TypeScript-specific hook development
• Claude Code Docs
• Schema

Checklist for New Hooks

Before publishing:

• [ ] Shebang line included
• [ ] File is executable (chmod +x)
• [ ] Validates all stdin input
• [ ] Quotes all variables
• [ ] Handles missing dependencies gracefully
• [ ] Uses appropriate exit codes
• [ ] Logs errors to stderr or file
• [ ] Tests with edge cases (spaces, Unicode, missing fields)
• [ ] Documents dependencies in HOOK.md
• [ ] Includes installation instructions
• [ ] Source code included in documentation
• [ ] Clear description and tags in prpm.json
• [ ] Version number is semantic