# Claude Code Hooks vs Plugins

> A hook is a deterministic script enforcing a rule at runtime; a plugin is the versioned, shareable bundle that packages hooks (plus commands, skills, agents) for distribution. A decision table and the migration path from a loose hook script to a packaged plugin.

Canonical: https://www.agentickit.co/compare/claude-code-hooks-vs-plugins
Last updated: 2026-11-18

A hook is a script wired to a lifecycle event in .claude/settings.json — it runs unconditionally on every matching event, and a PreToolUse hook can block an action outright. A plugin is a packaged, versioned bundle that can contain hooks (plus commands, skills, and agents) so the whole set installs and updates together across repos. They're not alternatives for the same job: a hook is the enforcement mechanism, a plugin is the distribution mechanism for one or more hooks (and everything else) at once. Last updated 2026-11-16 by Rakshit Yadav.



## Plugins are packaging, hooks are enforcement
A **hook** is a deterministic script registered against a lifecycle event — `PreToolUse`, `PostToolUse`, `Notification`, `Stop`, and others — in a single JSON entry under `.claude/settings.json`. It runs the same way every time an event matches, with no model judgment involved, which is the whole reason a `PreToolUse` hook can actually stop a dangerous command (exit code `2`) instead of just flagging it after the fact.
A **plugin** is a directory with a manifest that a marketplace or git URL can resolve and install in one step. It typically bundles some mix of `hooks/*`, `commands/*.md`, `skills/&lt;name&gt;/SKILL.md`, and `agents/*.md` — a plugin's hook is still a plain hook underneath, registered the same way, just shipped alongside the rest of the bundle with a version number attached. A plugin with zero hooks in it is completely normal; so is a hook that never gets packaged into a plugin at all.
The upshot: "hooks vs plugins" isn't really a fork in the road the way "hooks vs MCP servers" (see [that comparison](https://www.agentickit.co/compare/claude-code-hooks-vs-mcp-servers)) is — a hook is a thing you write, a plugin is a container you might put it in once more than one repo needs it.

## When you need both
The common case: you've already got a working hook — say, a `PreToolUse` guard that blocks edits to `.env` files, or a `PostToolUse` formatter that runs `prettier` after every `Write`. It lives in one repo's `.claude/settings.json` and does its job fine there. The moment a second repo, or a teammate, needs that exact same guard, copy-pasting the JSON snippet by hand starts costing more than it saves — at that point the hook is a candidate for moving into a plugin, where it ships with a version number and installs with one command instead of a manual settings edit per repo.
Plugins also matter when a hook isn't standalone — if your `.env` guard hook is meant to run alongside a `security-reviewer` subagent and a skill that explains the project's secrets-handling convention, those three pieces belong in one plugin together. Shipping the hook alone and leaving the agent/skill it assumes exist as a separate manual step is how a plugin ends up silently broken in a fresh repo.

## Decision table
<table><thead><tr><th>Situation</th><th>Reach for</th><th>Why</th></tr></thead><tbody><tr><td>Block a destructive command in just this repo</td><td>Hook</td><td>No distribution need yet — a JSON entry in this repo's settings is the whole job</td></tr><tr><td>Same destructive-command guard needed in every repo you start</td><td>Plugin containing the hook</td><td>One install/update instead of re-pasting the same JSON entry each time</td></tr><tr><td>Auto-format on save, single project</td><td>Hook</td><td>Project-specific, no reuse case — packaging adds overhead with no payoff</td></tr><tr><td>A hook that depends on a specific subagent or skill also existing</td><td>Plugin bundling all of them</td><td>Shipping the hook alone leaves a dependency the installer has to notice and add manually</td></tr><tr><td>Giving a teammate your hook setup without them copying files by hand</td><td>Plugin</td><td>A plugin install is one command; a hook snippet in Slack is manual and easy to get out of sync</td></tr><tr><td>Updating a hook's logic and wanting every consumer to get the fix</td><td>Plugin, version bumped</td><td>Consumers pull an update step; a standalone hook only updates where someone remembers to edit it</td></tr></tbody></table>Same underlying rule as [Plugins vs Commands](https://www.agentickit.co/compare/claude-code-plugins-vs-commands): build the primitive — here, the hook — for the one repo that needs it first, and only package it into a plugin once a second real consumer shows up.

## Migration path: hook script to packaged plugin
<ol>- **Confirm there's a real second consumer.** If the hook only ever runs in one repo, there's nothing to migrate — see the decision table above.
- **Create the plugin's directory structure.** A manifest at the root, then a `hooks/` folder holding the same script and matcher config the standalone hook already uses — the hook's own logic doesn't change, only where it lives.
- **Pull in anything the hook assumes exists.** If the hook's command references a subagent name or a skill's output, those move into the plugin too (under `agents/` or `skills/`) — a plugin that ships the hook but not what it depends on isn't actually portable.
- **Write the manifest and version it.** A name and starting version turn future edits into something consumers pull as an update instead of a silent, un-trackable overwrite.
- **Test a clean install in a repo that's never had the hook.** This is where a hardcoded path or an assumed file surfaces — the kind of thing that's invisible in the repo where the hook was first written.
</ol>For worked hook configurations across formatting, bash-safety, and PR-guardrail categories to start from, see [15 Claude Code Hooks Examples](https://www.agentickit.co/blog/15-claude-code-hooks-examples).



## FAQ

### Is a plugin just a collection of hooks?
No — a plugin can contain hooks, but just as often bundles commands, skills, and agents instead of or alongside them. A plugin with no hooks at all, made up purely of commands and skills, is completely normal.

### Do I need a plugin to use a hook?
No. A hook works on its own as a JSON entry in .claude/settings.json with no manifest, no marketplace, and no packaging step. A plugin only becomes useful once that hook (or a set of primitives including it) needs to install and update consistently across more than one repo.

### Does packaging a hook into a plugin change how the hook runs?
No. The hook is registered and triggered the same way whether it arrived as a standalone settings.json edit or as part of a plugin install — packaging only changes how the file got into the repo and how later updates propagate.

### What's the actual signal that a hook should become part of a plugin?
A second real consumer — another repo or teammate needing the identical hook, or the hook depending on a subagent/skill that should ship alongside it. Packaging before that point adds a manifest with no one yet needing it.

## Related
- [Claude Code Hooks vs MCP Servers](https://www.agentickit.co/compare/claude-code-hooks-vs-mcp-servers)
- [Claude Code Plugins vs Commands](https://www.agentickit.co/compare/claude-code-plugins-vs-commands)
- [Claude Code Plugins vs Skills vs MCP](https://www.agentickit.co/compare/claude-code-plugins-vs-skills-vs-mcp)
- [CLAUDE.md vs Skills vs Subagents vs Hooks](https://www.agentickit.co/compare/claude-code-skills-vs-subagents-vs-hooks)
- [15 Claude Code Hooks Examples](https://www.agentickit.co/blog/15-claude-code-hooks-examples)
- [The 34 AgenticKit agents](https://www.agentickit.co/agents)
