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

SituationReach forWhy
Block a destructive command in just this repoHookNo distribution need yet — a JSON entry in this repo's settings is the whole job
Same destructive-command guard needed in every repo you startPlugin containing the hookOne install/update instead of re-pasting the same JSON entry each time
Auto-format on save, single projectHookProject-specific, no reuse case — packaging adds overhead with no payoff
A hook that depends on a specific subagent or skill also existingPlugin bundling all of themShipping 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 handPluginA 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 fixPlugin, version bumpedConsumers 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

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.