Craft Hook

Skill: Craft Hook

"The Subconscious. Automatic reactions."

0. Read The Docs First

https://code.claude.com/docs/en/hooks is the source of truth. This skill is what we learned around it, and Anthropic adds events without asking us.

1. The Principles

• Thin: Hooks point to skills. They don't contain protocols.
• Invisible: A good hook is never noticed. It just works.
• Non-Blocking: Hooks complete quickly. Long tasks belong in agents.
• Focused: One hook, one job. Use matchers to target precisely.
• Verified: Test that Claude actually sees your output.

The Thin Hook Rule

If you're writing more than 5 lines of protocol/criteria in a hook, it belongs in a skill.

HOOK RESPONSIBILITY              SKILL RESPONSIBILITY
├── WHEN to inject               ├── HOW to do it
├── WHAT to tell Claude          ├── WHY to do it
├── Formatting (emojis)          └── Decision criteria
└── Exit code / JSON output

Anti-pattern: Duplicating skill content in hooks.

2. Context Injection Rules

Critical: Not all hooks can inject to Claude's context. Know the rules:

The Rules

1. SessionStart/UserPromptSubmit/Setup: Plain stdout goes to Claude. Just echo.
2. PreToolUse/PostToolUse: Must use JSON with additionalContext OR exit 2 with stderr.
3. Stop/SubagentStop: Use decision: "block" with reason to force continuation.
4. PreCompact: Cannot inject to Claude at all. Don't use for context preservation.

3. Implementation

• Location: hooks/hooks.json
• Paths: Use ${CLAUDE_PLUGIN_ROOT} for portability
• Testing: Verify with claude --debug to see hook execution

4. Deeper