Overview

This skill guides building or updating Claude Code hook configurations and scripts for command, prompt, and agent workflows. It emphasizes deterministic validation, executable hook handlers, and reliable plugin integration.

How This Skill Works

Identify required hook events, matchers, and hook types, then implement hooks.json using stable CLAUDE_PLUGIN_ROOT paths. Add or update hook handler scripts, ensure they are executable, and run hook validation plus smoke tests. Finally verify plugin-level integration through implement-plugin and plugin-verification.

When to Use It

• When adding a new command, prompt, or agent hook
• When updating hook behavior or payload handling
• Before releasing a plugin, to validate hook configurations
• During integration with implement-plugin and plugin-verification
• When performing hook script smoke tests to ensure reliability

Quick Start

1. Step 1: Identify required hook events, matcher patterns, and hook type(s).
2. Step 2: Implement hooks.json using stable paths and place scripts in hooks/.
3. Step 3: Run validations, smoke tests, and verify plugin integration

Best Practices

• Use stable CLAUDE_PLUGIN_ROOT paths in all hook configs
• Keep hooks.json deterministic to minimize drift
• Mark hook scripts executable and test locally before commit
• Run scripts/validate-hooks.sh and scripts/test-hook-script.sh regularly
• Document event types, matchers, and payload shapes with reference docs

Example Use Cases

• Updated command hook example using assets/templates/command-hook-example.sh
• Prompt hook example using assets/templates/prompt-hook-example.json
• Agent hook example using assets/templates/agent-hook-example.json
• Hook validation run via scripts/validate-hooks.sh
• Hook script smoke test via scripts/test-hook-script.sh

Frequently Asked Questions