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.
“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.”
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.
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.
- 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
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 ↗Checked
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
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]
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]
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]
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]
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]
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 ↗Checked
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 ↗Checked
https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/plugins/plugin-dev/LICENSE
Supports: license, limitations[5]
https://raw.githubusercontent.com/anthropics/claude-plugins-official/41f32e407b450055044f167db7ded5e8ff67d203/.claude-plugin/marketplace.json
Supports: limitations[6], install.steps[0]