Claude Code Hooks vs Plugins: Which One for Your Workflow
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/<name>/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) 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
| Situation | Reach for | Why |
|---|---|---|
| Block a destructive command in just this repo | Hook | No distribution need yet — a JSON entry in this repo's settings is the whole job |
| Same destructive-command guard needed in every repo you start | Plugin containing the hook | One install/update instead of re-pasting the same JSON entry each time |
| Auto-format on save, single project | Hook | Project-specific, no reuse case — packaging adds overhead with no payoff |
| A hook that depends on a specific subagent or skill also existing | Plugin bundling all of them | Shipping the hook alone leaves a dependency the installer has to notice and add manually |
| Giving a teammate your hook setup without them copying files by hand | Plugin | A plugin install is one command; a hook snippet in Slack is manual and easy to get out of sync |
| Updating a hook's logic and wanting every consumer to get the fix | Plugin, version bumped | Consumers pull an update step; a standalone hook only updates where someone remembers to edit it |
Same underlying rule as 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
- 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/orskills/) — 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.
For worked hook configurations across formatting, bash-safety, and PR-guardrail categories to start from, see 15 Claude Code Hooks Examples.
Related pages
Frequently asked questions
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.
Hooks and agents, already packaged
AgenticKit installs 34 subagents with the hooks, skills and commands that gate their actions as one versioned bundle — the plugin shape, pre-built.