hooks-builder

bsamiee's avatarfrom bsamiee

Creates and configures Claude Code hooks for lifecycle automation. Use when implementing PreToolUse validation, PostToolUse formatting, PermissionRequest auto-approve, custom notifications, session management, or deterministic agent control.

⭐1stars🔀0forks📁View on GitHub🕐Updated Dec 27, 2025⬇️1downloads
[Tool Routing and Orchestration]

When & Why to Use This Skill

The hooks-builder skill empowers developers to implement lifecycle automation for Claude Code agents by configuring deterministic hooks. It allows users to execute shell commands or LLM-powered prompts at critical agent events—such as tool execution, permission requests, and session boundaries—ensuring precise control, enhanced safety, and seamless integration into existing development workflows.

Use Cases

  • Pre-execution Validation: Intercept and validate tool parameters or security constraints before the agent executes a command to prevent unauthorized actions.
  • Automated Permission Management: Streamline workflows by setting up auto-approval logic for specific, low-risk tool requests while maintaining manual gates for sensitive operations.
  • Post-action Formatting and Linting: Automatically trigger code quality tools like Prettier or Black immediately after the agent modifies files to ensure style consistency.
  • Custom Lifecycle Notifications: Integrate with communication platforms like Slack or email to receive real-time alerts when the agent completes a task or hits a specific milestone.
  • Deterministic Agent Control: Replace unpredictable prompt-based instructions with shell-based hooks to enforce strict execution guarantees and business logic.
namehooks-builder
typestandard
depthextended
description>-

[H1][HOOKS-BUILDER]

Dictum: Deterministic behavior requires hooks; prompts fail execution guarantees.


Build Claude Code hooks—shell commands execute at agent lifecycle events.

Tasks:

  1. Read index.md — Reference file listing for navigation
  2. Read lifecycle.md — Event table, input schemas, exit codes
  3. Read schema.md — Configuration structure, matchers, JSON responses
  4. (integration) Read integration.md — Environment variables, context injection
  5. (scripting) Read scripting.md — Python standards, security patterns
  6. (recipes) Read recipes.md — Proven implementation patterns
  7. (troubleshooting) Read troubleshooting.md — Known issues, platform workarounds
  8. (prose) Load style-standards skill — Voice, formatting, constraints
  9. Validate — Quality gate; see §VALIDATION

Scope:

  • Event Selection: Choose hook type by automation goal (blocking vs observing).
  • Configuration: Author settings.json entries with matchers and timeouts.
  • Response Handling: Control agent via exit codes, JSON responses, or prompt evaluation.

[REFERENCE]: index.md — Complete reference file listing

[1][EVENT_SELECTION]

Dictum: Automation goal determines hook type; blocking capability varies by event.


Decision Gate:

  • Intercept before execution? → PreToolUse (validate/block/modify parameters)
  • Control permission dialogs? → PermissionRequest (auto-approve/deny)
  • React after completion? → PostToolUse (format, lint, add context)
  • Inject at session boundaries? → SessionStart (context), UserPromptSubmit (per-message)
  • Evaluate task completion? → Stop/SubagentStop (prompt type for LLM judgment)

Blocking vs Observing:

  • Blocking (exit 2): PreToolUse, PermissionRequest, PostToolUse, UserPromptSubmit, Stop, SubagentStop
  • Observing only: Notification, PreCompact, SessionStart, SessionEnd

[2][CONFIGURATION]

Dictum: Centralized configuration enables scope-aware hook precedence.


[INDEX] [SCOPE] [PATH] [USE] [GIT]
[1] User ~/.claude/settings.json Global, all projects N/A
[2] Project .claude/settings.json Shared, committed Commit
[3] Local .claude/settings.local.json Personal, testing Ignore

Precedence: Local > Project > User.

[3][IMPLEMENTATION]

Dictum: Deterministic and evaluative patterns require distinct execution modes.


[INDEX] [TYPE] [USE_CASE] [TIMEOUT] [CHARACTERISTICS]
[1] command Validation, formatting, rules 60s Deterministic, fast
[2] prompt Complex evaluation, LLM judgment 30s Context-aware, flexible

Prompt Type Scope: Stop and SubagentStop events only; Haiku provides fast LLM evaluation.

Guidance:

  • Command hooks — Deterministic scripts receive JSON stdin; return exit codes + optional JSON stdout.
  • Prompt hooks — LLM evaluates decisions; response schema: {"decision": "approve"|"block", "reason": "..."}.
  • Blocking — Exit code 2 blocks action; stderr routes to Claude. Exit 1 also blocks (known bug #4809).

[4][SCRIPTING]

Dictum: Hook reliability requires functional pipeline patterns.


Python 3.14+ with strict typing. Zero imperative patterns.

[5][VALIDATION]

Dictum: Gates prevent incomplete artifacts.


[VERIFY] Completion:

  • Event: Selected correct hook type for automation goal.
  • Schema: Configuration structure validated per schema.md.
  • Integration: Environment variables and context injection applied.
  • Scripting: Security patterns and tooling gates passed.
  • Quality: JSON syntax valid, timeouts appropriate.

[REFERENCE] Operational checklist: →validation.md