MUST load when creating or modifying automation hooks. Provides security-hardened templates to prevent path traversal and infinite loops. Knowledge map for Claude Code hooks - event-driven automation that executes shell commands or LLM prompts in response to tool usage, session events, and user interactions.
Provides security-hardened templates and validation tools for creating Claude Code automation hooks. Use when configuring event-driven automation that executes commands or prompts in response to tool usage, session events, or user interactions.
/plugin marketplace add Git-Fg/thecattoolkit/plugin install git-fg-thecattoolkit@Git-Fg/thecattoolkitThis skill inherits all available tools. When active, it can use any tool Claude has access to.
assets/scripts/hook-tester.pyassets/scripts/path-validator.pyassets/templates/base-hook.pyassets/templates/blocking-hook.pyassets/templates/hooks-json.mdassets/templates/observer-hook.pyreferences/command-vs-prompt.mdreferences/examples.mdreferences/hook-examples.mdreferences/hook-types.mdreferences/input-output-schemas.mdreferences/matchers.mdreferences/troubleshooting.mdworkflows/audit.mdworkflows/create.mdworkflows/edit.mdHooks are event-driven automation for Claude Code. They execute shell commands or LLM prompts in response to:
Hooks operate within an event hierarchy: events trigger matchers (tool patterns) which execute hooks (commands or prompts). Hooks can block actions, modify tool inputs, inject context, or observe and log operations.
Three workflows exist for hook lifecycle management:
workflows/create.md) - Creating new hooks from templatesworkflows/edit.md) - Modifying existing hook configurationsworkflows/audit.md) - Security validation and testingassets/templates/)base-hook.py - Core template with path validation, error handling, and security patternsblocking-hook.py - Template for PreToolUse/Stop hooks that can approve/block actionsobserver-hook.py - Template for PostToolUse/SessionStart hooks that observe/reporthooks-json.md - Complete guide to hooks.json configuration structureassets/scripts/)path-validator.py - Reusable utility for validating file paths and preventing traversal attackshook-tester.py - Automated validation tool supporting all 11 hook event typesUsage: Import or copy these into .claude/hooks/scripts/ for use in hook configurations.
.claude/hooks/
├── hooks.json # Hook configuration
└── scripts/
└── protect-files.py # Hook script
Configuration:
{
"description": "File protection and security checks",
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "python3 ${CLAUDE_PLUGIN_ROOT}/.claude/hooks/scripts/protect-files.py"
}
]
}
]
}
}
| Event | Fires | Can Block? | Matcher Required? |
|---|---|---|---|
| PreToolUse | Before tool execution | Yes | Yes |
| PostToolUse | After tool execution | No | Yes |
| UserPromptSubmit | User submits a prompt | Yes | No |
| PermissionRequest | Permission dialog shown | Yes | No |
| Stop | Claude attempts to stop | Yes | No |
| SubagentStart | Subagent starts | No | No |
| SubagentStop | Subagent attempts to stop | Yes | No |
| SessionStart | Session begins | No | No |
| SessionEnd | Session ends | No | No |
| PreCompact | Before context compaction | Yes | No |
| Notification | Claude sends notifications | No | No |
See references/hook-types.md for complete event documentation including input/output schemas and use cases.
Type: Executes a shell command
Configuration:
{
"type": "command",
"command": "/path/to/script.sh",
"timeout": 30000
}
Use cases: Simple validation, logging, external tools, notifications
Input: JSON via stdin Output: JSON via stdout (optional)
Type: LLM evaluates a prompt
Configuration:
{
"type": "prompt",
"prompt": "Evaluate if this command is safe: $ARGUMENTS\n\nReturn JSON: {\"decision\": \"approve\" or \"block\", \"reason\": \"explanation\"}"
}
Use cases: Complex decision logic, natural language validation, context-aware checks, reasoning
Input: Prompt with $ARGUMENTS placeholder
Output: JSON with decision and reason
Matchers filter which tools trigger the hook:
{
"matcher": "Bash", // Exact match
"matcher": "Write|Edit", // Multiple tools (regex OR)
"matcher": "mcp__.*", // All MCP tools
"matcher": "mcp__memory__.*" // Specific MCP server
}
Optional for: UserPromptSubmit, PermissionRequest, Stop, SubagentStart, SubagentStop, SessionStart, SessionEnd, PreCompact, Notification
Input Format: JSON via stdin
{
"session_id": "string",
"transcript_path": "path",
"cwd": "path",
"permission_mode": "default|plan|acceptEdits|dontAsk|bypassPermissions",
"hook_event_name": "EventName",
"event_specific_data": "varies"
}
Output Format: JSON via stdout (blocking hooks)
{
"decision": "approve" | "block",
"reason": "explanation",
"continue": true,
"systemMessage": "warning"
}
See references/input-output-schemas.md for complete schemas per event type.
Available in hook commands:
$CLAUDE_PROJECT_DIR - Project root directory${CLAUDE_PLUGIN_ROOT} - Plugin directory (plugin hooks only)$ARGUMENTS - Hook input JSON (prompt hooks only){
"hooks": {
"Notification": [
{
"hooks": [
{
"type": "command",
"command": "osascript -e 'display notification \"Claude needs input\" with title \"Claude Code\"'"
}
]
}
]
}
}
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "prompt",
"prompt": "Check if this command is destructive: $ARGUMENTS\n\nBlock if it contains: 'git push --force', 'rm -rf', 'git reset --hard'\n\nReturn: {\"decision\": \"approve\" or \"block\", \"reason\": \"explanation\"}"
}
]
}
]
}
}
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "prettier --write $CLAUDE_PROJECT_DIR",
"timeout": 10000
}
]
}
]
}
}
{
"hooks": {
"SessionStart": [
{
"hooks": [
{
"type": "command",
"command": "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"SessionStart\", \"additionalContext\": \"Current sprint: Sprint 23. Focus: User authentication\"}}'"
}
]
}
]
}
}
Command: claude --debug
Shows hook execution details, command output, and matching information.
Hook Types: references/hook-types.md
Command vs Prompt: references/command-vs-prompt.md
Matchers: references/matchers.md
Input/Output Schemas: references/input-output-schemas.md
Working Examples: references/examples.md
Hook Examples Reference: references/hook-examples.md
Troubleshooting: references/troubleshooting.md
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
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.