Hook System Guide
hook-system
Claude Code Hook system entry point. Guides you to the right skill based on your needs.
SKILL.md
Full skill instructions
Hook System Guide
Entry point for Claude Code Hook system. Routes to appropriate skills.
What are Hooks?
Scripts that auto-execute at specific events during Claude Code sessions.
User Input → [UserPromptSubmit Hook] → Claude Processing
→ [PreToolUse Hook] → Tool Execution → [PostToolUse Hook]
→ Claude Response → [Stop Hook] → End
Skill Selection Guide
| Question | Skill |
|---|---|
| What can hooks do? | hook-capabilities |
| Need pattern/implementation examples | hook-capabilities → references |
| Need templates for quick start | hook-templates |
| Want to call LLM from hooks | hook-sdk-integration |
| Need cost optimization | hook-sdk-integration |
| Want background execution | hook-sdk-integration |
Quick Decision Tree
Hook Question
│
├─ "What's possible?" ──────→ hook-capabilities
│
├─ "How to implement?" ─────→ hook-capabilities/patterns-detailed.md
│
├─ "Need templates?" ───────→ hook-templates
│
├─ "LLM evaluation?" ───────→ hook-sdk-integration
│
└─ "Real project examples?" → hook-capabilities/real-world-examples.md
hook-sdk-integration/real-world-projects.md
Hook Skills Architecture
hook-system (You are here)
│ Entry Point
┌───────────────┼───────────────┐
▼ ▼ ▼
hook-capabilities hook-templates hook-sdk-integration
┌─────────────┐ ┌────────────┐ ┌─────────────────┐
│ WHAT/WHY │ │ HOW │ │ ADVANCED │
│ • Events │ │ • Gate │ │ • LLM calls │
│ • Patterns │ │ • Side Fx │ │ • Background │
│ • Debugging │ │ • Orch. │ │ • Cost optim. │
└─────────────┘ └────────────┘ └─────────────────┘
│ │
└──────────► workflow-state-patterns ◄┘
(Multi-phase flows)
Related Skills
| Skill | Role | When to Use |
|---|---|---|
hook-capabilities | Events, patterns, debugging | First stop - understanding what's possible |
hook-templates | Gate/Side-effect/Orchestration templates | Implementation - copy-paste ready code |
hook-sdk-integration | SDK/CLI LLM calls | Advanced - AI evaluation in hooks |
workflow-state-patterns | State-based multi-phase workflows | Complex - chained automation with gates |
Core Concepts
Activation Reliability
| Method | Success Rate | When to Use |
|---|---|---|
| Hook | 100% | Forced automation |
| Hook + Forced Eval | 84% | Skill activation |
| Skill (default) | ~20% | Simple suggestions |
| MCP (all tools) | ~13% | Many tools loaded |
| MCP (Tool Search) | ~43-88% | Enable enableToolSearch |
Events (10 types)
| Event | Can Block | Use For |
|---|---|---|
| SessionStart | ❌ | Initialization |
| UserPromptSubmit | ✅ | Context injection |
| PreToolUse | ✅ | Gate (block/modify) |
| PostToolUse | ❌ | Side Effects |
| Stop | ✅ | Termination control |
Data Passing
# Passed via stdin JSON (NOT environment variables!)
INPUT=$(cat)
SESSION_ID=$(echo "$INPUT" | jq -r '.session_id')
Blocking
exit 0 # Allow
exit 2 # Block (stderr → feedback to Claude)
MCP Tool Search
Enable for better tool selection (13% → 43%+):
{
"mcpServers": {
"my-server": {
"command": "...",
"enableToolSearch": true
}
}
}