Add Hook Skill

Core Hook Components

Resource	Path
Shared Library	.claude/hooks/_shared/hook-lib.sh
Config	.claude/hooks/hooks-config.json
Settings	.claude/settings.json

Reference Files: Refer to and read fully with progressive disclosure

• Documentations (.claude/hooks/README.md)
• Response Patterns & Exit Codes
• Hook Types (command vs prompt)
• Matcher Patterns Reference
• Event Payloads & Casing
• hooks-config.json Patterns
• TDD Testing Workflow
• Test Template

---

PHASE 1: PLAN

Step 1: Clarify Requirements (If Needed)

Skip this step if the optimal path is clear from the user's request. Otherwise, ask clarifying questions:

Category	Question	Why Ask
Event Type	"Should this BLOCK the action or just OBSERVE/LOG it?"	PreToolUse blocks, PostToolUse observes
Event Type	"Should this happen BEFORE or AFTER the tool runs?"	Determines PreToolUse vs PostToolUse
Matcher	"Should this apply to ALL tools or specific ones?"	Prevents performance issues from broad matchers
Response	"If validation fails, should Claude RETRY with guidance or ABANDON the action?"	Exit 2 (retry) vs deny (abandon)
Response	"Should Claude see the result (costs tokens) or just the user?"	additionalContext vs systemMessage
Output	"Verbose logs, minimal notifications, or silent execution?"	Determines logging strategy
Modification	"Should this MODIFY the input or BLOCK the action?"	updatedInput vs permissionDecision
Performance	"Is this critical path (<50ms) or can it be slower?"	Determines timeout and optimization needs
Failure	"If this hook fails, should the action be BLOCKED or ALLOWED?"	Fail-secure vs fail-safe

Tip: Prioritize questions that impact architecture (event type, blocking behavior) over cosmetic ones (output verbosity).

Step 2: Analyze User Requirements to Create plan for a hook with best practices and valid hook types

1. Choose Hook Type:

Type	Use When	Timeout
command (default)	Block, format, log, validate	seconds (default 60)
prompt	Intelligent completion check	seconds (default 30)

⚠️ prompt type only works for Stop and SubagentStop events

• Read hook-types.md if you need more details

2. Determine Event Type (Keywords in user request): IMPORTANT: First read event-payloads.md & matcher-types.md (PreToolUse/PostToolUse/PermissionRequest only) to understand the event types and matcher patterns

• Determine the optimal event type and matcher for the hook based on the user request
• IMPORTANT ALWAYS choose the most specific event type and matcher to optimize token usage for CLAUDE without compromising on functionality
• Discover MCP Tools: mcp-cli tools | mcp-cli grep "keyword" | mcp-cli info server/tool

Quick Reference

Keywords	Event Type	Can Block	Can Modify
"before", "block", "prevent", "validate"	PreToolUse	✓ exit 2	✓ updatedInput
"after", "format", "log", "analyze result"	PostToolUse	-	✓ additionalContext
"tool failed", "handle error"	PostToolUseFailure	-	✓ feedback
"permission", "allow", "deny dialog"	PermissionRequest	✓ decision	✓ updatedInput
"prompt", "enhance prompt", "add context"	UserPromptSubmit	✓ exit 2	✓ additionalContext
"startup", "initialize", "env vars"	SessionStart	-	✓ stdout→Claude
"cleanup", "commit", "session end"	SessionEnd	-	-
"notification", "alert"	Notification	-	-
"stop", "check completion"	Stop	✓ exit 2	-
"subagent start", "task start"	SubagentStart	-	✓ stdout→subagent
"subagent stop", "task complete"	SubagentStop	✓ exit 2	-
"compact", "before compaction"	PreCompact	✓ exit 2	✓ stdout→instructions

Tool Type	Pattern Example
Single tool	"Bash", "Edit", "Write"
Multiple tools	"Edit|Write"
MCP tools	"mcp__supabase__.*"
All tools	"*"

3. Define Response Strategy:

• First read response-patterns.md - Exit codes, output JSON schemas
• IMPORTANT ALWAYS choose the most specific response strategy to optimize token usage for CLAUDE without compromising on functionality

Goal	Method
Block tool (retry with guidance)	exit 2 + stderr message
Block tool (permanently)	JSON permissionDecision: "deny"
Allow and modify input	JSON permissionDecision: "allow" + updatedInput
Add context to Claude	JSON additionalContext in hookSpecificOutput
Silent pass-through	exit 0 with no output

4. Determine User Output Strategy:

• First read output-to-user/README.md
• Consider hook function and event type to determine best output strategy

5. DOs and DON'Ts:

✅ DOs

DO	Why	Implementation
Read stdin once & cache	Stream consumed on read	input=$(cat)
Use Exit 0 for success	Only Exit 0 parses JSON	exit 0
Use Exit 2 for blocking	Blocks tool, stderr → Claude	echo "Reason" >&2; exit 2
Quote shell variables	Prevent injection	"$var"
Use jq for JSON	Safe parsing	jq -r '.field'
Validate JSON output	Invalid JSON fails silently	echo "$json" | jq empty
Check stop_hook_active	Prevent infinite loops	Stop hooks only
Use absolute paths	Relative paths fail	$CLAUDE_PROJECT_DIR
Keep PreToolUse fast	Delays execution	Target <100ms

❌ DON'Ts

DON'T	Why	Fix
Output JSON on Exit 2	Stdout ignored on error	Use stderr text only
Use "deny" for retry	Abandons tool completely	Use Exit 2 instead
Assume fields exist	Payloads vary	Check with jq -e
Use deprecated fields	decision/reason gone	Use permissionDecision
Parse JSON with grep	Fragile/Unsafe	Always use jq
Hardcode paths	Breaks envs	Use env vars
Trust user input	Security risk	Validate everything
Mix Exit codes & JSON	Exit 2 overrides JSON	Pick one strategy

🔧 Custom Framework Best Practices

DO	Why
Source hook-lib.sh	Shared library access
Use is_feature_enabled	Config toggle support
Use return_* functions	Standardized output
Use json_get wrapper	Safe jq abstraction
Log with log_*	Standardized logging

6. Verify & Ask (Gap Analysis): If details are ambiguous, ask the user (prioritize questions that impact architecture):

Ambiguity Category	Key Question	Why Ask
Event Type	"Should this BLOCK the action (PreToolUse) or just OBSERVE/LOG it (PostToolUse)?"	Critical for security/validation vs logging
Matcher Scope	"Should this apply to ALL tools, or only specific ones (e.g., just 'Write' or 'Bash')?"	Prevents performance issues from broad matchers
Response Strategy	"If validation fails, should Claude be blocked (Exit 2) or told to retry (JSON deny)?"	Determines exit code vs JSON strategy
Output Verbosity	"Do you want verbose logs, minimal notifications, or silent execution?"	Impacts user experience/noise
Performance	"Is this a critical path operation (must be <50ms) or background task?"	Determines timeout and async needs

Step 3: Present Plan for Approval

Show: hook purpose, event type, target tools, expected behavior.

Do NOT read reference docs yet - wait for RED phase to reveal what you actually need.

---

PHASE 2: TDD TEST

• Read tdd-testing-workflow.md

Step 4: RED - Baseline Test (Watch It Fail)

Goal: See what Claude does WITHOUT the hook. Document exact failures.

1. Create test scenario - Realistic task that triggers target behavior
2. Dispatch subagent - Hook DISABLED or not wired yet
3. Document failures verbatim:
   • What tool calls did Claude make?
   • What was wrong with the behavior?
   • What should have been different?

Step 5: GREEN - Implement and Verify

Now read the docs - targeted by what you observed in RED:

1. Read relevant reference docs:

• Response Patterns & Exit Codes
• Hook Types (command vs prompt)
• Matcher Patterns Reference
• Event Payloads & Casing
• hooks-config.json Patterns

2. Implement minimal hook at .claude/hooks/utils/{eventType}/{feature-name}.sh:

#!/usr/bin/env bash
# Hook: {feature-name} | Event: {EventType} | Matcher: {pattern}
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "${SCRIPT_DIR}/../../_shared/hook-lib.sh"

[[ "$(is_feature_enabled "{eventType}.{featureName}")" == "true" ]] || return_silent

payload="$(cat)"
tool_name="$(json_get "$payload" ".tool_name")"

# --- HOOK LOGIC ---

return_silent

3. Dispatch subagent WITH hook - Same scenario, hook enabled
4. Verify fix - Behavior should now be correct

Step 6: REFACTOR - Close Loopholes

1. Run edge case scenarios - Different inputs, combined with other tools
2. Capture new failures - Document and fix
3. Optimize performance - Target <50ms for simple hooks
4. Re-test until bulletproof

---

PHASE 3: FINALIZE

Step 7: Generate CI Test File

Copy reference/test-template.sh and customize.

bash .claude/hooks/utils/{eventType}/{feature-name}.test.sh

Step 8: Validate Implementation

bash .claude/hooks/tests/ensure-implementation.sh .claude/hooks/utils/{eventType}/{feature-name}.sh

Step 9: Wire and Document

1. Add to hooks-config.json - Feature registration + settings
2. Add to settings.json:

{
  "hooks": {
    "{EventType}": [{
      "matcher": "Write|Edit",
      "hooks": [{"type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/utils/{eventType}/{feature-name}.sh", "timeout": 5}]
    }]
  }
}

3. Update CHANGELOG.md
4. Run full suite: bash .claude/hooks/tests/run-tests.sh --all

---

Final Checklist

PLAN (Steps 1-3):

• Requirements clarified (if needed)
• User requirements analyzed
• Plan presented for approval

TDD TEST (Steps 4-6):

• RED - Baseline test WITHOUT hook, failures documented
• GREEN - Relevant docs read, hook implemented, behavior verified
• REFACTOR - Edge cases tested, loopholes closed

FINALIZE (Steps 7-9):

• CI test file exists and passes
• Implementation validated
• hooks-config.json + settings.json wired
• run-tests.sh --all passes