Plugins and plugin marketplaces

Why you'd careThe problem it solves

Four teams now want the skill you wrote. You did the obvious thing and copied .claude/skills/ into each repository. Six weeks later there are four versions: one has the bug fix, one has a local tweak nobody remembers making, one is missing the reference file because the copy was done by hand, and one is fine. Somebody asks which is current and there is no answer, because copying gave you distribution without giving you identity. A plugin makes the skill an installable thing with a name and a version, and a marketplace is where installs come from. The moment more than a couple of repos want the same behaviour, that is the boundary you have crossed.

ConceptWhat it is

A plugin is a directory that bundles extensions to Claude Code into one installable unit. It is identified by .claude-plugin/plugin.json at its root, which carries the name, description and version. Alongside that it may contain any combination of skills/, commands/, agents/, a hooks definition, and an MCP server configuration. A plugin containing zero skills is perfectly normal; skills are one of several payloads, not the point of the format.

A marketplace is the catalog that lists plugins. It is not a hosted service and there is nothing to sign up for — it is a git repository (or a local directory) with .claude-plugin/marketplace.json at the root, containing a marketplace name, owner information, and a plugins array whose entries point at plugin directories inside the same repo or at other repos. A private marketplace is therefore a private repo; access control is whatever your git host already does.

Users combine the two names when installing: the plugin's name, then the marketplace it came from. That composite is also how the harness disambiguates — skills delivered by a plugin are listed to the model under a qualified name that includes the plugin, so two plugins can each ship a skill called review without one shadowing the other.

The important asymmetry: the marketplace name is not scoped by the repo it came from. It is a single global key on each user's machine.

How it worksThe mechanics

The whole thing is files in a repo. A minimal marketplace with one plugin looks like this:

acme-eng/                          a plain git repo
├── .claude-plugin/
│   └── marketplace.json           the catalog - one per repo
└── plugins/
    └── release-tools/
        ├── .claude-plugin/
        │   └── plugin.json        name, description, version
        ├── skills/
        │   └── changelog/
        │       └── SKILL.md
        ├── commands/
        │   └── cut-release.md
        └── hooks/
            └── hooks.json

The catalog itself:

{
  "name": "acme-eng",
  "owner": { "name": "Acme Platform Team", "email": "platform@acme.example" },
  "plugins": [
    {
      "name": "release-tools",
      "source": "./plugins/release-tools",
      "description": "Changelog, release notes and tag hygiene for Acme services."
    }
  ]
}

Installing is two steps in a session: add the marketplace by pointing at the repo, then install release-tools from acme-eng. Both are done through the /plugin interface. The reload that used to be a gotcha is now handled for you: when the install summary says Run /reload-plugins to activate., Claude Code runs it itself, and you step in only if it warns about re-reading the conversation, with /reload-plugins --force.

Two details worth internalising. First, scripts and hooks inside a plugin must not assume a working directory; the plugin root is exposed as an environment variable so paths can be written relative to wherever the plugin was installed. Second, the marketplace name is a global-per-user key. Adding a second marketplace that declares the same name replaces the first, and the symptom is that a colleague's plugins vanish. Publish everything your organisation ships under one marketplace.json rather than standing up several catalogs that happen to share a name.

For org-wide rollout, the managed settings file lists the marketplaces a machine trusts and the plugins to enable automatically. Confirm the exact key names against your version's settings reference before rolling that out — this is the part of the surface that has moved most.

At a glanceSee it

How a skill travels from your repo into a teammate's session, and where the name collision bites.

Where it runsSurfaces and availability

Read the table as a warning about lock-in shape rather than lock-in severity. The content of a skill is portable, and more so than it looks: SKILL.md is an open standard (agentskills.io, cited from code.claude.com/docs/en/skills) that Codex and Antigravity both implement, just at .agents/skills rather than .claude/skills. What does not travel is the packaging — the plugin manifest, the marketplace, and the commands, hooks and agents you bundled next to the skill. If a skill must also serve a server-side agent or a second vendor, keep its body free of Claude Code assumptions and treat the plugin as a distribution wrapper you can rebuild, not as the artefact itself.

ExampleIn the real world

Acme's platform team owns three skills: changelog, incident-review and db-migration. They live in three product repos as copies, and the copies have drifted.

The team creates one private repo, acme-eng, with a single marketplace.json and two plugins inside it: release-tools (the changelog skill plus a /cut-release command) and ops-standards (incident review and migration rules, plus a hook that blocks committing a migration without a backfill). Engineers add the marketplace once and install what they need; the product repos delete their copies.

A month later someone finds that the changelog skill misreads squashed merge commits. The fix lands in acme-eng, gets a version bump, and reaches everyone through the update path instead of through three pull requests and a Slack message.

Then a second team publishes its own catalog and calls it acme-eng too, because that is the obvious name. Anyone who adds it stops seeing the platform team's plugins: same key, last write wins. The fix is organisational rather than technical — one catalog per organisation, more plugins inside it.

Not thisWhat it is often confused with

• Not an npm registrythere is no dependency graph and no resolver. Version is metadata that helps humans; installing is fetching a git repo (or a zip or npm package) and reading a JSON file. Do not design as if transitive dependencies will be handled for you.
• Not a skilla plugin is a container. It can hold skills, slash commands, subagent definitions, hooks and an MCP server, in any combination including none of the above. “Install the plugin” and “get the skill” are not synonyms.
• Not an MCP servera plugin can ship an MCP server configuration, which is why the two get conflated. The server is a process exposing tools over a protocol; the plugin is a folder that tells the client where to find it.
• Not a hosted marketplacenothing is submitted, reviewed or approved. A marketplace is a repo you already control, so its access model is your git host's access model and its trust model is “you read the code”.
• Not a permission grantinstalling a plugin does not sandbox what its hooks and scripts may do. Installing from a marketplace you do not control is running someone else's code with your credentials, and should be treated with the seriousness that implies.

LimitsWhen not to reach for it

• One repository.Commit the skill under .claude/skills/ and stop. A marketplace for a single consumer adds a publish step to every edit and buys nothing.
• The behaviour is mandatory, not optional.Plugin skills still load only when the model judges them relevant. If policy must apply every time, ship a hook or a CI check — distribution does not turn a suggestion into a guarantee.
• The thing you actually need is a tool.If the goal is to let the model call your internal API, that is an MCP server. Wrapping it in a plugin is fine for convenience but the plugin is not doing the work.
• The content is still moving daily.Publish once the skill has stopped changing shape. Early on, the feedback loop of editing a local file beats the loop of commit, push, update, reload.
• You need per-user secrets in it.A marketplace repo is readable by everyone who can install from it. Ship the instructions; have the skill read credentials from the environment at run time.

RelatedGo deeper