hooks-development

Original：🇺🇸 English

Translated

Claude Code hooks development guide. TRIGGERS - create hook, PostToolUse, PreToolUse, Stop hook, hook lifecycle, decision block.

1installs

Sourceterrylica/cc-skills

Added on2026-02-07

NPX Install

npx skill4agent add terrylica/cc-skills hooks-development

SKILL.md Content

View Translation Comparison →

Hooks Development

Guide for developing Claude Code hooks with proper output visibility patterns.

When to Use This Skill

Creating a new PostToolUse or PreToolUse hook
Hook output is not visible to Claude (most common issue)
User asks about
```
decision: block
```
pattern
Debugging why hook messages don't appear
User mentions "Claude Code hooks" or "hook visibility"

Quick Reference: Visibility Patterns

Critical insight: PostToolUse hook stdout is only visible to Claude when JSON contains

"decision": "block"

.

Output Format	Claude Visibility
Plain text	Not visible
JSON without `decision: block`	Not visible
JSON with `decision: block`	Visible

Exit code behavior:

Exit Code	stdout Behavior	Claude Visibility
0	JSON parsed, shown in verbose mode only	Only if `"decision": "block"`
2	Ignored, uses stderr instead	stderr shown to Claude
Other	stderr shown in verbose mode	Not shown to Claude

Minimal Working Pattern

bash

/usr/bin/env bash << 'SKILL_SCRIPT_EOF'
#!/usr/bin/env bash
set -euo pipefail

# Read hook payload from stdin
PAYLOAD=$(cat)
FILE_PATH=$(echo "$PAYLOAD" | jq -r '.tool_input.file_path // empty')

[[ -z "$FILE_PATH" ]] && exit 0

# Your condition here
if [[ condition_met ]]; then
    jq -n \
        --arg reason "[HOOK] Your message to Claude" \
        '{decision: "block", reason: $reason}'
fi

exit 0
SKILL_SCRIPT_EOF

Key points:

Use
```
jq -n
```
to generate valid JSON
Include
```
"decision": "block"
```
for visibility
Exit with code 0
The "blocking error" label is cosmetic - operation continues

TodoWrite Templates

Creating a PostToolUse Hook

markdown

1. [pending] Create hook script with shebang and set -euo pipefail
2. [pending] Parse PAYLOAD from stdin with jq
3. [pending] Add condition check for when to trigger
4. [pending] Output JSON with decision:block pattern
5. [pending] Register hook in hooks.json with matcher
6. [pending] Test by editing a matching file
7. [pending] Verify Claude sees the message in system-reminder

Debugging Invisible Hook Output