Guide · Agent skill
How to use the Hook Development Guide agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The hook-development skill is a set of instructions and reference files that teaches Claude Code to design, configure and debug hooks for plugins. Hooks are small automated checks that run at specific moments in a session, such as before a tool runs, after an edit, or when the agent tries to stop. This guide shows you how to install the skill, ask for hook work in natural language, and what to check before you rely on the result.
Hook Development Guideanthropics/claude-plugins-official · Apache-2.0 Download the skill Quick start
- 1Download the ZIP. Download the hook-development skill ZIP from this page.
- 2Install the skill. Unzip it into ~/.claude/skills/ for personal use or .claude/skills/ for one project, or upload it under Settings → Capabilities → Skills in the Claude apps.
- 3Check the requirements. Confirm you have Claude Code with plugin hooks, a bash shell and jq installed.
- 4Ask for a hook in plain language. Describe the event, the tool and the outcome, such as blocking a dangerous shell command.
- 5Review the generated configuration. Check the matcher, event name and hook type, and make sure paths use ${CLAUDE_PLUGIN_ROOT}.
- 6Test the hook. Use the included scripts/test-hook.sh and scripts/hook-linter.sh to check the hook before relying on it.
What does the hook-development skill make the agent do?
Hooks are event-driven automation scripts that run in response to Claude Code events. The skill helps the agent write hook configuration, choose between prompt-based and command hooks, and wire up events such as PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact and Notification.
Once installed, the agent can also write example validation scripts and linting or schema checks for hook configuration. Its guidance covers the input hooks receive on stdin, the output they return, and the exit codes that decide whether processing is blocked.
- Validate tool calls before they run (PreToolUse)
- React to tool results (PostToolUse)
- Check completion before the agent stops (Stop, SubagentStop)
- Load project context at session start (SessionStart)
How do you install the hook-development skill?
Download the skill ZIP from this page. Then choose one of the two install routes below.
For a personal install, unzip the file into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder. In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.
- Personal: unzip into ~/.claude/skills/
- Project: unzip into .claude/skills/ inside your project
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
What does the skill need before it works?
The skill assumes Claude Code with plugin hook support, a bash shell, and jq. The example validation scripts use jq to parse the JSON that hooks receive. The skill's own scripts run locally and the skill does not use the network, but they do run, so review them before use.
- Claude Code (plugin hooks)
- bash shell
- jq, used by the example validation scripts
- Runs scripts: yes. Uses network: no.
How do you trigger the skill with a natural request?
Describe the hook you want in plain terms, and mention the event or the behaviour. The skill's description lists phrases that match it, such as "create a hook", "add a PreToolUse hook", "validate tool use", "block dangerous commands" or "set up event-driven automation".
Be specific about the tool, the event and the outcome you want. The more concrete the request, the more useful the hook.
- Add a PreToolUse hook that blocks risky file writes to /etc or .env files
- Create a Stop hook that checks tests ran before the agent finishes
- Set up a SessionStart hook that loads project context
What does a hook configuration look like?
Plugin hooks live in hooks/hooks.json and use a wrapper with a hooks field. Settings files in .claude/settings.json use the direct format, with events at the top level and no wrapper. The skill also recommends using ${CLAUDE_PLUGIN_ROOT} in command paths so they stay portable.
The example below is a PreToolUse hook that asks a prompt to check file writes.
- Plugin format: wrap events in a hooks field inside hooks/hooks.json
- Settings format: events sit directly at the top level of .claude/settings.json
- Use ${CLAUDE_PLUGIN_ROOT}/scripts/... for paths inside a plugin
{"PreToolUse":[{"matcher":"Write|Edit","hooks":[{"type":"prompt","prompt":"Validate file write safety. Check: system paths, credentials, path traversal, sensitive content. Return 'approve' or 'deny'."}]}]}What examples does the skill include?
The reference files include patterns for security validation, test enforcement and multi-stage checks. A common pattern runs a fast command hook first, then a prompt hook for deeper analysis on the same event.
The example scripts load project context at session start and validate Bash and Write operations. The skill also explains how to migrate from basic command hooks to prompt-based hooks.
- Security validation: block writes to system directories, credentials or paths containing '..'
- Test enforcement: review the transcript before the agent stops
- Multi-stage validation: quick command check, then prompt analysis
- Migration: moving from command hooks to prompt hooks
What are the safety limits?
Treat the example pattern checks as a starting point, not a security boundary. The skill's own warning is that the example pattern checks are simple string matches and can be bypassed, so they should not be the only control.
Also remember that the skill runs scripts. Read the scripts/ and examples/ folders before you enable a hook, and test hooks on a non-critical project first.
- Do not rely on string-match hooks as your only control over dangerous commands
- Review the scripts before running them
- Use the scripts/test-hook.sh and scripts/hook-linter.sh files to check your hooks
What people use it for
- Blocking writes to system paths or credential files with a PreToolUse prompt hook
- Checking that tests ran before the agent stops with a Stop hook
- Loading project context into a session with a SessionStart command hook
- Running a quick command check before a deeper prompt-based review of Bash calls
Frequently asked questions
How do I install the hook-development skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. In the Claude apps, you can upload the ZIP under Settings → Capabilities → Skills.
What do I need to run it?
You need Claude Code with plugin hook support, a bash shell and jq. The example validation scripts use jq to parse hook input. The skill runs scripts but does not use the network.
Is the hook-development skill free?
The source for this skill is licensed under Apache-2.0. Check the licence file in the download for the terms that apply to you.
What is the difference between a prompt hook and a command hook?
A prompt hook uses an LLM to judge the situation in natural language, which suits context-aware checks. A command hook runs a bash command for fast, deterministic checks such as file operations or external tool calls.
Can this skill block dangerous shell commands on its own?
Not reliably. The skill's example pattern checks are simple string matches that can be bypassed, so they should be one layer among others rather than your only protection.
Why is my hook not running?
Check that the hook is in the right file for its format: hooks/hooks.json needs the hooks wrapper, while .claude/settings.json does not. Confirm the event name is spelled exactly as listed and that command paths use ${CLAUDE_PLUGIN_ROOT}.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
This skill suits plugin developers and teams who already know JSON configuration and shell scripting and want help building safety checks, session context loading or completion checks. It is not an end-user productivity tool, and if you need security-critical enforcement, use it alongside stronger controls rather than as the only one.
Download the skill