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.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
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.
