# plugin-add-hook

> Add a hook configuration to an existing Claude Code plugin

- Author: Edison
- Repository: soilmass/claudeutils
- Version: 20260127023329
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/soilmass/claudeutils
- Web: https://mule.run/skillshub/@@soilmass/claudeutils~plugin-add-hook:20260127023329

---

---
name: plugin-add-hook
description: Add a hook configuration to an existing Claude Code plugin
argument-hint: "<plugin-dir> <event> [--matcher <pattern>] [--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:
```
<plugin-dir>/hooks/
├── hooks.json
└── scripts/
```

### Step 3: Generate Script Template

Create `hooks/scripts/<script-name>.sh`:

```bash
#!/bin/bash
# Hook: <event> [<matcher>]
# 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
<event-specific-extraction>

# 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": {
    "<event>": [
      {
        "matcher": "<matcher or omit>",
        "hooks": [
          {
            "type": "command",
            "command": "${PLUGIN_DIR}/hooks/scripts/<script-name>.sh",
            "timeout": <timeout>
          }
        ]
      }
    ]
  }
}
```

### Step 5: Make Script Executable

```bash
chmod +x hooks/scripts/<script-name>.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: <event> [<matcher>]
Script: <plugin-dir>/hooks/scripts/<script-name>.sh
Config: <plugin-dir>/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 |