How does a Claude Code plugin marketplace work, from its marketplace.json catalog to installing a plugin as name@marketplace?
answer
- a catalog, not a hosted store
- .claude-plugin/marketplace.json at the repo root
- name, owner, plugins with name and source
- /plugin marketplace add, then install
- entry name versus manifest name
basics
~10 sA 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 sA 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{
"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
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.
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.
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.
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.