Creates new hook configurations for Claude Code lifecycle events, grounded in the docs corpus. Covers all hook event types with JSON schema compliance. Use when creating a new hook from scratch.
Generates a new hook configuration for a Claude Code lifecycle event, with correct JSON schema, handler type, and exit code behavior grounded in the docs corpus.
Check if hooks already exist for the target event in:
.claude/settings.json.claude/settings.local.jsonhooks/hooks.jsonIf the exact same event + matcher combination already exists:
{event} with this matcher already exists."/agent-customizer:improve-hook to evaluate and optimize it instead.If no hook exists for this event+matcher combination: Proceed to Phase 1 below.
Delegate to the artifact-analyzer agent with this task:
Analyze the project to understand existing hook configurations. Focus on: hooks defined in
.claude/settings.json,.claude/settings.local.json, and pluginhooks/hooks.json; project hook scripts in.claude/hooks/; plugin hook scripts inscripts/; event types currently in use; handler types used (command/http/prompt/agent); and any gaps in lifecycle event coverage. Also read rootCLAUDE.md,README.md, and any service-level README files to understand non-standard build commands, tooling, or conventions that hook scripts should use.
The agent runs on Sonnet with read-only tools (Read, Grep, Glob, Bash) in an isolated context. Wait for it to complete and parse its structured output.
Before generating, read these reference documents:
${CLAUDE_SKILL_DIR}/references/hook-authoring-guide.md — when to use hooks, 4 handler types, exit code semantics, blocking vs non-blocking behavior${CLAUDE_SKILL_DIR}/references/hook-events-reference.md — all 22 valid events, matcher fields per event, full JSON schema${CLAUDE_SKILL_DIR}/references/prompt-engineering-strategies.md — hook-specific prompting (zero-shot only for hooks)Read ${CLAUDE_SKILL_DIR}/assets/templates/hook-config.md and fill its placeholders using:
Before choosing the handler, verify in hook-events-reference.md that the selected event supports it. If the selected event only supports command, do not generate http, prompt, or agent guidance for that hook. If the requested handler is unsupported, stop and ask the user to change the event or handler choice.
Choose the target location based on the requested scope:
.claude/settings.json — committed project hook.claude/settings.local.json — local-only hookhooks/hooks.json — plugin-bundled hookGenerate the complete hook configuration:
hooks key of the selected target filecommand type):
.claude/hooks/{name}.sh with executable permissionsscripts/{name}.sh with executable permissions and reference it with ${CLAUDE_PLUGIN_ROOT}/scripts/{name}.shImportant: The hook JSON must be merged into the selected target file, not replace it. Read the current target file first and produce the merged result.
Read ${CLAUDE_SKILL_DIR}/references/hook-validation-criteria.md and execute its Validation Loop Instructions against the generated hook configuration.
The loop evaluates all hard limits and quality checks, fixes any failures, and re-evaluates — maximum 3 iterations. Do not proceed to Phase 4 until ALL criteria pass.
.claude/hooks/{name}.sh or scripts/{name}.sh and set executable (chmod +x)