Hook Development

Create and validate event-driven hooks for Claude Code plugins using prompt-based and command configurations.

Updated Mar 22, 2026
One-click install
npx skills add https://github.com/ace8991/agentos --skill hook-development-ace8991
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: Hook Development
Source: https://github.com/ace8991/agentos/tree/main/.tmp_claude_code/claude-code-main/plugins/plugin-dev/skills/hook-development
Command: npx skills add https://github.com/ace8991/agentos --skill hook-development-ace8991

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve? Building event-driven automation for Claude Code requires understanding hook events, JSON configuration formats, input/output schemas, and security practices, which is error-prone without structured guidance and validation tooling. ## Core Features & Use Cases - Hook Implementation Guidance: Covers all hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification) with both prompt-based and command hook patterns. - Validation and Testing Scripts: Includes validate-hook-schema.sh for hooks.json structure checks, test-hook.sh for running hooks against sample input, and hook-linter.sh for best-practice enforcement. - Reference Documentation: Provides proven hook patterns, migration guidance from command to prompt hooks, and advanced techniques like caching, rate limiting, and cross-event workflows. - Use Case: When adding a PreToolUse hook to block dangerous bash commands in a plugin, use this Skill to write the hooks.json entry, validate it with the schema script, and test it with sample input before restarting Claude Code. ## Quick Start Create a PreToolUse prompt-based hook in my plugin's hooks.json that validates file writes for path traversal and sensitive files.

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?

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

What is the difference between prompt hooks and command hooks?

Prompt hooks use LLM reasoning for context-aware validation and are easier to maintain, while command hooks run bash scripts for fast deterministic checks. Prompt hooks are supported on Stop, SubagentStop, UserPromptSubmit, and PreToolUse events.

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

Hooks load only at session start, so editing hooks.json or hook scripts requires restarting Claude Code. Use the /hooks command to review loaded hooks and run claude --debug to inspect registration and execution logs.

How do I test a hook script before deploying it?

Use the test-hook.sh script with a sample JSON input file, which you can generate with the --create-sample flag for a given event type. It sets up environment variables, measures execution time, and validates the output JSON and exit codes.

What exit codes should a Claude Code hook script return?

Hook scripts should exit 0 for success, where stdout appears in the transcript, or exit 2 for a blocking error, where stderr is fed back to Claude. Other exit codes are treated as non-blocking errors.