Claude Code Plugin Marketplace: Build One for Your Team

You’ve built a few plugins and now want every teammate, every repo and every new hire to get them without copying folders. A plugin marketplace is how: one git repository with a catalog file, registered once in your project settings. This guide builds one from scratch and covers the parts that trip teams up: private repos, updates and naming.

Checked against the official docs on creating and hosting marketplaces and the marketplace reference, as of October 2026.

How the pieces fit

Piece	What it is	Where
Plugin	Skills, agents, hooks, MCP servers in one folder	plugins/<name>/
Plugin manifest	Name, version, metadata (optional file)	plugins/<name>/.claude-plugin/plugin.json
Marketplace	Catalog listing plugins and their sources	.claude-plugin/marketplace.json at repo root
Team registration	Tells Claude Code about the marketplace	.claude/settings.json in each project

Step 1: Lay out the repository

acme-claude-plugins/
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    ├── review-kit/
    │   ├── .claude-plugin/plugin.json
    │   ├── skills/review-pr/SKILL.md
    │   └── agents/security-reviewer.md
    └── release-kit/
        ├── .claude-plugin/plugin.json
        ├── skills/release/SKILL.md
        └── hooks/hooks.json

Inside each plugin, skills/, agents/, commands/ and hooks/ sit at the plugin root, not inside .claude-plugin/. That’s the most common layout mistake. Skills themselves follow the Agent Skills standard.

Step 2: Write marketplace.json

{
  "name": "acme-tools",
  "description": "Claude Code plugins for Acme engineering",
  "owner": {
    "name": "Acme Platform Team",
    "email": "platform@example.com"
  },
  "plugins": [
    {
      "name": "review-kit",
      "source": "./plugins/review-kit",
      "description": "PR review skill and a security reviewer subagent",
      "category": "quality"
    },
    {
      "name": "release-kit",
      "source": "./plugins/release-kit",
      "description": "Release checklist skill and changelog hook"
    }
  ]
}

Rules that matter:

• Required: name, owner.name and plugins. Each plugin entry needs name and source.
• Marketplace name: letters, digits, ., _ and -, starting with a letter or digit. Users install with plugin@marketplace, so the name comes from this file, not the repo name. Keep it short.
• Relative sources start with ./, resolve from the marketplace root (the folder containing .claude-plugin/), and can’t use ...
• Plugin names in entries should match the name in each plugin.json.

Plugin sources beyond relative paths

A marketplace doesn’t have to contain the plugins. Entries can point elsewhere:

Source	Shape	Use when
Relative path	"./plugins/x"	Plugin lives in the marketplace repo
GitHub	{ "source": "github", "repo": "org/repo", "ref": "v1.2.0" }	Plugin has its own repo
Git URL	{ "source": "url", "url": "https://git.example.com/x.git" }	GitLab, Bitbucket, self-hosted
Git subdirectory	{ "source": "git-subdir", "url": "...", "path": "plugins/x" }	Plugin inside a monorepo
npm	{ "source": "npm", "package": "@acme/x" }	Plugin published to a registry

Pin with ref (tag or branch) or a full 40-character sha when you need reproducible installs.

Step 3: Validate before you push

claude plugin validate .
claude plugin validate . --strict

Exit code 0 means pass, 1 means fail, so it drops straight into CI. Add it to a GitHub Actions job on the marketplace repo; our Claude Code GitHub Actions guide shows the workflow basics.

Test locally before publishing:

claude plugin marketplace add ./acme-claude-plugins
claude plugin install review-kit@acme-tools

Step 4: Register it for the team

Teammates can add it by hand with /plugin marketplace add acme/acme-claude-plugins. Better: commit it to each project so it’s offered automatically. In the project directory:

claude plugin marketplace add acme/acme-claude-plugins --scope project

That writes to .claude/settings.json. Add the plugins you want enabled:

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "github", "repo": "acme/acme-claude-plugins" },
      "autoUpdate": true
    }
  },
  "enabledPlugins": {
    "review-kit@acme-tools": true,
    "release-kit@acme-tools": true
  }
}

Commit it. When a teammate opens the project and trusts the folder, Claude Code offers the marketplace and plugins. Settings in an untrusted folder are ignored, which is the right default for anything that can run hooks.

Ways to add a marketplace

Input	Treated as
owner/repo, owner/repo#v1.2.0	GitHub repo (optionally pinned)
git@host:org/repo.git	Git over SSH
https://host/org/repo.git	Git over HTTPS
Any other https:// URL	A hosted marketplace.json file
./path	Local directory

Private repositories

Claude Code has no token of its own; it runs git with your existing credentials. For owner/repo sources it tries SSH first, then HTTPS (set CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1 to skip SSH).

Interactive installs work for anyone who can git clone the repo. Background auto-updates are stricter: the docs note that setting GITHUB_TOKEN alone is not enough; the credentials must come from a credential helper. On GitHub:

gh auth login
gh auth setup-git

Never put tokens in marketplace.json or committed settings.

Shipping updates

• Bump version in plugin.json for each release. Users only receive an update when the version changes. If you omit version entirely, every commit counts as an update.
• Don’t set version in both plugin.json and the marketplace entry; plugin.json wins and the mismatch confuses people.
• Auto-update is on by default only for Anthropic’s official marketplace. For yours, set "autoUpdate": true as above, or users enable it in /plugin under Marketplaces.
• Manual refresh: /plugin marketplace update acme-tools or claude plugin marketplace update.
• Auto-update runs after the first message of a session, with a random delay of up to 10 minutes, so don’t expect instant rollout.

Plugins can change files on users’ machines after they reviewed them, so treat merges to the marketplace repo like production deploys: code review, CI validation, a changelog.

Locking things down (admins)

Organisations can control marketplaces through managed settings:

• strictKnownMarketplaces: an allowlist of marketplace sources users may add. It doesn’t register anything by itself; pair it with extraKnownMarketplaces. Patterns such as "repo": "acme/*" are supported in recent versions.
• blockedMarketplaces: deny specific sources.
• disableSideloadFlags: stop users loading local plugins with --plugin-dir.

If you use strictKnownMarketplaces, the docs warn you to keep { "source": "skills-dir" } in the list or skills-directory plugins stop loading.

Reserved names

You can’t use names that belong to Anthropic or look like them, including claude-plugins-official, claude-code-marketplace, claude-code-plugins, anthropic-plugins, agent-skills, anthropic-agent-skills and claude-community, plus anything starting with claudeai-. Validation can pass with these names, but adding the marketplace fails. Pick an org-prefixed name like acme-tools.

Troubleshooting

Symptom	Likely cause
Plugin installs but skills are missing	skills/ placed inside .claude-plugin/
“Plugin not found”	Entry name differs from what users type after @, or wrong marketplace name
Teammates never get updates	version not bumped, or auto-update off for your marketplace
Background update fails on private repo	Credentials only in GITHUB_TOKEN, not a credential helper
Settings ignored	Project folder not trusted

What to put in a team marketplace

Start small: one review plugin, one release plugin, one plugin with your shared MCP servers (see best MCP servers). Ready-made community skills from the best Claude Code skills can be wrapped and pinned so everyone runs the version you reviewed.

Your marketplace is your Claude kit

A team marketplace is a Claude kit with distribution built in. If you’d rather start from a packaged kit than build every plugin yourself, our Agentkit.best vs DIY comparison weighs the trade-offs.