managing-hooks_skill

Overview

This skill is a practical guide for creating, configuring, and using Claude Code hooks to validate and control agent behavior. It focuses on implementing Prompt-based and Command-based hooks, configuring event-driven hook mappings, and handling input/output and exit semantics. Use this when you need precise control over PreToolUse, PostToolUse, Stop, and related hook events.

How this skill works

The skill explains how hooks receive JSON on stdin and must return structured JSON and exit codes to indicate continue, suppress output, or block. It covers two hook types: prompt hooks (LLM-driven, for complex validation) and command hooks (shell-driven, for fast deterministic checks). It also describes how to map hooks to events and matchers in a hooks configuration file and how environment variables and timeouts affect execution.

When to use it

• When creating or modifying hooks for Claude Code plugins
• When implementing PreToolUse, PostToolUse, Stop, SessionStart, or SessionEnd hooks
• When validating or blocking risky tool usage before execution
• When configuring event-driven automation tied to specific tool matchers
• When you need clear exit-code semantics and structured I/O for hook communication

Best practices

• Prefer prompt hooks for context-aware or safety-sensitive validation and command hooks for quick deterministic checks
• Always use ${CLAUDE_PLUGIN_ROOT} for portable paths and quote shell variables to avoid injection
• Validate and sanitize all inputs received on stdin; never trust user-supplied data
• Set conservative timeouts: 5–10s for quick checks, ~30s standard, 60s for complex tasks; avoid hooks >60s
• Do not hardcode absolute paths, avoid logging sensitive data, and design hooks to be idempotent

Example use cases

• PreToolUse prompt hook that evaluates whether a proposed file write is safe and returns allow/deny/ask
• Command hook that runs a fast static check or linter before allowing a code-modifying tool
• Stop hook that verifies task completion and either approves or blocks finalization
• SessionStart hook that prepares environment context or loads policy settings
• PostToolUse hook that logs metadata and non-sensitive feedback for auditing