skip to content

How does a Claude Code plugin marketplace work, from its marketplace.json catalog to installing a plugin as name@marketplace?

level: middleimportance: should knowfreq 12%

answer

  1. a catalog, not a hosted store
  2. .claude-plugin/marketplace.json at the repo root
  3. name, owner, plugins with name and source
  4. /plugin marketplace add, then install
  5. entry name versus manifest name

basics

~10 s

A marketplace is a repository or directory whose .claude-plugin/marketplace.json lists plugins and where to fetch each. You register it once with /plugin marketplace add, then install plugins by entry name as plugin@marketplace.

solid answer

~40 s

A marketplace is a catalog, not a store: a directory or repository with `.claude-plugin/marketplace.json`, which requires a `name`, an `owner` and a `plugins` array whose entries each need a `name` and a `source`. A source is a relative path inside the marketplace, or an object such as `github`, `git-subdir`, `url`, `archive`, `npm` or `command`. Users register it once with `/plugin marketplace add your-org/plugins` (or a git URL, a `./local` path, or a hosted `marketplace.json` URL), and it registers under the `name` in the file, not the repository name. They then run `/plugin install formatter@your-marketplace`, which opens the details pane to pick a scope, or `claude plugin install` from a script. Anthropic's official marketplace, `claude-plugins-official`, is added on the first interactive session; any other one has to be added, by the user or through settings.

code

json · 15 lines
json
{
  "name": "platform-tools",
  "owner": { "name": "Platform Team" },
  "plugins": [
    {
      "name": "team-toolkit",
      "source": "./plugins/team-toolkit",
      "description": "Review skills, reviewer agent, format hook, MCP servers"
    },
    {
      "name": "db-helpers",
      "source": { "source": "github", "repo": "example-org/db-helpers" }
    }
  ]
}

go deeper

for a junior

Recall the two steps: add the marketplace once with /plugin marketplace add, then install a plugin by name@marketplace and pick a scope in the details pane.

for a middle

Explain marketplace.json's required name, owner and plugins, the source types, and why the entry name rather than the plugin.json name is the install and enabledPlugins key.

for a senior

Show you can debug a broken catalog: relative paths in a URL-hosted file, mismatched names, reserved names refused, and validate passing while a remote source fails at install.

for a principal

Weigh hosting choices for a team catalog: one git repository with relative paths versus per-plugin repositories, private-repo credentials on every machine, and who owns the catalog's updates.

## What a marketplace is A **plugin marketplace** is a directory or git repository containing `.claude-plugin/marketplace.json`, a file that lists plugins and tells Claude Code where to fetch each one. It is a **catalog, not a hosted store**: nothing is uploaded to Anthropic, and the plugins may live inside the marketplace repository or anywhere the listed source points. Claude Code adds Anthropic's official marketplace, `claude-plugins-official`, the first time you start an interactive terminal session, unless a managed policy blocks it. Every other marketplace, including a team's own, is added by the user, by a repository's committed settings, or by an administrator through managed settings, which is another topic. ## The marketplace.json file The file has three required parts: - **`name`**: the marketplace's identifier, the part after `@` in every install id. - **`owner`**: who maintains it, at least a `name`. - **`plugins`**: an array of **plugin entries**, each with a `name` and a `source`, plus optional fields such as `description` and `version`. The `source` decides where the plugin is fetched from: | Source | Use it when | |---|---| | Relative path, e.g. `./plugins/formatter` | The plugin's files are inside the marketplace directory | | `github` with `repo` | The plugin is its own GitHub repository | | `git-subdir` with `url` and `path` | The plugin is a folder in a larger repository | | `url` | A git repository on any host | | `archive` | A zip downloaded over HTTPS, optionally pinned by `sha256` | | `npm` or `command` | An npm package, or a directory a command produces on the user's machine | A relative path is written from the marketplace root (the directory containing `.claude-plugin/`) and may not contain `..`. Run `claude plugin validate ./my-marketplace` after each edit: it checks JSON syntax, required fields, naming rules and each relative-path plugin's `plugin.json`. It does not fetch remote sources, so a wrong `repo` only shows up at install. ## Adding a marketplace In a session, `/plugin marketplace add <source>`; from a shell, `claude plugin marketplace add <source>`. The source can be: 1. A GitHub repository as `owner/repo`, optionally pinned with `#ref` (a branch or tag). 2. A full git clone URL on any host, with `https://` or `git@host:path`. 3. A local directory or file path, starting with `./` or `../` so it is not read as GitHub shorthand. 4. A hosted `marketplace.json` URL. The marketplace registers under the `name` inside the file, not the repository's name, and is recorded in your user settings under `extraKnownMarketplaces`. A successful add prints `Successfully added marketplace: <name>`, and its plugins appear on the **Discover** tab with no reload. A **private** repository is added the same way, but Claude Code clones it with the git credentials already on the machine and never prompts: - **HTTPS**: your git credential helpers apply, such as access set up with `gh auth login`; a host you never authenticated to fails instead of asking for a password. - **SSH**: the host must already be in `known_hosts`, and the key must work without a passphrase prompt. - **`owner/repo` shorthand**: Claude Code tries SSH to github.com first and falls back to HTTPS; `CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1` skips the SSH check. Every teammate needs read access to that repository, because each machine clones it. ## Installing from it The install id is `<entry-name>@<marketplace-name>`. In a session, `/plugin install formatter@your-marketplace` does not install immediately; it opens the plugin's details so you can review what it adds and choose a scope. From a shell, `claude plugin install formatter@your-marketplace` installs at user scope unless you pass `--scope project` or `--scope local`. The **Discover** tab of `/plugin` lists every plugin from the marketplaces you have added. ## Two names, and other traps A marketplace plugin has an **entry name** in `marketplace.json` and a **manifest name** in its own `plugin.json`: - The entry name is the install key, the `enabledPlugins` key and what `claude plugin list` shows. - The manifest name is the prefix on the plugin's skills and agents. When they differ, installing by the manifest name fails with a not-found error, so keep them equal. Other traps: - A marketplace hosted as a bare `marketplace.json` URL downloads only that file, so relative-path entries fail; use fetchable sources or host the whole tree in git. - Official and community names such as `claude-plugins-official` or `claude-community` are accepted only from `github.com/anthropics/` repositories; anything else is third-party, whatever it calls itself. - Removing a marketplace uninstalls every plugin you installed from it. ## Managing marketplaces `claude plugin marketplace list` prints each marketplace with its source, `update <name>` refreshes a listing, and `remove <name>` deletes it. The **Marketplaces** tab in `/plugin` does the same and also toggles background auto-update per marketplace.

  • A teammate runs the install with the plugin's manifest name and gets a not-found error. What happened?
    The install id uses the entry `name` from `marketplace.json`, not the `name` in the plugin's own `plugin.json`. When the two differ, Claude Code reports that the plugin is not found in the marketplace. Keep the entry name and the manifest name identical; the entry name is also the key written to `enabledPlugins`, while the manifest name prefixes the plugin's skills and agents.
  • Why do relative-path entries fail when users add the marketplace by its marketplace.json URL?
    Added by URL, Claude Code downloads only the `marketplace.json` file, so a `./plugins/formatter` source points at a directory that was never fetched. Give such entries sources that fetch on their own, such as `github` or `archive`, or host the marketplace in a git repository so Claude Code clones the whole tree.

  • A marketplace is a store where Anthropic hosts the uploaded plugins.
  • The marketplace registers under its GitHub repository name.
  • Installing by the plugin.json name works whatever the entry says.
  • Any repository can call itself claude-plugins-official and be trusted.
  • claude plugin validate also checks that remote sources resolve.