Hook Development

Create and validate event-driven hooks for Claude Code plugin automation.

Updated Aug 7, 2026
One-click install
npx skills add https://github.com/valeratrades/plugin-dev --skill hook-development-valeratrades
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: Hook Development
Source: https://github.com/valeratrades/plugin-dev/tree/main/skills/hook-development
Command: npx skills add https://github.com/valeratrades/plugin-dev --skill hook-development-valeratrades

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires jq, and includes scripts (resource) and references (resource) components.

What problem does it solve? Building Claude Code plugin hooks requires understanding multiple hook events, JSON output schemas, security constraints, and configuration formats, and mistakes can silently break user workflows or introduce injection vulnerabilities. ## Core Features & Use Cases - Hook Implementation Guidance: Covers all nine hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification) with both prompt-based and command hook patterns. - Validation and Testing Utilities: Ships scripts to validate hooks.json schema, test hook scripts with sample input, and lint hook code for security issues like unquoted variables and hardcoded paths. - Use Case: When adding a PreToolUse hook to block dangerous bash commands in a plugin, use this Skill to write the hooks.json entry with ${CLAUDE_PLUGIN_ROOT} paths, validate it with validate-hook-schema.sh, and test it with test-hook.sh before restarting Claude Code. ## Quick Start Create a PreToolUse prompt-based hook that validates file writes for path traversal and sensitive files, then validate the hooks.json configuration.

Frequently Asked Questions about Hook Development

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create a PreToolUse hook in Claude Code?▼

Define the hook in your plugin's hooks/hooks.json with a matcher for the target tools and a hooks array containing either a prompt or command type. Prompt hooks use natural language validation logic, while command hooks execute bash scripts that return JSON decisions.

What is the difference between prompt-based and command hooks?▼

Prompt hooks use LLM reasoning for context-aware validation and are recommended for complex logic on Stop, SubagentStop, UserPromptSubmit, and PreToolUse events. Command hooks run bash scripts for fast deterministic checks, file operations, and external tool integration.

Why are my hook changes not taking effect in Claude Code?▼

Hooks load only at session start, so editing hooks.json or hook scripts does not affect the current session. Exit Claude Code and restart with claude, then use claude --debug to verify the new hooks registered correctly.

How do I test a hook script before deploying it?▼

Use the test-hook.sh utility to run a hook script against sample JSON input with proper environment variables set. Generate sample input with --create-sample for any event type, then check exit codes and validate the JSON output with jq.

What security practices should Claude Code hook scripts follow?▼

Always quote bash variables, use set -euo pipefail, validate all input fields with jq, and use ${CLAUDE_PLUGIN_ROOT} instead of hardcoded paths. Send error messages to stderr and return exit code 0 for approval or 2 for blocking.