Claude Code Mods vs Plugins
Everyone mixes these two up — including, in the first week, most of the people writing about them. Here is the actual ontology, as the system works: a plugin is the package, a mod is the code inside the package, and a skill is something else entirely.
The short version
| Concept | What it is | You interact with it by… |
|---|---|---|
| Plugin | The distribution unit — a marketplace entry you install | /plugin install |
| Mod | A TypeScript module inside a plugin that hooks the agent execution pipeline | Using it (it runs automatically once installed) |
| Skill | Markdown instructions that guide the model's behavior | Writing or invoking a checklist |
A plugin is the package
A plugin is how mods travel. It is a repository (or a local folder) containing a marketplace.json, with each mod defined by a plugin.json, a hooks/hooks.json, and the module file itself. When you run /plugin marketplace add hamzafer/claude-code-mods, you are adding a plugin source. When you run /plugin install, you are installing from a plugin. One plugin can ship several mods — hamzafer's collection, for example, bundles live lines, guards, panes, and games in a single installable unit.
A mod is the code
A mod is the TypeScript module inside the plugin that actually runs. It exports a register function that subscribes to events in the agent's execution pipeline — requests going out, responses coming back, tool calls being made. When an event fires, the mod's code runs and can observe, transform, or block what happens next. For UI it gets a dedicated $ API (rendering, state, files, HTTP, tools). If plugins are the shipping container, mods are the cargo.
A skill is instructions, not code
Skills are the third concept and the easiest to confuse with mods, because both "change what the agent does." The difference is mechanism: a skill is markdown text that the model reads — a checklist like "when reviewing code, check for SQL injection and verify error handling." A mod is code that the pipeline executes. Skills guide judgment; mods intercept execution. They compose well: a skill can tell the agent what to check, while a mod enforces that it gets checked.
How they fit together in practice
- Installing: you always install at the plugin level (
/plugin install <mod>@<marketplace>). There is no separate "mod install" command — the mod comes along inside the plugin. - Building: you always build at the mod level (write the module, export
register), then wrap it in plugin packaging so others can install it. See Build Your First Claude Code Mod. - One to many: a single plugin routinely contains multiple mods. The
marketplace.jsonlists them;plugin.jsondescribes each one. - Skills ride along: a repo can ship skills and mods together — claude-kit does exactly this, which is why it is a good starter pack.
Common mix-ups, cleared up
- "I installed the mod but…" — you installed the plugin; the mod inside it runs automatically. If nothing happens, the mod may only activate on events you have not triggered yet.
- "Is this a mod or a skill?" — ask: does it run code on pipeline events (mod), or is it text the model reads (skill)? Repos often contain both, which is where the confusion starts.
- "Do I need the plugin system to use mods?" — for installing, yes. For developing, no:
claude --plugin-dir ./my-modloads a mod straight from a folder.