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.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
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.
version
0.1.0
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:
{"type":"prompt","prompt":"Evaluate if this tool use is appropriate: $TOOL_INPUT",
For plugin hooks in hooks/hooks.json, use wrapper format:
{"description":"Brief explanation of hooks (optional)","hooks":{"PreToolUse":[...],"Stop":[...],"SessionStart":[...]}}
Key points:
description field is optional
hooks field is required wrapper containing actual hook events
This is the plugin-specific format
Example:
{"description":"Validation hooks for code quality","hooks":{"PreToolUse":[{"matcher":"Write","hooks":[{"type":"command","command":"${CLAUDE_PLUGIN_ROOT}/hooks/validate.sh"}]}]}}
Settings Format (Direct)
For user settings in .claude/settings.json, use direct 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):
{"PreToolUse":[{"matcher":"Write|Edit","hooks":[{"type":"prompt","prompt":"Validate file write safety. Check: system paths, credentials, path traversal, sensitive content. Return 'approve' or 'deny'."}]}]}
Output for PreToolUse:
{"hookSpecificOutput":{"permissionDecision":"allow|deny|ask","updatedInput":{"field":"modified_value"}},"systemMessage":"Explanation for Claude"}
PostToolUse
Execute after tool completes. Use to react to results, provide feedback, or log.
Example:
{"PostToolUse":[{"matcher":"Edit","hooks":[{"type":"prompt","prompt":"Analyze edit result for potential issues: syntax errors, security vulnerabilities, breaking changes. Provide feedback."}]}]}
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:
{"Stop":[{"matcher":"*","hooks":[{"type":"prompt","prompt":"Verify task completion: tests run, build succeeded, questions answered. Return 'approve' to stop or 'block' with reason to continue."}]}]}
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:
{"UserPromptSubmit":[{"matcher":"*","hooks":[{"type":"prompt","prompt":"Check if prompt requires security guidance. If discussing auth, permissions, or API security, return relevant warnings."}]}]}
SessionStart
Execute when Claude Code session begins. Use to load context and set environment.
Plugin hooks merge with user's hooks and run in parallel.
Matchers
Tool Name Matching
Exact match:
"matcher":"Write"
Multiple tools:
"matcher":"Read|Write|Edit"
Wildcard (all tools):
"matcher":"*"
Regex patterns:
"matcher":"mcp__.*__delete.*"// All MCP delete tools
Note: Matchers are case-sensitive.
Common Patterns
// All MCP tools"matcher":"mcp__.*"// Specific plugin's MCP tools"matcher":"mcp__plugin_asana_.*"// All file operations"matcher":"Read|Write|Edit"// Bash commands only"matcher":"Bash"
Create hooks that activate conditionally by checking for a flag file or configuration:
Pattern: Flag file activation
#!/bin/bash# Only active when flag file exists
FLAG_FILE="$CLAUDE_PROJECT_DIR/.enable-strict-validation"if [ ! -f "$FLAG_FILE" ]; then# Flag not present, skip validationexit 0
fi# Flag present, run validation
input=$(cat)
# ... validation logic ...
Pattern: Configuration-based activation
#!/bin/bash# Check configuration for activation
CONFIG_FILE="$CLAUDE_PROJECT_DIR/.claude/plugin-config.json"if [ -f "$CONFIG_FILE" ]; then
enabled=$(jq -r '.strictMode // false'"$CONFIG_FILE")
if [ "$enabled" != "true" ]; thenexit 0 # Not enabled, skipfifi# Enabled, run hook logic
input=$(cat)
# ... hook logic ...
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.json won'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 claude again
To test hook changes:
Edit hook configuration or scripts
Exit Claude Code session
Restart: claude or cc
New hook configuration loads
Test hooks with claude --debug
Hook Validation at Startup
Hooks are validated when Claude Code starts:
Invalid JSON in hooks.json causes loading failure
Missing scripts cause warnings
Syntax errors reported in debug mode
Use /hooks command to review loaded hooks in current session.
Debugging Hooks
Enable Debug Mode
claude --debug
Look for hook registration, execution logs, input/output JSON, and timing information.
