Skill spotlight: hook-development — event-driven Claude Code automation

TL;DR. The hook-development skill from anthropics/claude-plugins-official is the official reference for building event-driven hooks in Claude Code. It documents nine lifecycle events, a prompt-based hook API that uses an LLM to make context-aware decisions, and the ${CLAUDE_PLUGIN_ROOT} resolution rules that keep your scripts portable. It scored 89/100 in our auto-review pass — the highest of any skill in the catalog so far.

On this page

1. What is hook-development?
2. When should you use it?
3. How do you install it?
4. What hook events does Claude Code emit?
5. What is the prompt-based hook pattern?
6. How do ${CLAUDE_PLUGIN_ROOT} paths resolve?
7. What are the common pitfalls?
8. Related skills
9. FAQ

What is hook-development?

hook-development is a Claude skill that teaches the agent how to author event-driven hooks for Claude Code plugins. Hooks are short scripts (or LLM prompts) that run in response to specific lifecycle events — when a tool is about to fire, when a session starts, when the agent stops talking — and can validate, mutate, or block the event. The skill ships nine event types with worked JSON examples, the two configuration formats (plugin hooks.json vs user .claude/settings.json), and the ${CLAUDE_PLUGIN_ROOT} path resolution rules that let the same hook script work in development and after install.

Authored by Anthropic and shipped under anthropics/claude-plugins-official, it sits alongside two dozen other official skills (PDF authoring, slack integration, codeql analysis) — but hook-development is the one that turns Claude Code from a chatbot into a programmable runtime.

When should you use it?

Reach for hook-development whenever you’re about to write a hook by hand. The skill loads in under a thousand tokens and saves you from rediscovering the format every six weeks. Concrete triggers it covers, paraphrased from the description:

• “Block dangerous commands” — gate rm -rf, git push --force, and other destructive operations before they fire.
• “Validate tool use” — check arguments against a policy before letting the tool run.
• “Add context on session start” — load project conventions, secrets paths, or runtime info into every new conversation.
• “Enforce completion standards” — make the agent re-run linters before declaring done.
• “React to tool results” — auto-format files after writes, post Slack notifications after deploys.

If you’re using Claude Code without writing plugins, you don’t need this skill. If you’re authoring a plugin and have ever pasted a JSON snippet from someone’s GitHub README and hoped, you do.

How do you install it?

The SkillHub CLI installs any catalog skill into ~/.claude/skills/ in one command. For hook-development:

npx skillhub install anthropics/claude-plugins-official/hook-development
npx skillhub list | grep hook-development

If you’d rather pin to a specific commit, the skill source lives at anthropics/claude-plugins-official on GitHub. The SkillHub getting-started guide covers the full install loop, including how to remove a skill cleanly.

What hook events does Claude Code emit?

Claude Code emits nine event types, each with a different signature and use case. The skill catalogs them with examples; here’s the comparison table you’ll wish you had on day one:

The skill’s biggest practical insight is which events accept the prompt-based hook API (next section) and which only accept commands. PreToolUse, Stop, SubagentStop, and UserPromptSubmit support both; the rest are command-only.

What is the prompt-based hook pattern?

A prompt-based hook is a hook whose body is a natural-language instruction, evaluated by an LLM at runtime instead of running shell code. It’s the part of the hook system most teams haven’t seen yet, and it changes what hooks are good for.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Inspect $TOOL_INPUT. If the command would touch files outside the current repo, exfiltrate secrets, or run as root, return blocked with a one-sentence reason. Otherwise return ok.",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

The same hook written as a command would be a fragile bash script of greps and case statements. As a prompt, it generalises to commands you didn’t anticipate when you wrote the rule. The skill includes four worked examples — including one that uses prompt hooks to enforce that every Stop happens after the test suite passed.

How do ${CLAUDE_PLUGIN_ROOT} paths resolve?

${CLAUDE_PLUGIN_ROOT} expands to the absolute path of the installed plugin at runtime. The skill stresses why this matters: write "command": "${CLAUDE_PLUGIN_ROOT}/scripts/lint.sh" instead of a hardcoded path, and the same hook works whether you cloned the plugin into ~/.claude/plugins/foo/, /opt/claude/plugins/foo/, or a containerized install. Without it, every install needs path-rewriting; with it, plugins are portable.

What are the common pitfalls?

Three traps the skill flags explicitly:

1. Format confusion. Plugin hooks.json needs the {"hooks": {...}} wrapper; user .claude/settings.json uses events directly at top level. Mixing them silently produces a “hook never fires” bug that is frustrating to debug.
2. Missing the matcher. Without "matcher": "Bash" on a PreToolUse hook, it fires on every tool — including Read and Edit, which usually isn’t what you wanted.
3. Treating prompt hooks like assertions. They’re judgments. They can be wrong. Pair high-stakes prompt hooks (PreToolUse on Bash) with a deterministic command safety net for the cases you can express as code.

Related skills

If hook-development fits your workflow, three other Pass-rated skills compound with it:

• writing-skills — meta-skill from sickn33/antigravity-awesome-skills on how to author SKILL.md files. Pair with hook-development when shipping a plugin that bundles both.
• codeql from trailofbits/skills — drops as a PostToolUse hook on Write for security scanning.
• design-review from garrytan/gstack — natural fit as a Stop hook for any UI-touching project.

Browse the rest of the catalog at skills.palebluedot.live, or read the getting-started guide if you’re new to SkillHub. The full Skill Spotlight archive tracks the highest-aiScore skills as they ship.

FAQ