# hook-create

> Creates an individual hook script with proper shell structure. Use when: adding validation guards, workflow automation, or event-driven triggers.

- 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~hook-create:20260127023329

---

---
name: hook-create
description: >-
  Creates an individual hook script with proper shell structure. Use when:
  adding validation guards, workflow automation, or event-driven triggers.
license: MIT
metadata:
  author: claudeutils
  version: "1.0.0"
allowed-tools: Read Write Glob Bash
disable-model-invocation: true
user-invocable: true
argument-hint: "<name> <event> [--matcher pattern] [--category guards|workflows|session]"
---

## Task

Create a new hook script that follows Claude Code hook conventions.

## Input

- `$0`: Hook name (lowercase, hyphens, 1-64 chars)
- `$1`: Event type (required)
- `--matcher`: Optional tool/trigger pattern (e.g., "Write", "Bash")
- `--category`: guards | workflows | session (default: workflows)

## Valid Events

- `SessionStart`: Session begins
- `UserPromptSubmit`: User sends message
- `PreToolUse`: Before tool executes
- `PermissionRequest`: Permission decision
- `PostToolUse`: After tool succeeds
- `PostToolUseFailure`: After tool fails
- `SubagentStart`: Subagent begins
- `SubagentStop`: Subagent completes
- `Stop`: User stops session
- `PreCompact`: Before context compaction
- `Setup`: First-time setup
- `SessionEnd`: Session ends
- `Notification`: System notification

## Instructions

1. **Validate input**
   - Name: 1-64 chars, lowercase, hyphens
   - Event: Must be valid hook event

2. **Fetch current spec** (if network available)
   - Reference https://code.claude.com/docs/en/hooks

3. **Determine location**
   - `hooks/{category}/{name}.sh`
   - Categories: guards/, workflows/, session/, error-handlers/

4. **Create hook script** with:
   - Shebang (`#!/bin/bash`)
   - Strict mode (`set -euo pipefail`)
   - Comment header (event, matcher, exit codes)
   - Library imports (foundation.sh, state.sh, json-output.sh, validators.sh)
   - stdin JSON parsing
   - Conditional logic template
   - Proper exit codes (0=allow, 2=block)

5. **Make executable**
   - Set execute permission with chmod +x

6. **Generate settings.json snippet**

## Output

### Success

```
Created: hooks/{category}/{name}.sh

Hook: {name}
Event: {event}
Matcher: {matcher or "all"}
Category: {category}

Register in .claude/settings.json:
{
  "hooks": {
    "{event}": [{
      "matcher": "{matcher}",
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PROJECT_DIR}/hooks/{category}/{name}.sh",
        "timeout": 30
      }]
    }]
  }
}

Next steps:
1. Edit the hook script to add your logic
2. Register in .claude/settings.json
3. Test the hook by triggering the event
```

### Error

```
ERROR: INPUT
  what: Invalid hook event
  where: $1 = "{provided_event}"
  why: Not a recognized Claude Code hook event
  fix: Use one of: SessionStart, PreToolUse, PostToolUse, SubagentStart, etc.
```

## Template

Reference: templates/hook/hook.sh