hook-development
[Utility] Guide for developing Claude Code hooks - shell commands that execute automatically in response to tool calls and notifications. Use this when users want to create, debug, or optimize hooks for automating workflows like linting, formatting, notifications, or custom validations. Supports PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification events.
When & Why to Use This Skill
This Claude skill provides a comprehensive guide for developing, debugging, and optimizing Claude Code hooks—event-driven shell commands and prompt-based scripts that automate developer workflows. It enables seamless integration of custom validations, linting, formatting, and notifications directly into the AI agent's lifecycle, enhancing productivity and ensuring code quality through automated triggers.
Use Cases
- Automated Code Quality: Trigger linting and formatting tools like ESLint or Prettier automatically after the agent modifies files (PostToolUse) to maintain style consistency.
- Security and Policy Guardrails: Implement PreToolUse hooks to intercept and validate shell commands or file edits against organizational security policies before execution.
- Workflow Notifications: Configure system or Slack notifications to alert developers when a long-running agent task completes or when a subagent finishes its assignment (SubagentStop).
- Environment Initialization: Use SessionStart hooks to automatically load project-specific environment variables or inject relevant architectural context into the agent's session.
- Deterministic Validation: Execute bash scripts during the 'Stop' event to perform final checks, such as running a test suite, to ensure the agent's output meets all requirements.
| name | hook-development |
|---|---|
| description | "[Utility] Guide for developing Claude Code hooks - shell commands that execute automatically in response to tool calls and notifications. Use this when users want to create, debug, or optimize hooks for automating workflows like linting, formatting, notifications, or custom validations. Supports PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification events." |
Hook Development for Claude Code Plugins
Overview
Hooks are event-driven automation scripts that execute in response to Claude Code events. Use hooks to validate operations, enforce policies, add context, and integrate external tools into workflows.
Hook Types
Prompt-Based Hooks (Recommended)
Use LLM-driven decision making for context-aware validation.
Command Hooks
Execute bash commands for deterministic checks.
Hook Events
| Event | When | Use For |
|---|---|---|
| PreToolUse | Before tool | Validation, modification |
| PostToolUse | After tool | Feedback, logging |
| UserPromptSubmit | User input | Context, validation |
| Stop | Agent stopping | Completeness check |
| SubagentStop | Subagent done | Task validation |
| SessionStart | Session begins | Context loading |
| SessionEnd | Session ends | Cleanup, logging |
| PreCompact | Before compact | Preserve context |
| Notification | User notified | Logging, reactions |
Environment Variables
$CLAUDE_PROJECT_DIR- Project root path$CLAUDE_PLUGIN_ROOT- Plugin directory$CLAUDE_ENV_FILE- SessionStart only: persist env vars here
Best Practices
- Use prompt-based hooks for complex logic
- Use ${CLAUDE_PLUGIN_ROOT} for portability
- Validate all inputs in command hooks
- Set appropriate timeouts