Claude Code Plugins: What They Bundle

A Claude Code plugin is a directory that bundles your customizations — skills, agents, hooks, MCP servers, and more — into one thing you can version, share, and install.

The decision that comes first isn't how to build one. It's whether you need one at all:

Anthropic's guidance is to start standalone in .claude/ and convert when you're ready to share. That's the right order — a plugin adds a namespace, a manifest, and a distribution story you don't need while you're still iterating alone.

What a plugin can contain

More than most people realise. Everything below lives at the plugin root:

The single most common mistake: putting skills/, agents/, hooks/, or commands/ inside .claude-plugin/. Only plugin.json goes in there. Everything else sits at the plugin root, alongside it. If your skills aren't loading and you're sure the syntax is right, check this first.

The manifest itself is small, and optional when your components use default locations:

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": { "name": "Your Name" }
}

name does double duty: it identifies the plugin and becomes the skill namespace, so a hello/ skill in a plugin named my-first-plugin is invoked as /my-first-plugin:hello. Namespacing is mandatory and deliberate — it's what stops two plugins that both ship a /review skill from colliding.

version is optional but consequential: if you set it, users only receive updates when you bump it.

Building and testing one locally

The fastest loop doesn't involve a marketplace at all. Point Claude Code at a directory:

claude --plugin-dir ./my-plugin

That loads the plugin for the session without installing anything. The flag accepts a .zip archive too, and you can repeat it to load several plugins at once. If a local plugin shares a name with one you've already installed, the local copy wins for that session — which is exactly what you want when testing a change to something you use daily.

As you edit, run /reload-plugins to pick up changes without restarting. That reloads skills, agents, hooks, and plugin MCP and LSP servers.

There's a lighter path if you don't want to pass a flag every time:

claude plugin init my-tool

That scaffolds ~/.claude/skills/my-tool/ with a manifest and a starter SKILL.md, and it auto-loads on the next session as my-tool@skills-dir — no marketplace, no install step. It's the best way to develop something you're also using.

Before you share anything, validate it:

claude plugin validate ./your-plugin

The review pipeline runs the same check on every submission, so a local pass saves a round trip. Add --strict to treat warnings as errors.

Marketplaces

A marketplace is how plugins get distributed. Anthropic runs two public ones:

• claude-plugins-official — a curated set maintained by Anthropic, registered automatically the first time you start Claude Code interactively. There's no application process; Anthropic decides what goes in.
• claude-community — the public community marketplace, where third-party submissions land after review. Add it with /plugin marketplace add anthropics/claude-plugins-community and install from it as @claude-community.

Submissions go through an in-app form — on claude.ai for Team and Enterprise organisations, or through the Console for individual authors outside one. Approved plugins are pinned to a specific commit SHA in the community catalog, and CI moves the pin as you push. The catalog syncs nightly, so there's a lag between approval and installability.

For a team that doesn't want any of this public, host the marketplace in a private repository. That's the normal answer for internal tooling.

Converting what you already have

If you've accumulated skills and hooks in .claude/, migration is mostly copying:

mkdir -p my-plugin/.claude-plugin
cp -r .claude/skills my-plugin/
cp -r .claude/agents my-plugin/

Hooks are the one that changes shape: they move out of settings.json and into hooks/hooks.json, though the hooks object itself keeps the same format, so you can lift it across unchanged.

Afterwards, delete the originals from .claude/. Project and user .claude/agents/ definitions override same-named plugin agents, so the plugin version stays dormant until the originals are gone. Skills behave differently — the plugin copy is namespaced, so /skill-name and /plugin-name:skill-name both survive and you get two entries instead of one.

When to skip plugins entirely

Stay standalone if you're the only user, if the setup is specific to one repository, or if you're still changing it weekly. The packaging overhead buys you distribution, and distribution is worth nothing until someone else wants the thing.

Convert when a teammate asks for your setup, when you want versioned updates rather than "copy this folder", or when you're publishing. Those are the moments the namespace and the manifest start paying for themselves.

FAQ

What is a Claude Code plugin?

A directory that bundles skills, agents, hooks, MCP servers, LSP servers, and background monitors into one installable, versionable unit, usually with a .claude-plugin/plugin.json manifest.

How do I install a Claude Code plugin?

Add a marketplace, then install from it — /plugin marketplace add anthropics/claude-plugins-community followed by an install from @claude-community. The official marketplace registers itself on first interactive launch. The VS Code extension offers the same thing through a /plugins interface.

What's the difference between a plugin and a skill?

A skill is one capability — a folder with a SKILL.md that teaches Claude a repeatable task. A plugin is a container that can ship several skills plus agents, hooks, and MCP servers together.

How do I test a plugin before publishing it?

claude --plugin-dir ./my-plugin loads it for the session without installing. Use /reload-plugins after edits, and claude plugin validate ./my-plugin before submitting.

Why aren't my plugin's skills loading?

Almost always because skills/ was placed inside .claude-plugin/. Only plugin.json belongs there — every other directory sits at the plugin root.

Can I keep a plugin private to my company?

Yes. Host the marketplace in a private repository and only people with access can install from it.

The short version

Plugins are packaging, not power. Everything a plugin does, a .claude/ directory already does for you alone — what you're buying is a namespace, a version number, and a way to hand it to someone else. Build one when there's a someone else. Until then, iterate standalone.

"Build one when there's a someone else" is also the question Taku is asking, one layer up. A plugin solves distribution for people who already have Claude Code installed and configured; it does nothing for the much larger group who stall before that. Taku packages the whole running environment rather than the .claude/ directory inside it, so what you hand over opens and works. Taku is in Beta, and the Mac app is available now.