Creates and registers hooks for the Claude Code framework. Handles pre/post tool execution, validation, memory, and session hooks. Use when new validation, safety, or automation hooks are needed.
Creates and registers hooks for the Claude Code framework. Handles pre/post tool execution, validation, memory, and session hooks. Use when new validation, safety, or automation hooks are needed.
version
2.3.0
model
sonnet
invoked_by
both
user_invocable
true
tools
["Read","Write","Edit","Bash","Glob","Grep"]
dependencies
["research-synthesis"]
best_practices
["Always register hooks in appropriate config","Test hooks before deployment","Include error handling in all hooks","Document hook triggers and behavior","Use explicit enforcement modes (block|warn|off) with env overrides; default warn unless spec requires block"]
error_handling
graceful
streaming
supported
output_location
.claude/hooks/
verified
true
lastVerifiedAt
2026-02-28
source
builtin
trust_score
100
provenance_sha
27744e5a4bd0cae1
Hook Creator Skill
Creates, validates, and registers hooks for the multi-agent orchestration framework.
ROUTER UPDATE REQUIRED (CRITICAL - DO NOT SKIP)
After creating ANY hook, you MUST update documentation:
1. Add to .claude/hooks/README.md under appropriate category
2. Register in config.yaml or settings.json if required
3. Update learnings.md with hook summary
Verification:
grep "<hook-name>" .claude/hooks/README.md || echo"ERROR: hooks/README.md NOT UPDATED!"
WHY: Hooks not documented are invisible and unmaintainable.
Overview
This skill creates hooks for the Claude Code framework:
Pre-tool execution - Safety validation before commands run
After creating a hook, update .claude/hooks/README.md:
#### {Hook Name} (`hook-name.cjs`)
{Description of what the hook does}
**When it runs:** {Trigger condition}
**What it checks/does:** {Detailed behavior}
Verify with:
grep "hook-name" .claude/hooks/README.md || echo"ERROR: Not documented!"
Step 7: System Impact Analysis (MANDATORY)
This analysis is MANDATORY. Hook creation is INCOMPLETE without it.
After creating a hook:
Settings Registration (BLOCKING)
Add to .claude/settings.json PreToolUse/PostToolUse/etc.
This step is CRITICAL. After creating the hook artifact, you MUST register it in the hook discovery system.
Phase 1 Context: Phase 1 is responsible for tool and hook validation/discovery. Hooks created without registration are invisible to the system and will not be loaded at startup.
After hook file is written and tested:
Create/Update Hook Registry Entry in appropriate location:
If registry doesn't exist, create .claude/context/artifacts/hook-registry.json:
{"hooks":[{"name":"{hook-name}","id":"{hook-name}","description":"{Brief description from hook}","category":"{safety|routing|memory|session|validation|audit}","type":"{pre-tool|post-tool|user-prompt|session-start|session-end}","version":"1.0.0","targetTools":["{Tool1}","{Tool2}"],"enforcementMode":"{block|warn|off}","defaultEnabled":true,"filePath":".claude/hooks/{category}/{hook-name}.cjs","testFilePath":".claude/hooks/{category}/{hook-name}.test.cjs","environmentVariable":"{HOOK_NAME}_MODE"}]}
Validate Hook Against Schema:
Ensure hook validates against .claude/schemas/hook-schema.json (if exists):
# Validate hook structure
node -e "
const hook = require('./.claude/hooks/{category}/{hook-name}.cjs');
if (hook.validate) console.log('✓ Has validate() export');
if (hook.PROJECT_ROOT) console.log('✓ Has PROJECT_ROOT');
if (hook.findProjectRoot) console.log('✓ Has findProjectRoot()');
"
Register Hook in Loader:
Update .claude/lib/hooks/hook-loader.cjs (if exists) to include new hook:
#### {Hook Name} (`{hook-name}.cjs`)
{Detailed description of what the hook does.}
**When it runs:** {Trigger condition - e.g., "Before every Bash command", "After task completion"}
**What it checks/does:**- {Check/action 1}
- {Check/action 2}
- {Check/action 3}
**Enforcement mode:**`process.env.{HOOK_NAME}_MODE` (default: `warn`)
**Test file:**`.claude/hooks/{category}/{hook-name}.test.cjs`**Related hooks:** {List any hooks that interact with this one}
Update Memory:
Append to .claude/context/memory/learnings.md:
## Hook: {hook-name}-**Type:** {pre-tool|post-tool|event}
-**Category:** {safety|routing|memory|session|validation}
-**Purpose:** {Detailed purpose}
-**Trigger:** {When it runs}
-**Enforcement:** {Block/warn/off by default}
-**Integration Notes:** {Any special considerations}
Why this matters: Without hook registration:
Hooks are not loaded at startup
Hook validation doesn't occur
System cannot discover available hooks
Safety validators are bypassed
"Invisible artifact" pattern emerges
Phase 1 Integration: Hook registry is the discovery mechanism for Phase 1, enabling the system to validate hooks against schema, load them at startup, and enforce safety rules consistently.
Step 9: Integration Verification (BLOCKING - DO NOT SKIP)
This step verifies the artifact is properly integrated into the ecosystem.
Before calling TaskUpdate({ status: "completed" }), you MUST run the Post-Creation Validation workflow:
This step is BLOCKING. Do NOT mark task complete until validation passes.
Why this matters: The Party Mode incident showed that fully-implemented artifacts can be invisible to the Router if integration steps are missed. This validation ensures no "invisible artifact" pattern.
This skill is part of the Creator Ecosystem. After creating a hook, consider if companion artifacts are needed:
Gap Discovered
Required Artifact
Creator to Invoke
When
Domain knowledge needs a reusable skill
skill
Skill({ skill: 'skill-creator' })
Gap is a full skill domain
Existing skill has incomplete coverage
skill update
Skill({ skill: 'skill-updater' })
Close skill exists but incomplete
Capability needs a dedicated agent
agent
Skill({ skill: 'agent-creator' })
Agent to own the capability
Existing agent needs capability update
agent update
Skill({ skill: 'agent-updater' })
Close agent exists but incomplete
Domain needs code/project scaffolding
template
Skill({ skill: 'template-creator' })
Reusable code patterns needed
Behavior needs pre/post execution guards
hook
Skill({ skill: 'hook-creator' })
Enforcement behavior required
Process needs multi-phase orchestration
workflow
Skill({ skill: 'workflow-creator' })
Multi-step coordination needed
Artifact needs structured I/O validation
schema
Skill({ skill: 'schema-creator' })
JSON schema for artifact I/O
User interaction needs a slash command
command
Skill({ skill: 'command-creator' })
User-facing shortcut needed
Repeated logic needs a reusable CLI tool
tool
Skill({ skill: 'tool-creator' })
CLI utility needed
Narrow/single-artifact capability only
inline
Document within this artifact only
Too specific to generalize
Integration Workflow
After creating a hook that needs additional capabilities:
// 1. Hook created but needs dedicated skillSkill({ skill: 'skill-creator' });
// Create skill that encapsulates hook logic// 2. Hook needs to be assigned to agent// Update agent's workflow to include hook awareness// 3. Hook needs workflow for testing// Create workflow in .claude/workflows/<hook-name>-test-workflow.md
Post-Creation Checklist for Ecosystem Integration
After hook is fully created and validated:
[ ] Does hook need a skill wrapper? -> Use skill-creator
[ ] Does hook need dedicated agent? -> Use agent-creator
[ ] Does hook need testing workflow? -> Create workflow
[ ] Should hook be enabled by default? -> Update config.yaml
[ ] Does hook interact with other hooks? -> Document in README.md
[ ] Run post-creation validation -> node .claude/tools/cli/validate-integration.cjs .claude/hooks/<category>/<hook-name>.cjs
Iron Laws of Hook Creation
These rules are INVIOLABLE. Breaking them causes silent failures.
1. NO HOOK WITHOUT validate() EXPORT
- Every hook MUST export validate() function
- Hooks without validate() cannot be called programmatically
2. NO HOOK WITHOUT main() FOR CLI
- Every hook MUST have main() for CLI execution
- Run only when require.main === module
3. NO HOOK WITHOUT ENFORCEMENT CONTROLS
- Support 'block|warn|off' via environment variable
- Default to 'warn' unless explicitly required to block
- Never crash on malformed input
4. NO HOOK WITHOUT ERROR HANDLING
- Wrap JSON.parse in try/catch
- Handle missing parameters gracefully
- Return valid: true when unsure (fail open, not closed)
5. NO HOOK WITHOUT TEST FILE
- Every hook needs <hook-name>.test.cjs
- Test valid, invalid, and edge cases
6. NO HOOK WITHOUT DOCUMENTATION
- Add to .claude/hooks/README.md
- Document trigger, behavior, exit codes
7. CROSS-PLATFORM PATHS
- Use path.join() not string concatenation
- Handle both / and \ path separators
- Use path.normalize() for comparison
8. NO CREATION WITHOUT SYSTEM IMPACT ANALYSIS
- Check if hook requires settings.json registration
- Check if hook requires config.yaml registration
- Update @HOOK_AGENT_MAP.md with new hook row (MANDATORY)
- Update affected agents' Enforcement Hooks sections (MANDATORY)
- Check if related hooks need updating
- Document all system changes made
9. IRON LAW I: PRE-TOOL HOOKS MUST VALIDATE AGAINST JSON SCHEMA
- PreToolUse hooks MUST compile and validate input against the companion
schemas/input.schema.json using AJV or equivalent before allowing execution
- Pattern: compile(schema) → validate(input) → exit 2 on schema failure
- Never block (exit 2) on schema-load errors — fail open, not closed
- Search: site:github.com "preToolUse" "ajv" "validate" filetype:cjs
10. IRON LAW III: POST-TOOL HOOKS MUST EMIT OBSERVABILITY EVENTS
- PostToolUse hooks MUST append a structured JSON line to
.claude/context/runtime/tool-events.jsonl via the centralized emitter:
const { sendEvent } = require('.claude/tools/observability/send-event.cjs')
- Required fields: tool_name, agent_id, session_id, outcome, timestamp
- Never crash on emit failure (try/catch, fail open)
- Inspect events: node .claude/tools/observability/send-event.cjs --tail 20
Integration Points
Ecosystem Assessor: Hook creator integrates with ecosystem assessment for reverse lookups
Agent Creator: Agents can reference hooks in their frontmatter
Skill Creator: Skills can define hooks in their hooks/ directory
Settings.json: Hooks are auto-registered with proper triggers and matchers
Config.yaml: Event hooks registered for UserPromptSubmit, SessionStart, etc.
Search arXiv for academic research (mandatory for AI/ML, agents, evaluation, orchestration, memory/RAG, security):
Via Exa: mcp__Exa__web_search_exa({ query: 'site:arxiv.org <topic> 2024 2025' })
Direct API: WebFetch({ url: 'https://arxiv.org/search/?query=<topic>&searchtype=all&start=0' })
Record decisions, constraints, and non-goals in artifact references/docs.
Keep updates minimal and avoid overengineering.
arXiv is mandatory (not fallback) when topic involves: AI agents, LLM evaluation, orchestration, memory/RAG, security, static analysis, or any emerging methodology.
Regression-Safe Delivery
Follow strict RED -> GREEN -> REFACTOR for behavior changes.
Run targeted tests for changed modules.
Run lint/format on changed files.
Keep commits scoped by concern (logic/docs/generated artifacts).
Optional: Evaluation Quality Gate
Run the shared evaluation framework to verify hook quality:
Exit codes correct: Hook exits 0 (allow) or 2 (block) only; exit 1 is never used (treated as error, not block per SE-03)
100ms performance budget: Hook body completes in under 100ms; no network calls, no blocking I/O, no long computation in the hot path
Fail-open vs fail-closed policy: Security hooks (routing, creator, write) are fail-closed (process.exit(2) on errors); advisory and PostToolUse hooks are fail-open (process.exit(0) on errors)
Graceful error handling: Hook body is wrapped in try/catch; unexpected errors exit 0 (non-critical) or 2 (security-critical) — never crash without an exit code
Registration complete: Hook is registered in .claude/settings.json and documented in @ENFORCEMENT_HOOKS.md
See .claude/skills/skill-creator/EVAL_WORKFLOW.md for full evaluation protocol and grader/analyzer agent usage.
