--- name: plugin-add-hook description: Add a hook configuration to an existing Claude Code plugin argument-hint: " [--matcher ] [--type command|prompt]" user-invocable: true model: sonnet --- # plugin-add-hook Add a hook configuration to an existing Claude Code plugin with proper event binding and script template. ## When to Use Use this skill when: - Adding event-driven behavior to a plugin - You need to validate or modify tool operations - You want to automate workflows based on Claude actions ## Arguments | Argument | Required | Description | |----------|----------|-------------| | `plugin-dir` | Yes | Path to the plugin directory | | `event` | Yes | Hook event (PreToolUse, PostToolUse, etc.) | | `--matcher` | No | Tool\/pattern matcher (e.g., "Write", "Bash:npm") | | `--script-name` | No | Script filename (default: derived from event) | | `--timeout` | No | Script timeout in seconds (default: 10) | ## Example Usage ``` \/plugin-add-hook .\/my-plugin PreToolUse --matcher Write ``` ``` \/plugin-add-hook .\/my-plugin PostToolUse --matcher "Bash:npm test" --timeout 30 ``` ## Valid Events | Event | Trigger | Common Use | |-------|---------|------------| | `SessionStart` | Session begins | Initialize state | | `SessionEnd` | Session ends | Cleanup | | `UserPromptSubmit` | User sends message | Intent detection | | `PreToolUse` | Before tool runs | Validation, blocking | | `PostToolUse` | After tool succeeds | Verification, recording | | `PostToolUseFailure` | After tool fails | Recovery, retry | | `SubagentStart` | Agent spawns | Context setup | | `SubagentStop` | Agent finishes | Output processing | | `Stop` | Claude responds | Summarization | | `PermissionRequest` | Permission prompt | Auto-approve\/deny | ## Workflow When invoked, follow these steps: ### Step 1: Validate Arguments 1. Verify plugin directory exists 2. Verify event is valid Claude Code hook event 3. Validate matcher pattern (if provided) 4. Validate timeout is 1-60 seconds ### Step 2: Ensure Hooks Directory Create if not exists: ``` \/hooks\/ ├── hooks.json └── scripts\/ ``` ### Step 3: Generate Script Template Create `hooks\/scripts\/.sh`: ```bash #!\/bin\/bash # Hook: [] # Exit codes: 0=continue, 2=block, other=warning # # Input: JSON via stdin # See: https:\/\/code.claude.com\/docs\/en\/hooks set -euo pipefail # Read JSON input from stdin INPUT=$(cat) # Extract relevant fields based on event # Your hook logic here # Example: Validate, transform, block # Success - continue processing exit 0 ``` Event-specific templates: **PreToolUse:** ```bash TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name \/\/ empty') TOOL_INPUT=$(echo "$INPUT" | jq -r '.tool_input \/\/ empty') # Validate tool input # if [[ condition ]]; then # echo "ERROR: BLOCKED" >&2 # echo " what: Reason for blocking" >&2 # exit 2 # fi ``` **PostToolUse:** ```bash TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name \/\/ empty') TOOL_OUTPUT=$(echo "$INPUT" | jq -r '.tool_output \/\/ empty') # Process successful result # Log, record state, trigger next action ``` **UserPromptSubmit:** ```bash USER_PROMPT=$(echo "$INPUT" | jq -r '.user_prompt \/\/ empty') # Detect intent, set workflow context # Use json_output to provide context to Claude ``` ### Step 4: Update hooks.json Add configuration to `hooks\/hooks.json`: ```json { "hooks": { "": [ { "matcher": "", "hooks": [ { "type": "command", "command": "${PLUGIN_DIR}\/hooks\/scripts\/.sh", "timeout": } ] } ] } } ``` ### Step 5: Make Script Executable ```bash chmod +x hooks\/scripts\/.sh ``` ### Step 6: Update Plugin Manifest Add hook reference to `plugin.json`: ```json { "hooks": [ ..., "hooks\/hooks.json" ] } ``` ### Step 7: Update Workflow State If in plugin-build workflow: 1. Add hook to `phases.implement.components.hooks.items` 2. Increment `phases.implement.components.hooks.total` ### Step 8: Report Results ``` Hook added: [] Script: \/hooks\/scripts\/.sh Config: \/hooks\/hooks.json Exit codes: 0 = Continue (success) 2 = Block (stderr sent to Claude) other = Warning (continue with warning) Next steps: 1. Edit script to implement hook logic 2. Test hook with \/plugin-test 3. Run \/plugin-validate to check compliance ``` ## Validation Rules - Event must be valid Claude Code hook event - Matcher must be valid regex pattern (if provided) - Timeout must be 1-60 seconds - Script must not already exist (use `--force` to overwrite) ## Error Handling - If plugin directory doesn't exist: Report NOTFOUND error - If event is invalid: Report VALIDATION error with valid events list - If matcher is invalid regex: Report INPUT error - If script exists: Report error, suggest `--force` ## Matcher Patterns | Pattern | Matches | |---------|---------| | `Write` | All Write tool calls | | `Bash` | All Bash tool calls | | `Bash:npm` | Bash calls containing "npm" | | `.*test.*` | Tools with "test" in name | | `(Read\|Glob)` | Read or Glob tools |