hook-system

Original source / Raw SKILL.md

---
name: hook-system
description: Claude Code Hook system entry point. Guides you to the right skill based on your needs.
allowed-tools: ["Read"]
---

# 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

```bash
# Passed via stdin JSON (NOT environment variables!)
INPUT=$(cat)
SESSION_ID=$(echo "$INPUT" | jq -r '.session_id')
```

### Blocking

```bash
exit 0   # Allow
exit 2   # Block (stderr → feedback to Claude)
```

### MCP Tool Search

Enable for better tool selection (13% → 43%+):

```json
{
  "mcpServers": {
    "my-server": {
      "command": "...",
      "enableToolSearch": true
    }
  }
}
```

## References

- [Detailed Skill Selection Guide](references/skill-map.md)


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/skill-map.md

```markdown
# Hook Skill Selection Guide

## Skill Mapping by Situation

### Learning / Understanding Phase

| Situation | Skill | File |
|-----------|-------|------|
| New to Hook system | hook-system | SKILL.md |
| Want to know available events | hook-capabilities | event-details.md |
| Want to know what's possible/impossible | hook-capabilities | SKILL.md (Can vs Cannot) |

### Implementation Phase

| Situation | Skill | File |
|-----------|-------|------|
| Block dangerous commands | hook-capabilities | patterns-detailed.md (Gate) |
| Auto-action after file changes | hook-capabilities | patterns-detailed.md (Side Effect) |
| Track session state | hook-capabilities | patterns-detailed.md (State) |
| Send Slack/Discord notifications | hook-capabilities | advanced-patterns.md |
| Auto-commit to Git | hook-capabilities | advanced-patterns.md |

### LLM Integration

| Situation | Skill | File |
|-----------|-------|------|
| Need AI evaluation in hooks | hook-sdk-integration | SKILL.md |
| Background LLM calls | hook-sdk-integration | background-agent.md |
| Cost optimization methods | hook-sdk-integration | cost-optimization.md |
| type: "prompt" vs SDK comparison | hook-sdk-integration | SKILL.md |

### Advanced Patterns

| Situation | Skill | File |
|-----------|-------|------|
| Force skill/agent activation | hook-capabilities | **orchestration-patterns.md** |
| Hook → Agent → Skill pattern | hook-capabilities | orchestration-patterns.md |
| Iteration Control | hook-capabilities | advanced-patterns.md |
| Promise Detection | hook-capabilities | advanced-patterns.md |
| Transcript Parsing | hook-capabilities | advanced-patterns.md |
| Workflow State Machine | workflow-state-patterns | SKILL.md |

### Templates / Quick Start

| Situation | Skill | File |
|-----------|-------|------|
| Need Gate Hook template | hook-templates | gate-patterns.md |
| Need Side Effect template | hook-templates | side-effect-patterns.md |

## Skill Relationship Diagram

```
hook-system (Entry Point)
    │
    ├─→ hook-capabilities (What: events, patterns, possibilities)
    │       │
    │       ├─→ event-details.md (10 event specs)
    │       ├─→ patterns-detailed.md (30 basic patterns)
    │       ├─→ orchestration-patterns.md (force skill/agent activation) ★ NEW
    │       ├─→ advanced-patterns.md (advanced combo patterns)
    │       └─→ real-world-examples.md (implementation examples)
    │
    ├─→ hook-sdk-integration (SDK/CLI LLM calls)
    │       │
    │       ├─→ sdk-patterns.md (u-llm-sdk usage)
    │       ├─→ background-agent.md (non-blocking execution)
    │       ├─→ cost-optimization.md (cost structure)
    │       └─→ real-world-projects.md (GitHub projects)
    │
    ├─→ hook-templates (Quick implementation templates)
    │
    └─→ workflow-state-patterns (State-based workflows)
```

## FAQ

### Q: Can hooks modify files?
**A**: Yes → hook-capabilities/patterns-detailed.md (PostToolUse)

### Q: Can hooks call external APIs?
**A**: Yes → hook-capabilities/advanced-patterns.md (External Integration)

### Q: Can hooks call Claude?
**A**: Yes → hook-sdk-integration (Background Agent recommended)

### Q: Does type: "prompt" hook incur costs?
**A**: Yes (subscription usage) → hook-sdk-integration/cost-optimization.md

### Q: Can I get session info via environment variables?
**A**: No (stdin JSON) → hook-capabilities/SKILL.md (Data Passing section)

### Q: How can I force skill activation reliably?
**A**: Use Forced Eval pattern (84%) or Hook → Agent → Skill (100%) → hook-capabilities/orchestration-patterns.md

### Q: Why doesn't Claude use my skill automatically?
**A**: Skills have ~20% activation rate by default (description matching only). Use hooks to force. → hook-capabilities/orchestration-patterns.md

```