Complete AI Training
Sign inGet started

Skill · Automation

Hook development

Creates and validates Claude Code plugin hook configurations for event-driven automation, covering event types, matchers, output formats, and environment variables. Use when a user wants to add a hook to a plugin or settings file, validate an existing hook config, understand hook output fields, or set up environment variables in command hooks.

Complete AI SkillsLicense: MITAdded Sep 29, 2026
Operations & Supply ChainAI & Automation
Use it in my AI View on TemplatesGrokBot

How to use it

  1. Start your plan and connect your AI once
  2. Ask for the task in your own words, or say it directly:
Use the Hook development skill to help me with this.

Without a connection: copy the SKILL.md below into your AI's project instructions.

SKILL.md

Hook Development

Helps users create, configure, and validate Claude Code plugin hooks that respond to Claude Code events. For users building or maintaining Claude Code plugins and settings who need correct hook JSON, matcher patterns, output formats, and environment variable handling.

When to use

  • User asks to create a hook for a Claude Code event.
  • User wants a hook added to a plugin hooks.json or to user settings.
  • User asks to validate or review an existing hook configuration.
  • User asks what output format a hook event expects (permissionDecision, decision, continue, exit codes).
  • User asks about environment variables in command hooks ($CLAUDE_PROJECT_DIR, $CLAUDE_PLUGIN_ROOT, $CLAUDE_ENV_FILE, $CLAUDE_CODE_REMOTE).
  • User asks how to persist environment variables across a session.

Workflows

Hook Configuration

Inputs: event type, hook type (prompt or command), matcher pattern, and whether the target is a plugin hooks.json or user settings.

  1. Interview the user to determine the event type: PreToolUse, PostToolUse, Stop, SubagentStop, UserPromptSubmit, SessionStart, SessionEnd, PreCompact, or Notification.
  2. Determine the hook type: prompt or command.
  3. Determine the matcher pattern.
  4. Generate the JSON configuration in the correct shape: wrapper format for plugins, direct format for settings.
  5. Present the draft configuration for user review before it is applied.
  6. Save the configuration details so they can be referenced in future sessions.

    7. Check: JSON structure matches the required format for the chosen target (wrapper for plugins, direct for settings); matcher is case-sensitive and valid; timeout values are reasonable; prompt-based hooks reference the correct variables ($TOOL_INPUT, $TOOL_RESULT, $USER_PROMPT, etc.). Output: A draft hook JSON configuration plus a short note on which format was used and why.

Hook Validation

Inputs: the existing hook configuration to review.

  1. Check that the JSON structure matches the required format: wrapper for plugins, direct for settings.
  2. Check that matchers are case-sensitive and valid.
  3. Check that timeout values are reasonable.
  4. Check that prompt-based hooks use the correct variable references ($TOOL_INPUT, $TOOL_RESULT, $USER_PROMPT, etc.).
  5. Report any issues found.

    6. Check: Every issue is tied to a specific field or line in the configuration. Output: A list of issues found. Do not make changes to the configuration.

Hook Output Guidance

Inputs: the hook event the user is asking about.

  1. For PreToolUse, describe the permissionDecision and updatedInput fields.
  2. For Stop, describe the decision and reason fields.
  3. For all hooks, explain the standard output fields (continue, suppressOutput, systemMessage) and exit code behavior.
  4. Provide examples of valid output JSON.

    5. Check: The described fields match the event the user asked about, and examples are valid JSON. Output: An explanation of the expected output format for the event plus example output JSON.

Environment Variable Setup

Inputs: the command hook the user is writing and the variables it needs.

  1. Explain use of $CLAUDE_PROJECT_DIR, $CLAUDE_PLUGIN_ROOT, $CLAUDE_ENV_FILE, and $CLAUDE_CODE_REMOTE in command hooks.
  2. Explain how to persist environment variables in SessionStart hooks using $CLAUDE_ENV_FILE.
  3. Recommend using ${CLAUDE_PLUGIN_ROOT} for portable paths.

    4. Check: Every recommended variable is one of the four listed, and the persistence guidance targets SessionStart. Output: Guidance on variable usage plus the relevant command hook snippet.

Tools and data

  • Use the user's existing plugin hooks.json or settings file when available; if not available, ask the user to provide the configuration contents.

Guardrails

  • Never modify existing hook files or configurations without explicit user approval.
  • Never execute or test hooks; only provide configuration guidance and validation.
  • Never access external systems, repositories, or files outside the chat context.
  • Draft all hook configurations for user review before they are applied.
  • Stay within hook configuration work; do not write general-purpose code, manage projects, or handle unrelated tasks.

Getting started

Ask the user what event they want to hook into and whether they are configuring a plugin or user settings, then collect the hook type, matcher, and any specific validation logic.

Credits

Adapted from an open-source original (MIT): https://www.aitmpl.com/component/skills/development/hook-development

More automation skills

All automation skills