Agent skill

hook-templates

Comprehensive Claude Code hook patterns for automation, state management, and external integration. Use when implementing hooks for validation, workflow gates, MCP integration, or state machines.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/development/hook-templates

SKILL.md

Hook Patterns

Production-tested patterns for Claude Code hooks (1.0.40+).

Hook Roles (Beyond Just Validation)

Role Hook Event Example
Gate PreToolUse Block dangerous commands, require prerequisites
Side Effect PostToolUse Auto-format, auto-commit, lint
State Manager PostToolUse Create/delete state files, track workflow phase
External Integrator Any MCP calls, HTTP APIs, WebSocket
Context Injector SessionStart Load project context, activate services

Event Reference

Event Trigger Can Block Use For
SessionStart Session begins No Context loading, service activation
UserPromptSubmit User sends message Yes Prompt validation, skill suggestion
PreToolUse Before tool Yes Validation, workflow gates
PostToolUse After tool No State updates, side effects
Stop Claude stops Yes Quality gates, cleanup
SubagentStop Subagent stops Yes Subagent quality gates

Exit Codes

Code PreToolUse/Stop Others
0 Allow Continue
2 Block (stderr→Claude) Logged
1, 3+ Block Logged

JSON Response (Advanced)

json
{
  "decision": "approve|block",
  "reason": "Shown to user/Claude",
  "continue": true,
  "suppressOutput": false
}

Quick Registration

json
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{ "type": "command", "command": "script.sh", "timeout": 5 }]
    }]
  }
}

Pattern Selection

Need Pattern Reference
Force skill/agent activation Orchestration orchestration-templates.md
Block dangerous actions Gate Pattern gate-patterns.md
Auto-format/lint/commit Side Effect Pattern side-effect-patterns.md
Full working examples Examples full-examples.md

Orchestration Patterns (NEW)

Hook-based skill/agent activation with reliability stats:

Pattern Success Use Case
Forced Evaluation 84% Force Claude to evaluate and use skills
Agent Router 100% Route to plugin agents via Task tool
Context Injection 100% Load project context at session start

See orchestration-templates.md for templates.

Debugging

Common issues and solutions in debugging-guide.md.

Quick checklist:

  • Hook executable? (chmod +x)
  • Using INPUT=$(cat) to read stdin?
  • Using exit 2 for blocking (not exit 1)?
  • Debug to stderr (>&2), output to stdout?
  • New session after settings.json change?

Common Mistakes

  • Missing nested hooks array
  • Missing "type": "command"
  • Using exit 1 instead of exit 2 for blocking
  • Object matcher (not supported) - use script parsing instead

Didn't find tool you were looking for?

Be as detailed as possible for better results