Expert guidance for writing secure, reliable, and performant Claude Code hooks - validates design decisions, enforces best practices, and prevents common pitfalls. Use when creating, reviewing, or debugging Claude Code hooks.
/plugin marketplace add secondsky/claude-skills/plugin install claude-hook-writer@claude-skillsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
references/code-templates.mdreferences/publishing-guide.mdreferences/quick-reference.mdreferences/reliability-performance.mdreferences/security-requirements.mdreferences/testing-debugging.mdStatus: Production Ready Version: 2.0.0 (Optimized with progressive disclosure) Last Updated: 2025-12-17
Expert guidance for writing secure, reliable, and performant Claude Code hooks. This skill validates design decisions, enforces best practices, and prevents common pitfalls.
Hooks execute automatically with user permissions and can read, modify, or delete any file the user can access.
ALWAYS validate and sanitize all input. Hooks receive JSON via stdin—never trust it blindly.
For complete security patterns: Load references/security-requirements.md when implementing validation or securing hooks.
A hook that works 99% of the time is a broken hook. Edge cases (Unicode filenames, spaces in paths, missing tools) will happen.
Test with edge cases before deploying.
For reliability patterns: Load references/reliability-performance.md when handling errors or edge cases.
Hooks block operations. A 5-second hook means Claude waits 5 seconds before continuing.
Keep hooks fast. Run heavy operations in background.
For performance optimization: Load references/reliability-performance.md when optimizing hook speed.
Missing dependencies, malformed input, and disk errors will occur.
Handle errors explicitly. Log failures. Return meaningful exit codes.
Before writing code, answer these questions:
PreToolUse - Before tool execution (modify input, validate, block)PostToolUse - After tool completes (format, log, cleanup)UserPromptSubmit - Before user input processes (validate, enhance)SessionStart - When Claude Code starts (setup, env check)SessionEnd - When Claude Code exits (cleanup, persist state)Notification - During alerts (desktop notifications, logging)Stop / SubagentStop - When responses finish (cleanup, summary)PreCompact - Before context compaction (save important context)Common mistake: Using PostToolUse for validation (too late—tool already ran). Use PreToolUse to block operations.
Be specific. matcher: "*" runs on every tool call.
Good matchers:
"Write" - Only file writes"Edit|Write" - File modifications"Bash" - Shell commands"mcp__github__*" - All GitHub MCP toolsBad matchers:
"*" - Everything (use only for logging/metrics)Different tools provide different input. Check what's available:
# PreToolUse / PostToolUse
{
"input": {
"file_path": "/path/to/file.ts", // Read, Write, Edit
"command": "npm test", // Bash
"old_string": "...", // Edit
"new_string": "..." // Edit
}
}
Validate fields exist before using them:
FILE=$(echo "$INPUT" | jq -r '.input.file_path // empty')
if [[ -z "$FILE" ]]; then
echo "No file path provided" >&2
exit 1
fi
Command hooks (type: "command"):
Prompt hooks (type: "prompt"):
Rule of thumb: Use command hooks unless you need LLM reasoning.
exit 0 - Success (continue operation)exit 2 - Block operation (show error to Claude)exit 1 or other - Non-blocking error (log but continue)For PreToolUse hooks:
For PostToolUse hooks:
Error: Hooks break on filenames with spaces or special characters
Why: Unquoted variables split on whitespace
Example:
# ❌ WRONG - breaks on "my file.txt"
cat $FILE
prettier --write $FILE
rm $FILE
# ✅ RIGHT - handles spaces and special chars
cat "$FILE"
prettier --write "$FILE"
rm "$FILE"
Why this matters: Files with spaces ("my file.txt"), Unicode ("文件.txt"), or special chars ("file (1).txt") are common.
For quoting best practices: Load references/security-requirements.md for comprehensive input handling patterns.
Error: Hook executes on malicious or malformed input
Why: Not validating JSON fields before using them
Example:
# ❌ DANGEROUS - no validation
FILE=$(jq -r '.input.file_path')
rm "$FILE" # Could delete ../../../etc/passwd
# ✅ SAFE - validate first
FILE=$(jq -r '.input.file_path // empty')
[[ -n "$FILE" ]] || exit 1
[[ "$FILE" == "$CLAUDE_PROJECT_DIR"* ]] || exit 2
[[ "$FILE" != *".."* ]] || exit 2
rm "$FILE"
Why this matters: Prevents path traversal attacks, protects files outside project, prevents malformed input crashes.
For complete security patterns: Load references/security-requirements.md.
Error: Hook takes 30+ seconds, blocking Claude
Why: Running expensive operations (tests, builds) synchronously in hook
Example:
# ❌ BLOCKS Claude for 30 seconds
npm test
npm run build
# ✅ RUN IN BACKGROUND - returns immediately
(npm test > /tmp/test-results.log 2>&1 &)
(npm run build > /tmp/build.log 2>&1 &)
exit 0
Why this matters: Slow hooks create bad user experience. Target < 100ms for PreToolUse, < 500ms for PostToolUse.
For performance optimization: Load references/reliability-performance.md.
Error: PreToolUse hook doesn't actually block the operation
Why: Using exit 1 instead of exit 2
Example:
# ❌ WRONG - logs error but doesn't block
if [[ $FILE == ".env" ]]; then
echo "Don't edit .env" >&2
exit 1 # Tool still runs!
fi
# ✅ RIGHT - actually blocks
if [[ $FILE == ".env" ]]; then
echo "Blocked: .env is protected" >&2
exit 2 # Tool is blocked
fi
Why this matters: Exit 1 only logs errors. Exit 2 is required to block in PreToolUse hooks.
For exit code patterns: Load references/hook-templates.md for complete hook response patterns.
Error: Hook crashes when dependency is missing
Why: Not checking if tool is installed before using
Example:
# ❌ BREAKS if prettier not installed
prettier --write "$FILE"
# ✅ SAFE - check first
if command -v prettier &>/dev/null; then
prettier --write "$FILE"
else
echo "prettier not installed, skipping" >&2
exit 0 # Success exit, just skip
fi
Why this matters: Users may not have all tools installed. Hooks should degrade gracefully.
For reliability patterns: Load references/reliability-performance.md.
✅ Validate all JSON input before using (jq -r '... // empty')
✅ Quote all variables containing paths or user input
✅ Use absolute paths for scripts (${CLAUDE_PLUGIN_ROOT}/...)
✅ Block sensitive files (.env, *.key, credentials)
✅ Check if required tools exist (command -v toolname)
✅ Set reasonable timeouts (< 5s for PreToolUse)
✅ Run heavy operations in background
✅ Test with edge cases (spaces, Unicode, special chars)
✅ Use exit 2 to block in PreToolUse hooks
✅ Log errors to stderr or file, not stdout
❌ Trust JSON input without validation
❌ Use unquoted variables ($FILE instead of "$FILE")
❌ Use relative paths for scripts
❌ Skip path sanitization (check for .., validate in project)
❌ Assume tools are installed
❌ Block for > 1 second in PreToolUse hooks
❌ Use exit 1 when you mean to block (use exit 2)
❌ Log sensitive data to stdout or files
❌ Use matcher: "*" unless truly necessary
Load reference files when working on specific hook aspects:
references/security-requirements.md)Load when:
.env, keys, credentials)references/reliability-performance.md)Load when:
references/code-templates.md)Load when:
references/testing-debugging.md)Load when:
references/publishing-guide.md)Load when:
continue, stopReason, suppressOutput, systemMessagereferences/quick-reference.md)Load when:
Before publishing a hook:
.env, *.key, etc.)This skill includes 6 reference files for on-demand loading:
Security & Reliability (2 files):
security-requirements.md - Input validation, path sanitization, blocking sensitive filesreliability-performance.md - Error handling, timeouts, performance optimizationImplementation (2 files):
code-templates.md - Working hook examples (format-on-save, block-sensitive, logger, etc.)quick-reference.md - Fast syntax lookup (exit codes, jq patterns, environment vars)Testing & Publishing (2 files):
testing-debugging.md - Test patterns, edge cases, debugging techniquespublishing-guide.md - PRPM packaging, advanced configuration, README templateLoad references on-demand when specific knowledge is needed. See "When to Load References" section for triggers.
Last verified: 2025-12-17 | Version: 2.0.0
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.
Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.
Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.