Hook Creator

SKILL: Hook Creator

---

LIBRARY-FIRST PROTOCOL (MANDATORY)

Before writing ANY code, you MUST check:

Step 1: Library Catalog

• Location: .claude/library/catalog.json
• If match >70%: REUSE or ADAPT

Step 2: Patterns Guide

• Location: .claude/docs/inventories/LIBRARY-PATTERNS-GUIDE.md
• If pattern exists: FOLLOW documented approach

Step 3: Existing Projects

• Location: D:\Projects\*
• If found: EXTRACT and adapt

Decision Matrix

| Match | Action | |-------|--------| | Library >90% | REUSE directly | | Library 70-90% | ADAPT minimally | | Pattern exists | FOLLOW pattern | | In project | EXTRACT | | No match | BUILD (add to library after) |

---

Purpose

Create production-ready Claude Code hooks that integrate with our RBAC security system, follow official schemas, and meet performance requirements (/dev/null || echo "default")

BAD - crashes if key missing or json invalid

VALUE=$(echo "$JSON" | jq -r '.key')

### 4. Ensure Directories Exist

Create directories before writing:
```bash
STATE_DIR="${HOME}/.claude/my-hook"
mkdir -p "$STATE_DIR" 2>/dev/null

5. Use Environment Variables for Paths

Never hardcode project paths:

# GOOD - configurable via environment
PROJECT_PATH="${MY_PROJECT_PATH:-/default/path}"

# BAD - hardcoded, breaks on other systems
PROJECT_PATH="/c/Users/john/projects/myapp"

ANTI-PATTERNS TO AVOID

These patterns caused real bugs in production hooks. NEVER use them:

ANTI-PATTERN 1: Using grep -P (Perl Regex)

Problem: grep -P requires Perl regex support, not available on all systems.

# BAD - grep -P not portable
FOUND=$(echo "$TEXT" | grep -oP '(?).*?(?=)')

# GOOD - use bash regex matching
if [[ "$TEXT" =~ \([^\ ]]; then
    FOUND="${BASH_REMATCH[1]}"
fi

ANTI-PATTERN 2: Using sed -i Directly

Problem: sed -i behaves differently on macOS (requires ''), Linux, and Windows Git Bash.

# BAD - not portable
sed -i 's/old/new/' "$FILE"

# ALSO BAD - OS detection is fragile
if [[ "$(uname -s)" == "Darwin" ]]; then
    sed -i '' 's/old/new/' "$FILE"
else
    sed -i 's/old/new/' "$FILE"
fi

# GOOD - portable temp file approach
sed_inplace() {
    local pattern="$1"
    local file="$2"
    local temp_file="${file}.tmp.$$"
    sed "$pattern" "$file" > "$temp_file" && mv "$temp_file" "$file"
}
sed_inplace 's/old/new/' "$FILE"

ANTI-PATTERN 3: Hardcoded Paths

Problem: Hardcoded paths break on other systems or when projects move.

# BAD - hardcoded
cd D:/Projects/connascence
python analyze.py

# GOOD - environment variable with fallback
CONNASCENCE_PATH="${CONNASCENCE_PROJECT_PATH:-D:/Projects/connascence}"
if [[ -d "$CONNASCENCE_PATH" ]]; then
    cd "$CONNASCENCE_PATH"
    python analyze.py
else
    echo "ERROR: Connascence project not found at $CONNASCENCE_PATH" >&2
    exit 1
fi

ANTI-PATTERN 4: Missing Directory Creation

Problem: Writing to directories that don't exist causes silent failures.

# BAD - assumes directory exists
echo "$DATA" > ~/.claude/my-hook/state.json

# GOOD - ensure directory exists first
STATE_DIR="${HOME}/.claude/my-hook"
mkdir -p "$STATE_DIR" 2>/dev/null
echo "$DATA" > "$STATE_DIR/state.json"

ANTI-PATTERN 5: Blocking cat Reads

Problem: Using cat without timeout can block indefinitely if stdin never closes.

# BAD - can block forever
INPUT=$(cat)

# GOOD - use timeout or check for input
INPUT=$(timeout 5 cat 2>/dev/null || echo "{}")

# OR check if stdin has data
if [[ -t 0 ]]; then
    # No stdin data, use default
    INPUT="{}"
else
    INPUT=$(cat)
fi

ANTI-PATTERN 6: Silent Failures

Problem: Errors are silently swallowed, making debugging impossible.

# BAD - silent failure
jq '.key' "$FILE" 2>/dev/null

# GOOD - log errors to stderr, handle gracefully
if ! VALUE=$(jq -r '.key' "$FILE" 2>&1); then
    echo "[HOOK ERROR] Failed to parse $FILE: $VALUE" >&2
    VALUE="default"
fi

Hook Validation Checklist

Before deploying a hook, verify:

• [ ] Uses set -euo pipefail (or equivalent error handling)
• [ ] All variables are properly quoted
• [ ] No grep -P usage (use bash regex or grep -E)
• [ ] No direct sed -i (use temp file approach)
• [ ] No hardcoded paths (use environment variables)
• [ ] Directories created before use
• [ ] jq errors handled gracefully
• [ ] Timeout on stdin reads if applicable
• [ ] Errors logged to stderr
• [ ] Tested on target platform (Windows Git Bash/macOS/Linux)

Performance Monitoring

Add performance logging to all hooks:

const start = process.hrtime.bigint();
// ... hook logic ...
const durationMs = Number(process.hrtime.bigint() - start) / 1_000_000;
console.error(`[PERF] ${hookName} completed in ${durationMs.toFixed(2)}ms`);

Related Skills

• hooks-automation - General hook automation patterns
• cicd-intelligent-recovery - Error recovery patterns
• cascade-orchestrator - Multi-hook coordination

---

Last Updated: 2025-12-30 Integrated with: Claude Code Hooks v1.0.0

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: DNYoussef
• Source: DNYoussef/context-cascade
• License: MIT

Install and usage instructions live in the source repository linked above.