Skip to content
Skills Library
AI & agents · Learning & explanation

hooks

/hooks

Guide to Claude Code hooks — lifecycle events, handler types, decision control, and common patterns. Use when creating, debugging, or planning hooks for guardrails, context injection, quality gates, notifications, or automation.

Repository
crouton-kit ↗
Licence
GPL-3.0
Last repository change
02.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 02.10.2026, without references to retired models or APIs.

Licence

GPL-3.0, otwarta.

What it does and when to use it

Guide to Claude Code hooks — lifecycle events, handler types, decision control, and common patterns. Use when creating, debugging, or planning hooks for guardrails, context injection, quality gates, notifications, or automation.

Original author description

Guide to Claude Code hooks — lifecycle events, handler types, decision control, and common patterns. Use when creating, debugging, or planning hooks for guardrails, context injection, quality gates, notifications, or automation.

How it works

  1. When to Use Hooks vs Other Tools
  2. Hook Events
  3. Handler Types
  4. Decision Control
  5. Matchers
  6. Skill- and Agent-Scoped Hooks
  7. Common Patterns
  8. Best Practices
Original SKILL.md headings · 75 lines, 479 words
SKILL.md preview
---
name: hooks
description: Guide to Claude Code hooks — lifecycle events, handler types, decision control, and common patterns. Use when creating, debugging, or planning hooks for guardrails, context injection, quality gates, notifications, or automation.
user-invocable: false
paths:
  - "**/hooks.json"
  - "**/hooks/**/*.py"
  - "**/hooks/**/*.sh"
  - "**/hooks/**/*.mjs"
  - "**/hooks/**/*.js"
  - "**/hooks/**/*.ts"
---

# Claude Code Hooks

Hooks are deterministic handlers that fire at lifecycle events. Unlike instructions, hooks **cannot be ignored** — they block, inject, or modify at the system level.

## When to Use Hooks vs Other Tools

- **Hooks**: Must happen every time, no exceptions (guardrails, formatting, enforcement)
- **Rules/CLAUDE.md**: Advisory guidance Claude should follow (conventions, preferences)
- **Skills**: On-demand reference material (knowledge, methodology)

## Hook Events

Hooks fire at three points in execution: before the user or agent acts (`UserPromptSubmit`, `PreToolUse`), after the system acts (`PostToolUse`, `Stop`), and during agent lifecycle transitions (`SubagentStart`, `TaskCompleted`). Session bookend events (`SessionStart`, `SessionEnd`) handle setup and teardown. See [reference.md](reference.md) for the full event list with blocking/injection capabilities per event.

## Handler Types

Pick based on how complex the decision is:

| Handler | Use when... |
|---------|-------------|
| **command** | Logic is deterministic — regex check, file exists, env var set. Fastest. |
| **prompt** | Decision requires judgment but no file access — "is this prompt asking for secrets?" |
| **agent** | Decision requires investigation — read files, run commands, check state. |
| **http** | Hook logic lives outside the machine — shared enforcement service, cross-team policy. |

Default to `command`. Escalate to `prompt` only when a shell script can't encode the judgment. Use `agent` sparingly — it spawns a subagent and adds real latency.

## Decision Control

All hook output must be wrapped in `hookSpecificOutput` with the matching `hookEventName`. **`hookEventName` is required** — without it, Claude Code silently drops the payload.

```json
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "additionalContext": "injected text"
  }
}
```

See [reference.md](reference.md) for the full per-event return value spec (`permissionDecision`, `updatedInput`, `decision: "block"`, etc.).

## Matchers

Use `|` to target multiple tools: `"matcher": "Write|Edit|MultiEdit"`. MCP tools match as `mcp__servername__toolname`. Omit matcher to catch all tools for that event.

See [reference.md](reference.md) for full matcher syntax including SessionStart variants.

## Skill- and Agent-Scoped Hooks

Hooks can be declared in `SKILL.md` or agent frontmatter to scope them to that skill/agent only — useful for guardrails that shouldn't apply globally. Uses the same matcher/handler format as `hooks.json`, nested under `hooks:` in frontmatter. See [reference.md](reference.md) for a full example.

## Common Patterns

See [patterns.md](patterns.md) for comprehensive examples organized by category:
- Guardrails and enforcement
- Context injection
- Quality gates (auto-format, lint, test)
- Notifications and alerts
- Logging and auditing
- Auto-approval workflows
- Input modification and sandboxing
- Git workflow automation
- Session management
- Agent team coordination

## Best Practices

- **Async for slow operations**: Set `"async": true` for hooks that shouldn't block (tests, notifications)
- **Timeouts**: Default is 60s for sync hooks. Set explicit timeouts for fast hooks.
- **Idempotency**: Hooks may fire multiple times. Guard against duplicate processing.
- **Stop hook loops**: Always check `stop_hook_active` to prevent infinite continuation loops.
- **Minimal hooks.json**: One concern per hook. Compose multiple small hooks rather than one monolith.
Files in this package (3)
  • SKILL.md 4 KB
  • patterns.md 5 KB
  • reference.md 5 KB

Versions

RepositoryScoreLicence
This page · CaptainCrouton89/crouton-kit100GPL-3.0
ai-answer/contentrepurposesystem100MIT
stxrmik/antigravity-plus100MIT
nimadorostkar/Claude-Skills-collection100MIT
opus-pro/reel-runbook100MIT
Rohitjangid2704/Tessa90MIT

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version b66d3e775780 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90Creating Hooks
    Build event-driven hooks in Claude Code for validation, setup, and automation. Use when you need to validate inputs, check environment state, or automate tasks at specific lifecycle events.
  • 95hook-dev
    Use this skill when creating or refining Claude Code hooks. Hooks are shell commands that execute at specific lifecycle events (tool use, prompt submit, notifications, session events). Helps design event handlers for notifications, formatting, logging, feedback, and permission…
  • 100claude-code-hooks
    Claude Code hooks configuration patterns, event types, validation scripts, and decision control for automating workflows and integrating external tools. This skill should be used when creating hooks, validating tool usage, automating workflows, or integrating external tools with Claude Code.
  • 100error-handling
    Debug and recover from agent team errors including common errors, hooks for quality gates, known limitations, and recovery strategies. Use when encountering team errors, enforcing quality gates with hooks, understanding limitations, or debugging agent issues.
  • 95creating-claude-hooks
    Use when creating or publishing Claude Code hooks - covers executable format, event types, JSON I/O, exit codes, security requirements, and PRPM package structure
  • 95creating-claude-hooks
    Use when creating or publishing Claude Code hooks - covers executable format, event types, JSON I/O, exit codes, security requirements, and PRPM package structure

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.