Claude Code Hooks Playbook

A battle-tested guide to writing, testing, registering, and debugging Claude Code PreToolUse / PostToolUse / SessionStart / Stop hooks.

Dev & CodingAdvanced★ 1,323⑂ 212AI score 9/10Last updated: Aug 8, 2026

What it does

Turns rules that keep getting violated in prose (CLAUDE.md) into hard structural gates implemented as shell hooks.
Spells out each hook type's contract: PreToolUse (exit 2 blocks; stderr is the guidance the model sees), PostToolUse (inject authoritative context), SessionStart (always exit 0 health checks), Stop (the only hook that can react to the model's own output).
Encodes hard-won pitfalls as rules: token-level matching with shlex.shlex(punctuation_chars=True) instead of awk splitting, exempting git commit segments, bash -n + real-JSON end-to-end testing before registering, SSOT + symlink so a ~/.claude reinstall can't disarm the guard, multi-profile convergence, human-confirmation release gates instead of env-var escape hatches, explicit fail-open vs fail-closed direction, and a loop-variant termination proof for hooks that demand remediation.
Ships runnable skeletons in references/hook_patterns.md and a test harness in scripts/test_hook.sh.

Who it's for

Developers who live in Claude Code and want dangerous commands (force push, deletions, secret leaks) actually blocked.
Tech leads who want team policy enforced mechanically rather than by reminders.
Anyone debugging a hook that false-blocks, silently misses, or poisons the whole session.

Examples

"Make git push --force impossible" → author a PreToolUse Bash guard, test trigger vs healthy-lookalike JSON events, then register it in settings.json.
"Stop the model from inventing unverified names" → the skill routes this to a Stop hook (not UserPromptSubmit) and shapes a one-block message that reports every violation at once.
"Every Bash call broke after I added a hook" → run bash -n, replay the real event payload to find the session-poisoning bug, and add a SessionStart health check for dangling symlinks.

· · · Install guide · · ·

Try it now, no install

Paste this into Claude to use the skill without installing anything.

Read the instructions in this file and follow them to help me:
https://raw.githubusercontent.com/daymade/claude-code-skills/HEAD/daymade-claude-code/claude-code-hooks/SKILL.md

What I want: (describe your task here)

If Claude can't open the link, open it yourself and paste the contents instead.

↓ If it works for you, download the ZIP below and install it. Then it runs on its own — no pasting each time.

Install in the Claude app (no terminal)

Download the ZIP with the button below.
In Claude, open Settings → Capabilities and turn on 'Code execution and file creation'. (one time)
Go to Customize → Skills → + → 'Upload a skill' and upload the ZIP.

↓ Download ZIP

Install in Claude Code

Let Claude do it — paste this into Claude Code

Install the skill I found on Claude Skill Mart.
Copy the daymade-claude-code/claude-code-hooks folder from the GitHub repo daymade/claude-code-skills into my ~/.claude/skills/claude-code-hooks/.
When it's done, tell me in one line what this skill can do.

Install with a command instead

git clone https://github.com/daymade/claude-code-skills.git && mkdir -p ~/.claude/skills && cp -r claude-code-skills/daymade-claude-code/claude-code-hooks ~/.claude/skills/

⚠ This is a third-party skill. Check the source repository before installing.

Open a terminal.
Clone the repo: git clone https://github.com/daymade/claude-code-skills.git
Create the skills folder: mkdir -p ~/.claude/skills
Copy just this skill: cp -r claude-code-skills/daymade-claude-code/claude-code-hooks ~/.claude/skills/
Verify with ls ~/.claude/skills/claude-code-hooks — you should see SKILL.md, references/, and scripts/.
Restart Claude Code and ask something like "write a hook that blocks rm -rf" to trigger the skill.
Before registering any hook, always run bash -n and scripts/test_hook.sh — a broken PreToolUse hook can poison every Bash call in the session.

View source on GitHub ↗License: MIT