Claude Code plugins, and when you actually need one

A plugin is not a new capability. It is packaging for the skills, subagents, hooks, and MCP servers you can already write, plus a way to version and share them. What plugins contain, which prebuilt ones are worth installing, how to convert a .claude directory into one, and the context cost nobody mentions.

The quickest way to understand Claude Code plugins: a plugin is a folder containing the things you can already write, plus a manifest that makes it installable. Skills, subagents, hooks, MCP servers, and a few extras go in a directory, .claude-plugin/plugin.json names it, and now other people can install it with one command and get updates when you bump a version.

That framing decides everything else. If you have written a skill or a hook, you already know how to write a plugin; what you are choosing is a distribution model. This post covers what goes inside one, which prebuilt plugins are worth the install, how to convert an existing .claude/ setup, and the costs that only show up after a few weeks.

Standalone or plugin

Both approaches give Claude the same abilities. The differences that matter:

The honest rule: start standalone, convert when you actually need to share. Iterating on a skill in .claude/skills/ is faster, and namespacing is a real cost, since /my-plugin:deploy is more to type than /deploy every day forever.

Our own repo is a good example of the boundary. It has eight subagents, a pipeline orchestrator, hooks, and permission settings in .claude/, which is exactly the shape that becomes a plugin. We have not converted it, because it serves one repo and one person, and packaging would buy namespacing and nothing else. The day a second project needs the same pipeline, that calculus flips.

What goes inside

The layout, with the mistake everyone makes called out first: only plugin.json goes inside .claude-plugin/. Every other directory sits at the plugin root.

my-plugin/
├── .claude-plugin/
│   └── plugin.json      # name, description, version, author
├── skills/              # <name>/SKILL.md
├── agents/              # subagent definitions
├── hooks/hooks.json     # event handlers
├── .mcp.json            # MCP servers
├── .lsp.json            # language servers
├── monitors/            # background watchers
├── bin/                 # executables added to PATH while enabled
└── settings.json        # defaults applied when enabled

The name field is the namespace, so a hello/ skill in a plugin named my-first-plugin becomes /my-first-plugin:hello. A plugin shipping exactly one skill can put SKILL.md at the root and skip the skills/ directory.

Three parts are less known and worth a look:

• monitors/monitors.json runs a background command (tail -F ./logs/error.log) and delivers each stdout line to Claude as a notification during the session. No prompting needed; the plugin just watches.
• .lsp.json wires a language server, which is the biggest capability jump in the whole system. More on that below.
• bin/ puts executables on the Bash tool's PATH while the plugin is enabled, which is how a plugin ships a helper script its skills can call from anywhere.

To develop one, skip the install flow entirely:

claude --plugin-dir ./my-plugin      # load it for this session
/reload-plugins                       # pick up edits without restarting

A local --plugin-dir copy takes precedence over an installed plugin of the same name, so you can test changes without uninstalling. If you would rather not pass the flag every launch, claude plugin init my-tool scaffolds a plugin inside ~/.claude/skills/ that loads automatically as my-tool@skills-dir.

Installing: marketplaces in two steps

A marketplace is a catalog; adding one installs nothing. The three you should know:

# Official, curated by Anthropic. Added automatically on first interactive launch.
/plugin install github@claude-plugins-official

# Community, third-party plugins that passed validation and safety screening.
/plugin marketplace add anthropics/claude-plugins-community
/plugin install <name>@claude-community

# Demo plugins, useful for seeing what is possible.
/plugin marketplace add anthropics/claude-code

Marketplaces can also come from any git URL, a local path, or a hosted marketplace.json. /plugin opens a four-tab manager: Discover, Installed, Marketplaces, Errors. The Errors tab is the first place to look when a plugin silently does nothing.

Installing asks for a scope: user (you, everywhere), project (everyone on the repo, written to .claude/settings.json), local (you, this repo only). Administrators can also push managed plugins you cannot modify.

Two details worth knowing before you install anything. The plugin detail pane shows a Context cost estimate, which is how many tokens the plugin adds to every turn, and a Will install list of the exact commands, agents, skills, hooks, and servers it contributes. Read both. A plugin is not free; it is rent.

What is actually worth installing

Most plugin roundups list everything. Here is the short version of what changes your day:

Language server plugins, first and by a distance. typescript-lsp, pyright-lsp, rust-analyzer-lsp, gopls-lsp, and friends give Claude two things it does not otherwise have: diagnostics reported back after every single edit, so a type error or missing import gets noticed and fixed in the same turn instead of surfacing when you finally run the build, and real code navigation (go to definition, find references, call hierarchy) instead of grep. You have to install the language server binary yourself; the plugin only wires it. If a plugin does nothing after install, check the Errors tab for Executable not found in $PATH.

security-guidance reviews each change Claude makes for common vulnerabilities and pushes it to fix what it finds in the same session. This is the "gate, do not hope" idea from our hooks post shipped as a package.

Integration plugins (github, linear, sentry, slack, figma, supabase, and so on) bundle preconfigured MCP servers, which saves the fiddly part of MCP setup. Install the one or two you actually use; MCP tools are the most expensive thing you can add to a context window.

Workflow plugins like commit-commands and pr-review-toolkit are convenient but are also the easiest category to write yourself, and yours will fit your repo better.

Converting a .claude/ directory into a plugin

The migration is mostly copying, with one real change:

mkdir -p my-plugin/.claude-plugin
# write plugin.json with name, description, version
cp -r .claude/skills my-plugin/
cp -r .claude/agents my-plugin/

Hooks are the exception. They move out of settings.json and into hooks/hooks.json, with the same object shape you already had. Then claude --plugin-dir ./my-plugin to test, and check each piece: skills by invoking /my-plugin:name, agents in /context under Custom Agents, hooks by triggering the event they match.

Two migration traps:

• Delete the originals afterward. Project and user .claude/agents/ definitions override same-named plugin agents, so the plugin's version silently never runs while the old file exists.
• Skills do not override, they coexist. Because plugin skills are namespaced, the original /deploy and the plugin's /my-plugin:deploy both stay available, which is confusing if you thought you migrated.

To push a plugin to a team, put the marketplace in the project's .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "my-team-tools": {
      "source": { "source": "github", "repo": "your-org/claude-plugins" }
    }
  }
}

Once a teammate trusts the repository folder, the marketplace registers without another prompt. One current caveat: a plugin from an external source that only the project settings enable does not load until the teammate installs it, and Claude Code tells them the claude plugin install command to run.

The costs nobody mentions

• Every enabled plugin is context rent. It costs tokens on every turn, forever, whether or not you use it. The /plugin Installed tab flags plugins you have not used in two weeks across at least ten sessions under a Not used recently header, with a Last used line in the detail view. Audit that list quarterly and uninstall freely.
• /reload-plugins is not free. Loading new components appends content to the conversation, and a plugin providing MCP servers can invalidate the prompt cache so the next request re-reads the whole conversation. Reload deliberately, not reflexively.
• Plugins run arbitrary code with your privileges. Anthropic does not control what a third-party plugin contains and cannot verify it does what it claims. Marketplaces are as trusted as the person who published them, so treat adding one like adding a dependency, not like clicking install on an app store.
• The /plugin panel stays open after /plugin disable, /plugin enable, or /plugin uninstall, so press Escape before typing the next command. Use the claude plugin shell commands when scripting.

The short version

1. A plugin is packaging, not new capability. Skills, agents, hooks, and MCP servers you already know how to write.
2. Start in .claude/, convert when you need to share or version. Namespacing is the price.
3. Only plugin.json lives in .claude-plugin/. Everything else at the root.
4. Develop with --plugin-dir plus /reload-plugins. Never install to test.
5. Install the LSP plugin for your language today. It is the one with a capability upgrade behind it.
6. Read the context cost before installing, and audit the unused list later.

One side effect worth predicting: the more capable you make the agent, the longer its turns get. Diagnostics after every edit, an MCP server or two, a security reviewer in the loop, and a turn that took ninety seconds now takes three minutes and produces better work. That trade is usually worth it, and it makes the question of what you do during those minutes larger, not smaller. Ours is one flashcard per wait; the point is having an answer before the waits get longer.