---
title: "Hook Development for Claude Code Plugins: review, setup & limitations · Undominated.ai"
canonical: https://undominated.ai/skills/anthropic-hook-development/
description: "Explains how to write Claude Code plugin hooks, prompt-based and command-based, with their event list, input and output JSON and exit codes, and ships Bash utilities to validate, lint and test them."
---

# Hook Development for Claude Code Plugins: review, setup & limitations · Undominated.ai

> Explains how to write Claude Code plugin hooks, prompt-based and command-based, with their event list, input and output JSON and exit codes, and ships Bash utilities to validate, lint and test them.

[← Explore all skills](/skills/)

AGENT DEVELOPMENT / Anthropic

# Hook Development for Claude Code Plugins

Explains how to write Claude Code plugin hooks, prompt-based and command-based, with their event list, input and output JSON and exit codes, and ships Bash utilities to validate, lint and test them.

 [See setup guidance ↓](#setup)[Original source ↗](https://github.com/anthropics/claude-plugins-official/tree/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/skills/hook-development)

SOURCE REVIEW

 Reviewed 2026-10-22
 Evidence 10 linked sources
 Publisher Anthropic
 Licence [Apache-2.0 ↗](https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/LICENSE)
 Revision 41f32e407b45
 [Read what was—and wasn’t—checked ↓](#review)

“This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.”

 [Anthropic · upstream description ↗](https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/skills/hook-development/SKILL.md) Our analysis follows below.

01 / THE REASONING

## Why this made the selection.

 - It separates prompt hooks, which it recommends and lists for Stop, SubagentStop, UserPromptSubmit and PreToolUse, from command hooks for deterministic checks, and gives the hook input JSON, output JSON and exit codes (0 success, 2 blocking error fed back to Claude).
- It ships three Bash utilities, validate-hook-schema.sh, test-hook.sh and hook-linter.sh, and three example hooks: validate-write.sh, validate-bash.sh and load-context.sh.

### A good fit for

 - Write a PreToolUse hook that denies, or asks before, a Write or Edit to sensitive paths
- Choose between a prompt hook and a command hook for a Stop or SubagentStop completeness check
- Run a hook script against a sample JSON input with test-hook.sh before enabling it

### Weigh up before choosing

 - Last commit touching plugins/plugin-dev/skills/hook-development at revision 41f32e40: 2026-02-05 (2438937b).
- The SKILL.md says a plugin's hooks/hooks.json wraps its events in a top-level hooks object, but its later "Plugin Hook Configuration" example for the same file puts the events at the top level.
- validate-hook-schema.sh runs its event checks over the file's top-level keys (jq -r 'keys[]'). In the wrapper format the SKILL.md prescribes for plugins, those keys are description and hooks, not event names.
- Hooks load when a Claude Code session starts; the SKILL.md says changes to hooks.json or hook scripts take a restart.
- validate-hook-schema.sh, test-hook.sh and the validate-write.sh and validate-bash.sh examples call jq; hook-linter.sh only searches a script for the string jq.
- hook-development ships in plugin-dev, whose README puts "MIT License - See repository for details" under its License heading, while the plugin's LICENSE file is the Apache License, Version 2.0. This record follows the LICENSE file.
- The plugin-dev install line that would bring in hook-development names a claude-code-marketplace; the repository's marketplace file is named claude-plugins-official.

02 / THE REVIEW RECORD

## What we actually inspected.

Source review has boundaries. A clear record is more useful than a “safe” badge.

### Material inspected

 - plugins/plugin-dev/skills/hook-development/SKILL.md
- plugins/plugin-dev/skills/hook-development/scripts/validate-hook-schema.sh
- plugins/plugin-dev/skills/hook-development/scripts/test-hook.sh
- plugins/plugin-dev/skills/hook-development/scripts/hook-linter.sh (usage block)
- plugins/plugin-dev/skills/hook-development/examples/validate-write.sh
- plugins/plugin-dev/skills/hook-development/examples/validate-bash.sh
- plugins/plugin-dev/skills/hook-development/examples/load-context.sh
- plugins/plugin-dev/README.md
- plugins/plugin-dev/LICENSE
- .claude-plugin/marketplace.json (name and plugin-dev entry)

### Our findings

 - The SKILL.md frontmatter declares no allowed-tools.
- Default timeouts in the SKILL.md: 60 seconds for command hooks and 30 seconds for prompt hooks; all matching hooks run in parallel and do not see each other's output.
- test-hook.sh pipes the sample input into the hook script under timeout, after setting CLAUDE_PROJECT_DIR to /tmp/test-project and CLAUDE_ENV_FILE to /tmp/test-env-<pid> unless they are already set; if the environment file exists afterwards, it prints and deletes it.
- load-context.sh appends export lines such as PROJECT_TYPE to $CLAUDE_ENV_FILE, the SessionStart mechanism the SKILL.md describes for persisting environment variables.

### Not established by this review

 - None of the three utilities or three example hooks was run.
- references/patterns.md, references/migration.md, references/advanced.md and scripts/README.md were not opened.
- Not executed: it was not installed or run.

The review applies to the material and revision named here. A newer upstream release can change its behavior.

03 / PUT IT TO WORK

## Add a skill to your workflow.

[Upstream setup instructions ↗](https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/README.md)
 - The plugin-dev README prints `/plugin install plugin-dev@claude-code-marketplace`, which names claude-code-marketplace rather than this repository's marketplace, claude-plugins-official, and installs the full plugin-dev plugin rather than hook-development by itself, so install.command is null.
- The README also prints `cc --plugin-dir /path/to/plugin-dev` for loading the plugin from a local directory during development.
- Neither line was run for this review.

### Before you start

 - Claude Code (hooks attach to Claude Code events)
- Bash for the scripts and examples; jq for validate-hook-schema.sh, test-hook.sh, validate-write.sh and validate-bash.sh

### Compatibility

Claude Code

### Guidance plus Bash utilities that read hook files and execute a hook script under test

 - No allowed-tools in the SKILL.md frontmatter
- validate-hook-schema.sh and hook-linter.sh read the files named on their command lines and print results
- test-hook.sh executes the hook script passed to it, with a 60-second default timeout; afterwards it deletes whatever file exists at the CLAUDE_ENV_FILE path, a path the caller may already have set or, by default, /tmp/test-env-<pid>, whoever created that file
- Hooks built from it run on Claude Code events under the user's permissions; command hooks run shell scripts and prompt hooks ask the model for a decision

### Cost model

Apache-2.0 per plugins/plugin-dev/LICENSE; prompt hooks add model calls on each matching event

04 / FOLLOW THE EVIDENCE

## The source trail.

Our notes are separate from the original resource. Check upstream before adopting a new version.

 - [hook-development SKILL.md ↗](https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/skills/hook-development/SKILL.md) Checked 2026-10-21 https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/skills/hook-development/SKILL.md Supports: upstreamDescription, summary, whySelected[0], whySelected[1], bestFor[0], bestFor[1], limitations[1], limitations[3], compatibility, review.findings[0], review.findings[1], review.findings[3], access.permissions[0], access.permissions[3], access.cost
- [hook-development scripts/validate-hook-schema.sh ↗](https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/skills/hook-development/scripts/validate-hook-schema.sh) Checked 2026-10-21 https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/skills/hook-development/scripts/validate-hook-schema.sh Supports: limitations[2], limitations[4], access.permissions[1], install.prerequisites[1]
- [hook-development scripts/test-hook.sh ↗](https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/skills/hook-development/scripts/test-hook.sh) Checked 2026-10-21 https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/skills/hook-development/scripts/test-hook.sh Supports: bestFor[2], limitations[4], review.findings[2], access.permissions[2]
- [hook-development scripts/hook-linter.sh ↗](https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/skills/hook-development/scripts/hook-linter.sh) Checked 2026-10-21 https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/skills/hook-development/scripts/hook-linter.sh Supports: whySelected[1], access.permissions[1], limitations[4]
- [hook-development examples/load-context.sh ↗](https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/skills/hook-development/examples/load-context.sh) Checked 2026-10-21 https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/skills/hook-development/examples/load-context.sh Supports: review.findings[3], access.permissions[3]
- [hook-development examples/validate-write.sh ↗](https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/skills/hook-development/examples/validate-write.sh) Checked 2026-10-22 https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/skills/hook-development/examples/validate-write.sh Supports: limitations[4], install.prerequisites[1], bestFor[0]
- [hook-development examples/validate-bash.sh ↗](https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/skills/hook-development/examples/validate-bash.sh) Checked 2026-10-22 https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/skills/hook-development/examples/validate-bash.sh Supports: limitations[4], install.prerequisites[1]
- [plugin-dev README ↗](https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/README.md) Checked 2026-10-21 https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/README.md Supports: install.sourceUrl, install.steps[0], install.steps[1], install.prerequisites[0], limitations[5], limitations[6], compatibility, whySelected[1]
- [plugin-dev LICENSE ↗](https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/LICENSE) Checked 2026-10-21 https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/LICENSE Supports: license, limitations[5]
- [Marketplace file, name and plugin-dev entry ↗](https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/.claude-plugin/marketplace.json) Checked 2026-10-21 https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/.claude-plugin/marketplace.json Supports: limitations[6], install.steps[0]

KEEP COMPARING

## Other approaches to consider.

Related by category or shared topics. These are alternatives to inspect, not a measured quality order.

 [### Plugin Settings Pattern for Claude Code Plugins ↗ Documents one pattern for per-project Claude Code plugin settings, a .claude/<plugin-name>.local.md file with YAML frontmatter and a Markdown body, and how hooks, commands and agents read it.](/skills/anthropic-plugin-settings/)[### Agent Development for Claude Code Plugins ↗ Explains how to write a Claude Code plugin agent file (frontmatter, trigger description, system prompt) and ships a Bash script that checks one agent file.](/skills/anthropic-agent-development/)[### Command Development for Claude Code ↗ Explains how to write Claude Code slash-command files: frontmatter fields, $ARGUMENTS and positional arguments, @file references, inline Bash and plugin command patterns.](/skills/anthropic-command-development/)

 [AI Tools ↗](/tools/)[Skills ↗](/skills/)[Agents ↗](/agents/)[MCP Servers ↗](/mcp-servers/)[Workflows ↗](/workflows/)

## Continue your investigation

 - [Choose a toolkit](/tools/)
- [Inspect execution hosts](/agents/)
- [Check tool access](/mcp-servers/)
- [Check project dependencies](/check-repo/)
