# Publishing a Private Plugin Marketplace for Your Team

URL: https://developertoolkit.ai/en/ecosystem/plugins/team-marketplace/
Description: Run a private plugin marketplace for Claude Code, Codex and Cursor: repo layout, reserved names, version rule, private-repo auth, CI validation and rollout.

A private plugin marketplace is a git repository with a catalogue file (`.claude-plugin/marketplace.json`) that lists your team's plugins. Claude Code installs from it, Codex 0.157.1 reads the same file, and Cursor imports its own catalogue as a team marketplace. A change reaches teammates only when the plugin's `version` changes, so CI must enforce the bump.

You packaged the team's release checklist and API conventions as plugins, pushed them, and told everyone to install. Two weeks later you fix a wrong rule in the API skill, and half the team still runs the old one. Nobody bumped the version, one person's clone of the private repository fails silently, and a new hire has `enabledPlugins` committed but no plugin installed. This page is for the tech lead who owns the marketplace and the developer who ships changes to it. It assumes you can already [build a plugin](/en/ecosystem/plugins/building-plugins/); here you run the channel that delivers it.

## What a working team marketplace gives you

- A two-plugin marketplace repository, `acme-plugins`, with every file shown and tested on Claude Code 2.1.283 and codex-cli 0.157.1
- A CI gate, `scripts/check-marketplace.sh`, that fails a pull request on a schema warning, a reserved name, a missing source directory or a change without a version bump
- The release loop: pull request, CI, merge, tag, and one update command per teammate
- Four rollout routes (per person, per repository, fleet-wide, claude.ai organization sync) with what each one does and does not install
- A recovery list for the failures that leave teammates on stale plugins

Everything marked as observed below was run on 2026-09-26 in a scratch home directory. The Cursor catalogue was checked against the schemas in Cursor's `cursor/plugins` repository; the dashboard import comes from secondary sources, because cursor.com was unreachable, and was not run.

## How a change travels from a pull request to every teammate

The marketplace has one job: make sure that what is merged is what every teammate runs. Each stage has a check that replaces reading the change line by line.

| Stage | Who | Check that proves it | Tool |
| ----- | --- | -------------------- | ---- |
| Pull request | Plugin author | CI: strict validation, install smoke test, version-bump rule | `scripts/check-marketplace.sh` |
| Review | Owner in `CODEOWNERS` | CI green, version bumped, always-on token cost read from CI log | GitHub review |
| Release | Marketplace owner | `claude plugin tag` confirms `plugin.json` and the catalogue agree | `claude plugin tag --push` |
| Rollout | Every teammate, or managed settings | `claude plugin list` shows the new version | `claude plugin marketplace update`, `claude plugin update` |

## Build the two-plugin marketplace repository

The example marketplace ships two plugins. `acme-release` holds a release-check skill; `acme-api-style` holds the team's HTTP API conventions. Both are skills only, so they cost little context and carry across agents.

1. **Lay out the repository.** Keep each plugin under `plugins/` and the catalogue at the root.

   ```text
   acme-plugins/
   ├── .claude-plugin/marketplace.json       # the catalogue; Codex reads it too
   ├── .cursor-plugin/marketplace.json       # optional: Cursor's own catalogue
   ├── .github/CODEOWNERS
   ├── .github/workflows/plugin-marketplace.yml
   ├── scripts/check-marketplace.sh
   └── plugins/
       ├── acme-release/
       │   ├── .claude-plugin/plugin.json
       │   └── skills/release-check/SKILL.md
       └── acme-api-style/
           ├── .claude-plugin/plugin.json
           └── skills/api-conventions/SKILL.md
   ```

2. **Write the catalogue.** The `name` is what everyone types after `@`, so choose it once and never change it. `validate --strict` fails without the top-level `description`.

   ```json title=".claude-plugin/marketplace.json"
   {
     "name": "acme-plugins",
     "description": "Internal plugins for Acme engineering",
     "owner": { "name": "Acme Platform Team", "email": "platform@acme.example" },
     "plugins": [
       {
         "name": "acme-release",
         "source": "./plugins/acme-release",
         "description": "Release checklist skill: changelog, migrations, feature flags"
       },
       {
         "name": "acme-api-style",
         "source": "./plugins/acme-api-style",
         "description": "Acme REST conventions: error envelope, pagination, versioning"
       }
     ]
   }
   ```

   Do not put a `version` in these entries. If one disagrees with `plugin.json`, `plugin.json` wins at install time and the entry is silently ignored; `validate --strict` reports it as a warning and fails.

3. **Avoid reserved marketplace names.** Claude Code refuses names that imitate Anthropic's marketplaces. Observed on 2.1.283: `validate --strict` passed with `"name": "claude-code-marketplace"`, and then `claude plugin marketplace add` failed with `The name 'claude-code-marketplace' is reserved for official Anthropic marketplaces and can only be used with GitHub sources from the 'anthropics' organization.` The same happened with `anthropic-plugins`. The marketplace reference also reserves `npm`, `github`, `gh`, `claudeai-*`, `inline`, `builtin`, `skills-dir` and `synced`. A prefix with your company name avoids all of them.

4. **Give each plugin a version.** The `version` in `plugin.json` is the signal a teammate's update acts on.

   ```json title="plugins/acme-api-style/.claude-plugin/plugin.json"
   {
     "name": "acme-api-style",
     "version": "1.0.0",
     "description": "Acme REST conventions: error envelope, pagination, versioning",
     "author": { "name": "Acme Platform Team" }
   }
   ```

   ```markdown title="plugins/acme-api-style/skills/api-conventions/SKILL.md"
   ---
   name: api-conventions
   description: Use when adding or changing an HTTP endpoint. Applies Acme's error envelope, cursor pagination and /v{n}/ versioning rules.
   ---

   # Acme API conventions

   - Errors return {"error": {"code", "message", "request_id"}} with a 4xx or 5xx status.
   - List endpoints paginate with an opaque `cursor` and `limit` (max 100), never page numbers.
   - Breaking changes go in a new /v{n}/ prefix; never change a published response shape.
   ```

   `acme-release` follows the same shape with a `release-check` skill.

   The alternative is to omit `version` everywhere. Claude Code then versions the plugin by the 12-character commit SHA, and every commit to the marketplace becomes a release (observed on 2.1.283: `updated from 9235eac629d9 to b7aa77f81abc`). That suits a marketplace where every merge should ship at once, but `validate --strict` then fails with `No version specified`, and teammates lose a readable number to report back. This page keeps explicit versions and enforces the bump in CI.

5. **Name an owner per plugin.** A `CODEOWNERS` file makes the sign-off explicit.

   ```text title=".github/CODEOWNERS"
   /plugins/acme-release/     @acme/release-eng
   /plugins/acme-api-style/   @acme/api-guild
   /.claude-plugin/           @acme/platform
   ```

6. **Push it to a private repository**, for example `acme/acme-plugins` on GitHub. GitLab and other hosts work through their full `https://…git` URL.

**Copy-paste prompt: scaffold the marketplace repository**

```text
Create a Claude Code plugin marketplace in this empty repository. Catalogue: .claude-plugin/marketplace.json with name "acme-plugins", a top-level description, owner.name "Acme Platform Team", and two entries whose source is ./plugins/<name> and which carry no version field. Plugin 1: plugins/acme-release with .claude-plugin/plugin.json at version 1.0.0 and a skill skills/release-check/SKILL.md that, before a release, lists user-visible changes missing from CHANGELOG.md, migrations without a rollback note, and new feature flags with their defaults, and never tags. Plugin 2: plugins/acme-api-style at 1.0.0 with a skill skills/api-conventions/SKILL.md for our error envelope, cursor pagination (limit max 100) and /v{n}/ versioning. Write each skill description so it names the trigger phrases. Then run `claude plugin validate --strict .` and `claude plugin validate --strict` on each plugin directory and paste the outputs. Do not install anything.
```

## Validate the marketplace in CI before anyone installs from it

`claude plugin validate --strict` is necessary but not sufficient. In the 2.1.283 test it passed a catalogue whose `source` pointed at a directory that did not exist, and it passed a reserved name. Both fail only when someone installs. The gate below therefore validates, then installs every plugin into a throwaway home directory with both CLIs, then enforces the version rule.

```bash title="scripts/check-marketplace.sh"
#!/usr/bin/env bash
# Usage: scripts/check-marketplace.sh <base-ref>   (CI passes origin/main)
set -euo pipefail
base="${1:-origin/main}"
market=$(jq -r .name .claude-plugin/marketplace.json)
export HOME="$(mktemp -d)" CODEX_HOME="$(mktemp -d)"   # scratch homes: nothing leaks in

# 1. Schema: --strict fails on warnings the runtime would tolerate
claude plugin validate --strict .
for p in plugins/*/; do claude plugin validate --strict "$p"; done

# 2. Install smoke test: catches reserved names and missing source directories,
#    which validate passes
claude plugin marketplace add ./
for name in $(jq -r '.plugins[].name' .claude-plugin/marketplace.json); do
  claude plugin install "$name@$market"
  claude plugin details "$name" | grep 'Always-on'
done
codex plugin marketplace add ./
for name in $(jq -r '.plugins[].name' .claude-plugin/marketplace.json); do
  codex plugin add "$name@$market"
done

# 3. Release rule: a changed plugin must carry a new version, or nobody receives it
for p in plugins/*/; do
  git diff --quiet "$base" -- "$p" && continue
  old=$(git show "$base:${p}.claude-plugin/plugin.json" 2>/dev/null | jq -r .version || echo new)
  new=$(jq -r .version "${p}.claude-plugin/plugin.json")
  if [ "$old" = "$new" ]; then
    echo "::error::${p} changed but .claude-plugin/plugin.json still says $new"
    exit 1
  fi
  # ...and the new version must sort above the old one (catches 1.0.0 -> 1.0)
  if [ "$old" != new ] && [ "$(printf '%s\n%s\n' "$old" "$new" | sort -V | tail -1)" != "$new" ]; then
    echo "::error::${p} version went from $old to $new; it must go up"
    exit 1
  fi
done
echo "marketplace OK"
```

Run locally, the script printed `Always-on: ~49 tok` for `acme-release` (your figure depends on the skill description you write) and `~68 tok` for `acme-api-style` and ended with `marketplace OK`. Codex prints a warning that it will not create helper binaries under a temporary directory; it is harmless in this job. With a mistyped `source` it stopped at `Source path does not exist`, and with a skill edited but not bumped it stopped at the `::error::` line. The second check also rejects a version that goes down or loses a component, such as `1.0.0` to `1.0`. The version-bump step is our own rule, not a vendor feature.

The workflow holds no secrets, because validation and installation make no model call:

```yaml title=".github/workflows/plugin-marketplace.yml"
name: plugin-marketplace
on:
  pull_request:
    paths: ['plugins/**', '.claude-plugin/**', '.agents/**', '.cursor-plugin/**', 'scripts/**', '.github/**']
permissions:
  contents: read
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
          persist-credentials: false
      - uses: actions/setup-node@v7
        with:
          node-version: 22
      - run: npm install -g @anthropic-ai/claude-code@2.1.283 @openai/codex@0.157.1
      - run: bash scripts/check-marketplace.sh "origin/$BASE_REF"
        env:
          BASE_REF: ${{ github.base_ref }}
```

Keep `claude plugin eval`, which calls a model and needs an API key, out of this `pull_request` job. Run it on the default branch or locally; [building plugins](/en/ecosystem/plugins/building-plugins/) shows how.

**Copy-paste prompt: review a marketplace pull request**

```text
Review this pull request against main for the acme-plugins marketplace. For each plugin under plugins/ that changed, report: the old and new version in .claude-plugin/plugin.json and whether the change is a patch, minor or major by our rule (skill wording = patch, new skill or command = minor, removed or renamed skill = major); every hook, MCP server or script added, with the command it runs and every environment variable it reads; any literal credential or token-bearing URL; and the always-on token figure CI printed for it, flagging any increase above 300 tokens. Check that no marketplace entry carries a version field and that the catalogue name is still acme-plugins. Output one table per plugin. Do not approve or merge.
```

## Release a plugin version and get it to teammates

Merging does not update anyone. Observed on 2.1.283: after a skill was edited without a version change, `claude plugin marketplace update` succeeded and `claude plugin update acme-release@acme-plugins` answered `acme-release is already at the latest version (1.0.0)`; the cached skill still held the old text. After the bump to `1.0.1`, the same command printed `Plugin "acme-release" updated from 1.0.0 to 1.0.1 for scope user. Restart to apply changes.` and wrote a new `1.0.1` cache directory beside the old one.

1. **Tag the merged release.** From a clean checkout of `main`, the tag command checks that `plugin.json` and the catalogue agree before it writes `<name>--v<version>`:

   ```bash
   claude plugin tag --dry-run plugins/acme-release
   # Tag:     acme-release--v1.0.1
   # √ Dry run — would create tag acme-release--v1.0.1 at HEAD in …
   claude plugin tag --push plugins/acme-release
   ```

   When a catalogue entry still carried `"version": "1.0.0"`, the command refused: `Version mismatch: plugin.json says "1.0.1" but .claude-plugin/marketplace.json plugins[0].version says "1.0.0".`

2. **Announce the release** with the tag, the one-line change and the update commands below. Teammates update per tool:

   **Claude Code**

   ```bash
   claude plugin marketplace update acme-plugins
   claude plugin update acme-release@acme-plugins
   claude plugin list    # Version: 1.0.1
   ```

   Restart the session afterwards. Third-party marketplaces do not auto-update until a user or an admin turns it on (Claude Code 2.1.283 default; see the marketplaces reference), which is why the managed settings below set `autoUpdate`.

   **Codex**

   ```bash
   codex plugin marketplace upgrade acme-plugins
   codex plugin add acme-release@acme-plugins
   codex plugin list    # acme-release@acme-plugins  installed, enabled  1.0.1
   ```

   Codex has no `codex plugin update` and no `marketplace update` (on 0.162.1, checked 2026-10-12, `codex plugin --help` lists `add`, `list`, `marketplace` and `remove`, and `codex plugin marketplace --help` lists `add`, `list`, `upgrade` and `remove`); re-running `add` installs the new version into its own cache directory (observed on 0.157.1). `upgrade` refreshes Git sources only: on a marketplace added from a local path it fails with `marketplace 'acme-plugins' is not configured as a Git marketplace`.

   **Cursor**

   Cursor distributes a team marketplace from the dashboard rather than through a per-member command; how a new version reaches members is not verified here (cursor.com was unreachable on 2026-09-26). Check it in your dashboard after the first release.

3. **Confirm the rollout.** Ask the team to paste `claude plugin list` (or `codex plugin list`) output into the release thread, or check one machine per team. The release is done when the version you tagged is the version people run.

To undo a bad release, roll forward: revert the change on `main`, bump to a new version such as `1.0.2`, and tag again. A new version number is the only thing an update acts on, so a revert that keeps `1.0.1` reaches nobody.

## Roll the marketplace out to the whole team

Pick the route that matches how much control you need. Each one writes different settings, and none of them makes a private clone work without git credentials.

**Claude Code**

**Private-repository access comes first.** Claude Code clones with the machine's git credentials and never prompts. For HTTPS on GitHub, run `gh auth login` and then `gh auth setup-git`. A `GITHUB_TOKEN` in the environment does nothing without a credential helper, and `marketplace.json` has no token field (checked on Claude Code 2.1.283). Set `CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1` to skip the SSH attempt. Test access with plain git before blaming the plugin: `git ls-remote https://github.com/acme/acme-plugins.git`.

| Route | Command or file | What it does |
| ----- | --------------- | ------------ |
| Per person | `claude plugin marketplace add acme/acme-plugins`, then `claude plugin install acme-api-style@acme-plugins` | Adds and installs at user scope |
| Per repository | `claude plugin marketplace add acme/acme-plugins --scope project` and `claude plugin install acme-api-style@acme-plugins --scope project`, then commit `.claude/settings.json` | Declares the marketplace in `extraKnownMarketplaces` and enables the plugin in `enabledPlugins` |
| Fleet-wide | Managed settings (server-managed, MDM or `managed-settings.json`) | Allowlists marketplaces, adds yours with auto-update, enables plugins |
| claude.ai Team or Enterprise | **Organization settings → Plugins & skills** | Syncs the marketplace through the org's GitHub or GitLab connection; the repository must be private or internal, and no plugin may have a top-level `bin/` directory |

The per-repository route writes both keys, but **`enabledPlugins` enables a plugin; it does not install it.** The marketplace registers only after each teammate trusts the folder, and a plugin with an external source still needs one `claude plugin install … --scope project` per machine. Put that command in the repository's README, and have each teammate confirm the install with `claude plugin list`.

The fleet-wide route, adapted from Anthropic's documented example (which also sets `disableSideloadFlags`). Keep `{ "source": "skills-dir" }` in the allowlist: without it, strict mode also blocks the personal plugins that `claude plugin init` creates (`<name>@skills-dir`).

```json title="managed-settings.json"
{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "anthropics/claude-plugins-official" },
    { "source": "github", "repo": "acme/*" },
    { "source": "skills-dir" }
  ],
  "extraKnownMarketplaces": {
    "acme-plugins": { "source": { "source": "github", "repo": "acme/acme-plugins" }, "autoUpdate": true }
  },
  "enabledPlugins": {
    "acme-release@acme-plugins": true,
    "acme-api-style@acme-plugins": true
  }
}
```

`strictKnownMarketplaces` makes these the only marketplaces anyone can add. [One policy for every coding agent](/en/org/managed-policy/) covers how to distribute and audit that file.

Newer `claude plugin` options (Claude Code 2.1.296 help, checked 2026-10-12) shorten the per-person route. `--marketplace SOURCE` installs a plugin from a marketplace that is not added yet, adding it first in user settings under the same checks as `claude plugin marketplace add`, for example `claude plugin install acme-api-style --marketplace acme/acme-plugins`. It arrived in v2.1.292, so both release channels have it on 2026-10-17 (`stable` is 2.1.292). `--config KEY=VALUE` sets an option that the plugin's manifest declares, and `claude plugin configure acme-api-style` lists which options are still unset; both arrived in v2.1.285, so both channels have them.

**Codex**

Codex 0.157.1 reads `.claude-plugin/marketplace.json` when it is the repository's only catalogue, so the example marketplace needs no Codex file. Observed:

```bash
codex plugin marketplace add acme/acme-plugins --ref main
codex plugin add acme-api-style@acme-plugins
codex plugin list
# Marketplace `acme-plugins`
# …/.claude-plugin/marketplace.json
# acme-api-style@acme-plugins  installed, enabled  1.0.0
```

Codex records the result in `config.toml` as `[marketplaces.acme-plugins]` and `[plugins."acme-api-style@acme-plugins"] enabled = true`. It copies each plugin's `skills/` into `plugins/cache/acme-plugins/<plugin>/<version>/`; open a Codex session and run `/skills` to confirm the skills load before you announce support.

Add a Codex catalogue only when you need Codex-specific fields such as `policy`. When `.agents/plugins/marketplace.json` exists, Codex uses it instead of the Claude file, so the two lists must stay identical:

```json title=".agents/plugins/marketplace.json"
{
  "name": "acme-plugins",
  "interface": { "displayName": "Acme engineering" },
  "plugins": [
    {
      "name": "acme-release",
      "source": { "source": "local", "path": "./plugins/acme-release" },
      "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" },
      "category": "Developer Tools"
    },
    {
      "name": "acme-api-style",
      "source": { "source": "local", "path": "./plugins/acme-api-style" },
      "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" },
      "category": "Developer Tools"
    }
  ]
}
```

If you add it, add one line to the CI script: `diff <(jq -r '.plugins[].name' .claude-plugin/marketplace.json | sort) <(jq -r '.plugins[].name' .agents/plugins/marketplace.json | sort)`.

**Cursor**

Cursor needs its own catalogue at `.cursor-plugin/marketplace.json`, plus a `.cursor-plugin/plugin.json` in each plugin directory. Cursor's plugins documentation (read 2026-10-12) names two formats, Agent Plugins with a `plugin.json` at the plugin root and Cursor Plugins with a `.cursor-plugin/plugin.json`; the files below use the second. The skills in `skills/` are reused as they are. The files below pass the JSON schemas and the `scripts/validate-plugins.mjs` checker in Cursor's first-party `cursor/plugins` repository (commit of 2026-09-25):

```json title=".cursor-plugin/marketplace.json"
{
  "name": "acme-plugins",
  "owner": { "name": "Acme Platform Team", "email": "platform@acme.example" },
  "metadata": { "description": "Internal plugins for Acme engineering" },
  "plugins": [
    { "name": "acme-release", "source": "plugins/acme-release", "description": "Release checklist skill: changelog, migrations, feature flags" },
    { "name": "acme-api-style", "source": "plugins/acme-api-style", "description": "Acme REST conventions: error envelope, pagination, versioning" }
  ]
}
```

```json title="plugins/acme-api-style/.cursor-plugin/plugin.json"
{
  "name": "acme-api-style",
  "version": "1.0.0",
  "description": "Acme REST conventions: error envelope, pagination, versioning",
  "author": { "name": "Acme Platform Team" },
  "skills": "./skills/"
}
```

Do not copy the Claude catalogue across. Cursor's schema forbids unknown top-level keys, so the Claude file's top-level `description` fails with `must NOT have additional properties`; Cursor expects it under `metadata`. To gate it in CI, copy `schemas/` and `scripts/validate-plugins.mjs` from `cursor/plugins`, install `ajv` and `ajv-formats`, and run `node scripts/validate-plugins.mjs`. It also fails on a missing `source` directory. Keep both `plugin.json` files of a plugin at the same version; the CI version rule above checks only the Claude one, so add the Cursor path to it if Cursor users matter to you.

The import is **secondary evidence** (Cursor's documentation was unreachable on 2026-09-26): on a Teams or Enterprise plan, an admin opens **Dashboard → Settings → Plugins → Team Marketplaces → Import**, pastes the repository URL, chooses access groups, and marks each plugin **Required** or **Optional**. Members install with `/add-plugin` in Agent chat. A community template's README says the Teams plan gets one team marketplace; confirm the limit in your dashboard.

Headless agents in CI or containers need the plugins too. Build a seed directory once with `CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin install …`, run the agent with `CLAUDE_CODE_PLUGIN_SEED_DIR=/opt/claude-seed`, and set `CLAUDE_CODE_SYNC_PLUGIN_INSTALL=1` so a `-p` run waits for installs. [Headless agents in CI](/en/ecosystem/agent-tools/headless-agents-ci/) covers the rest of that setup.

**Copy-paste prompt: onboard a repository onto the team marketplace**

```text
Wire this repository to the acme-plugins marketplace (GitHub repo acme/acme-plugins). Run `claude plugin marketplace add acme/acme-plugins --scope project` and `claude plugin install acme-api-style@acme-plugins --scope project`, then show me the resulting .claude/settings.json. Add a "Team plugins" section to README.md that tells a new teammate to run `gh auth login`, `gh auth setup-git`, `git ls-remote https://github.com/acme/acme-plugins.git` and the same install command, and to confirm with `claude plugin list` that acme-api-style shows the current version. Do not add any token or credential to any file. Stop before committing.
```

## How big public plugin marketplaces are, and what a team plugin costs in context

As of 2026-09-26, Anthropic's `claude-plugins-official` catalogue listed 314 entries, Codex's `openai-curated` 65 and Cursor's `cursor-plugins` 94 (counted from each repository's marketplace file). The largest cross-agent third-party marketplace in our research, `wshobson/agents` (marketplace name `claude-code-workflows`), shipped 94 plugins with both a Claude and a Codex catalogue and had 39,978 GitHub stars (GitHub API, 2026-09-26). Private marketplaces have no public count.

The two example plugins cost 49 and 68 always-on tokens per session (`claude plugin details`, 2.1.283), about 117 together. Skill-only plugins stay cheap; a plugin that bundles many skills or an MCP server costs more, and on 2.1.283 the figure from `claude plugin details` may not include MCP tool schemas, so check `/context` in a session as well. Print the always-on figure in CI, as the script does, and treat a jump in review as a design question.

**Traps in a private marketplace**

- `validate --strict` passing does not prove the marketplace installs: reserved names and missing `source` directories fail only at `marketplace add` or `install`. Keep the install smoke test in CI.
- While `plugin.json` carries a `version`, a pushed commit without a new one reaches nobody. `plugin.json` wins over a catalogue `version`, so keep the version in one place.
- `enabledPlugins` in `.claude/settings.json` enables; it does not install.
- The Claude and Cursor catalogues are not interchangeable: Cursor rejects a top-level `description`.
- `GITHUB_TOKEN` alone does not authenticate a private clone. Use a credential helper.
- The spellings differ: `claude plugin install` and `claude plugin marketplace update`, but `codex plugin add` and `codex plugin marketplace upgrade` (checked on Claude Code 2.1.283 and codex-cli 0.157.1).
- Never just edit a published plugin or marketplace `name`: every install id and every namespaced skill (`/acme-release:release-check`) is built from it. A plugin rename goes through the catalogue's `renames` map.

## What breaks in a team marketplace, and how to recover

- **Teammates still run the old skill after a merge.** The version did not change, or they never updated. Bump `version`, tag, and send the update commands; check with `claude plugin list`. Add the version-bump step to CI so it cannot happen twice.
- **`marketplace add` fails with "reserved for official Anthropic marketplaces".** Rename the catalogue before anyone installs it. After people have installed, a rename changes every install id, so treat it as a migration: announce it, and have everyone remove the old marketplace and add the new one.
- **You have to rename a plugin inside the marketplace.** Do not just change its `name`. Add the old name to the catalogue's `renames` map (`{ "old-name": "new-name" }`, or `null` for a removed plugin). After `claude plugin marketplace update`, Claude Code 2.1.283 moves each teammate's `enabledPlugins` entry to the new name, and `claude plugin list` marks the old install "Renamed to …". It does not resolve the old id: `install` and `update` by the old name fail with "not found", so teammates run `claude plugin install <new-name>@acme-plugins`. Keep old entries in the map.
- **Install fails with `Source path does not exist`.** A plugin directory was moved or renamed without its `source`. Fix the entry; the CI install step catches the next one.
- **The marketplace never appears on a teammate's machine.** They have not trusted the folder, or their git credentials cannot clone the private repository. Run `git ls-remote` on the repository URL; if it prompts or fails, fix `gh auth setup-git` (or your host's credential helper) first.
- **A committed plugin is enabled but missing.** `enabledPlugins` does not install. Run `claude plugin install <name>@acme-plugins --scope project` on that machine.
- **Codex installs a different plugin list from Claude Code.** A `.agents/plugins/marketplace.json` exists and Codex reads it instead. Make the two lists identical, and add the `diff` line to CI.
- **`codex plugin marketplace upgrade` fails with "not configured as a Git marketplace".** The marketplace was added from a local path. Remove it and add it again from `acme/acme-plugins`.
- **Cursor's validator reports `must NOT have additional properties`.** The Cursor catalogue was copied from the Claude one. Move `description` under `metadata` and drop any other Claude-only key.
- **`claude plugin tag` refuses with a version mismatch.** A catalogue entry carries its own `version`. Delete that field and tag again.

## Where to go next with plugins

- [Build a plugin](/en/ecosystem/plugins/building-plugins/) — Manifests, a skill, a hook and an MCP server in one plugin, with eval and hook tests.
- [Plugins and marketplaces overview](/en/ecosystem/plugins/) — Install, measure and allowlist plugins in each agent.
- [Marketplaces and registries](/en/ecosystem/plugins/marketplaces-registries/) — Where plugins, skills and MCP servers come from, and the intake review for outside ones.
- [One policy for every coding agent](/en/org/managed-policy/) — Distribute managed settings, allowed marketplaces and plugins across vendors.
- [Skill supply-chain security](/en/ecosystem/skills/skill-security/) — What to check before a plugin's instructions and scripts reach your team.
