creating-claude-hooks

name creating-claude-hooks description Use when creating or publishing Claude Code hooks - covers executable format, event types, JSON I/O, exit codes, security requirements, and PRPM package structure skillType skill allowed-tools Read, Write, Edit, Grep, Glob, Bash Creating Claude Code 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 Hook File Format Aspect Requirement Location .claude/hooks/<event-name> Format Executable file (shell, TypeScript, Python, etc.) Permissions Must be executable ( chmod +x ) Shebang Required ( #!/bin/bash or #!/usr/bin/env node ) Input JSON via stdin Output Text via stdout (shown to user) Exit Codes 0 = success, 2 = block, other = error Available Events Event When It Fires Common Use Cases session-start New session begins Environment setup, logging, checks user-prompt-submit Before user input processes Validation, enhancement, filtering tool-call Before tool execution Permission checks, logging, modification assistant-response After assistant responds Formatting, logging, cleanup Hook Format Requirements File Location Project hooks: .claude/hooks/session-start .claude/hooks/user-prompt-submit User-global hooks: ~/.claude/hooks/session-start ~/.claude/hooks/tool-call Executable Requirements Every hook MUST: Have a shebang line: #!/bin/bash # or #!/usr/bin/env node # or #!/usr/bin/env python3 Be executable: chmod +x .claude/hooks/session-start Handle JSON input from stdin: #!/bin/bash INPUT=$( cat ) FILE=$( echo " $INPUT " | jq -r '.input.file_path // empty' ) Exit with appropriate code: exit 0 # Success exit 2 # Block operation exit 1 # Error (logs but continues) Input/Output Format JSON Input Structure Hooks receive JSON via stdin with event-specific data: { "event" : "tool-call" , "timestamp" : "2025-01-15T10:30:00Z" , "session_id" : "abc123" , "current_dir" : "/path/to/project" , "input" : { "file_path" : "/path/to/file.ts" , "command" : "npm test" , "old_string" : "..." , "new_string" : "..." } } Stdout Output Normal output shows in transcript Empty output runs silently Use stderr ( >&2 ) for errors Exit Codes Code Meaning Behavior 0 Success Continue normally 2 Block Stop operation, show error 1 or other Error Log error, continue Schema Validation Hooks should validate against the JSON schema: Schema URL: https://github.com/pr-pm/prpm/blob/main/packages/converters/schemas/claude-hook.schema.json Required frontmatter fields: name - Hook identifier (lowercase, hyphens only) description - What the hook does event - Event type (optional, inferred from filename) language - bash, typescript, javascript, python, binary (optional) hookType: "hook" - For round-trip conversion 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 Basic Hook Examples Shell Script Hook #!/bin/bash # .claude/hooks/session-start # Log session start echo "Session started at $(date) " >> ~/.claude/session.log # Check environment if ! command -v node &> /dev/null; then echo "Warning: Node.js not installed" >&2 fi # Output to user echo "Development environment ready" exit 0 TypeScript Hook #!/usr/bin/env node // .claude/hooks/user-prompt-submit import { readFileSync } from 'fs' ; // Read JSON from stdin const input = readFileSync ( 0 , 'utf-8' ); const data = JSON . parse (input); // Validate prompt if (data. prompt . includes ( 'API_KEY' )) { console . error ( 'Warning: Prompt may contain secrets' ); process. exit ( 2 ); // Block } console . log ( 'Prompt validated' ); process. exit ( 0 ); 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 |