jackproai/jackproai-claudecode3.1/hook-development
Claude Code and agent skill by jackproai/jackproai-claudecode3.1
- community
Checking that the SKILL.md file is still in the repository.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.
Install
npx vskill@latest install jackproai/jackproai-claudecode3.1/hook-developmentSKILL.md
The same SKILL.md was published earlier as aiskillstore/marketplace/hook-development.
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.
Key capabilities:
- Validate tool calls before execution (PreToolUse)
- React to tool results (PostToolUse)
- Enforce completion standards (Stop, SubagentStop)
- Load project context (SessionStart)
- Automate workflows across the development lifecycle
Hook Types
Prompt-Based Hooks (Recommended)
Use LLM-driven decision making for context-aware validation:
Supported events: Stop, SubagentStop, UserPromptSubmit, PreToolUse
Benefits:
- Context-aware decisions based on natural language reasoning
- Flexible evaluation logic without bash scripting
- Better edge case handling
- Easier to maintain and extend
Command Hooks
Execute bash commands for deterministic checks:
Use for:
- Fast deterministic validations
- File system operations
- External tool integrations
- Performance-critical checks
Hook Configuration Formats
Plugin hooks.json Format
For plugin hooks in hooks/hooks.json, use wrapper format:
Key points:
descriptionfield is optionalhooksfield is required wrapper containing actual hook events- This is the plugin-specific format
Example:
Settings Format (Direct)
For user settings in .claude/settings.json, use direct format:
Key points:
- No wrapper - events directly at top level
- No description field
- This is the settings format
Important: The examples below show the hook event structure that goes inside either format. For plugin hooks.json, wrap these in {"hooks": {...}}.
Hook Events
PreToolUse
Execute before any tool runs. Use to approve, deny, or modify tool calls.
Example (prompt-based):
Output for PreToolUse:
PostToolUse
Execute after tool completes. Use to react to results, provide feedback, or log.
Example:
Output behavior:
- Exit 0: stdout shown in transcript
- Exit 2: stderr fed back to Claude
- systemMessage included in context
Stop
Execute when main agent considers stopping. Use to validate completeness.
Example:
Decision output:
SubagentStop
Execute when subagent considers stopping. Use to ensure subagent completed its task.
Similar to Stop hook, but for subagents.
UserPromptSubmit
Execute when user submits a prompt. Use to add context, validate, or block prompts.
Example:
SessionStart
Execute when Claude Code session begins. Use to load context and set environment.
Example:
Special capability: Persist environment variables using $CLAUDE_ENV_FILE:
See examples/load-context.sh for complete example.
SessionEnd
Execute when session ends. Use for cleanup, logging, and state preservation.
PreCompact
Execute before context compaction. Use to add critical information to preserve.
Notification
Execute when Claude sends notifications. Use to react to user notifications.
Hook Output Format
Standard Output (All Hooks)
continue: If false, halt processing (default true)suppressOutput: Hide output from transcript (default false)systemMessage: Message shown to Claude
Exit Codes
0- Success (stdout shown in transcript)2- Blocking error (stderr fed back to Claude)- Other - Non-blocking error
Hook Input Format
All hooks receive JSON via stdin with common fields:
Event-specific fields:
- PreToolUse/PostToolUse:
tool_name,tool_input,tool_result - UserPromptSubmit:
user_prompt - Stop/SubagentStop:
reason
Access fields in prompts using $TOOL_INPUT, $TOOL_RESULT, $USER_PROMPT, etc.
Environment Variables
Available in all command hooks:
$CLAUDE_PROJECT_DIR- Project root path$CLAUDE_PLUGIN_ROOT- Plugin directory (use for portable paths)$CLAUDE_ENV_FILE- SessionStart only: persist env vars here$CLAUDE_CODE_REMOTE- Set if running in remote context
Always use ${CLAUDE_PLUGIN_ROOT} in hook commands for portability:
Plugin Hook Configuration
In plugins, define hooks in hooks/hooks.json:
Plugin hooks merge with user's hooks and run in parallel.
Matchers
Tool Name Matching
Exact match:
Multiple tools:
Wildcard (all tools):
Regex patterns:
Note: Matchers are case-sensitive.
Common Patterns
Security Best Practices
Input Validation
Always validate inputs in command hooks:
Path Safety
Check for path traversal and sensitive files:
See examples/validate-write.sh and examples/validate-bash.sh for complete examples.
Quote All Variables
Set Appropriate Timeouts
Defaults: Command hooks (60s), Prompt hooks (30s)
Performance Considerations
Parallel Execution
All matching hooks run in parallel:
Design implications:
- Hooks don't see each other's output
- Non-deterministic ordering
- Design for independence
Optimization
- Use command hooks for quick deterministic checks
- Use prompt hooks for complex reasoning
- Cache validation results in temp files
- Minimize I/O in hot paths
Temporarily Active Hooks
Create hooks that activate conditionally by checking for a flag file or configuration:
Pattern: Flag file activation
Pattern: Configuration-based activation
Use cases:
- Enable strict validation only when needed
- Temporary debugging hooks
- Project-specific hook behavior
- Feature flags for hooks
Best practice: Document activation mechanism in plugin README so users know how to enable/disable temporary hooks.
Hook Lifecycle and Limitations
Hooks Load at Session Start
Important: Hooks are loaded when Claude Code session starts. Changes to hook configuration require restarting Claude Code.
Cannot hot-swap hooks:
- Editing
hooks/hooks.jsonwon't affect current session - Adding new hook scripts won't be recognized
- Changing hook commands/prompts won't update
- Must restart Claude Code: exit and run
claudeagain
This is the start of the file. Read the full SKILL.md on GitHub.
Security
- Security scanPassed, 95 of 100Pattern checks on the skill's files.
- Model reviewPassed
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryChecking.claude-local-runtime/home/plugins/marketplaces/claude-plugins-official/plugins/plugin-dev/skills/hook-development/SKILL.md
Popularity
- Repository stars
- 251
- Repository forks
- 199
- 7-day trend score
- 28
Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/jackproai/jackproai-claudecode3.1/hook-development)