Hook Development
Official Anthropic skill for event-driven Claude Code hooks, validation, and safer plugin workflows.
- Skill Road
- Hook Development
Categories
Hook Development is an official Anthropic skill for developing hooks in Claude Code plugins. Its primary source is the official repository at https://github.com/anthropics/claude-code/tree/main/plugins/plugin-dev/skills/hook-development. According to the provider, hooks respond to events such as tool calls, session start, session end, user prompts, context compaction, and an agent stopping. This entry describes a technical development guide rather than a finished security product, an autonomous service, or a guarantee of error-free decisions.
Purpose and architecture
The skill presents hooks as automation that runs before or after an event. PreToolUse can inspect a tool call, deny it, or return updated input. PostToolUse can analyze results and provide feedback. Stop and SubagentStop support completeness checks, while SessionStart can load project context. SessionEnd, PreCompact, UserPromptSubmit, and Notification cover other lifecycle events. This separation helps teams place a control at the right point instead of moving every rule into one oversized script.
Prompt and command hooks
According to the provider, prompt hooks suit context-dependent decisions. They can evaluate a tool call or task using natural-language reasoning and return a structured decision. Command hooks suit deterministic checks, filesystem work, and external tools. The choice should consider traceability, runtime, failure modes, and permissions. A flexible model decision is not automatically reproducible, and a deterministic script is not automatically safe. In both cases, the team must review inputs, outputs, timeouts, and error paths.
Configuration and event data
The source distinguishes plugin configuration in hooks/hooks.json from direct user settings. In a plugin, events are nested inside a hooks object, while settings place events directly at the top level. Matchers can select one tool, several tool names, or regular-expression patterns. Hooks receive JSON on standard input with fields such as session identifier, working directory, permission mode, and event name. Depending on the event, additional data includes tool name, tool input, tool result, user prompt, or stop reason. Before activation, test these inputs with harmless fixtures and against the Claude Code version that the team actually supports.
Security and E-E-A-T
This description is grounded in Anthropic’s official source and official Claude Code documentation for hooks. Provider claims are identified as according to the provider; responsibility for safe rollout remains with the operating team. Treat tool input, file paths, and external responses as untrusted data. Apply least privilege, quote shell variables, and explicitly reject path manipulation and sensitive files. Never store or log passwords, tokens, private keys, or other secrets. Before writes, network access, or changes to external state, verify target, scope, and authorization. A hook can block an action, but it does not replace code review, access control, or monitoring.
Operations, testing, and limits
According to the provider, hooks load when a Claude Code session starts. Configuration or script changes therefore require a restart before they take effect. The source describes debugging, validating structured JSON output, setting suitable timeouts, and accounting for parallel execution. Concurrent hooks must not depend on a particular order or on another hook’s output. Test allowed, denied, malformed, and incomplete input separately. Also verify that a hook returns the intended decision to Claude and that failures remain understandable. The skill provides patterns and guardrails, but it does not guarantee that a particular plugin is correct, complete, or suitable for every environment.
Installation instructions
This guide complements Anthropic’s official Hook Development source. It does not replace checking the installed Claude Code version, reviewing the plugin, or obtaining approval from the responsible team.
Choose the event and objective
First define the event and the concrete objective. PreToolUse fits a check before an action, while PostToolUse fits a controlled review afterward. Stop and SubagentStop support completeness checks, and SessionStart supports context loading. Do not choose the broadest event when a narrower rule is sufficient.
Select the hook type
Use prompt hooks when context and judgment matter. Use command hooks for reproducible checks with clear inputs. Limit timeouts, tools, and file access. Every decision should be returned in an understandable form so a blocked workflow can be investigated.
Step 1: Review the configuration
Distinguish the plugin file hooks/hooks.json from direct settings. Check that events are nested at the correct level and that matchers select exactly the intended tools. Treat JSON, file contents, and external responses as untrusted data. Do not activate a rule whose effects and fallback behavior have not been tested with harmless fixtures.
FAQ
What is Hook Development? It is an official Anthropic skill with guidance for event-driven hooks in Claude Code plugins, including prompt and command hooks.
Are prompt hooks automatically safer? No. They can make context-aware decisions but still require limits, review, and human approval.
When are changes loaded? Hooks load when a session starts. According to the provider, changes require a restart.
Can a hook solve every security issue? No. Hooks complement but do not replace access control, code review, testing, or monitoring.
- Provider
- Anthropic
- Last reviewed
- 09.09.2026
Repository and documentation
Categories
Compatible with
Related guides
Guides and background related to this entry.