What a private Claude Code plugin marketplace is
A private Claude Code plugin marketplace is a catalog of your own plugins that only your team can reach. Technically it is a directory or repository with a .claude-plugin/marketplace.json file that lists each plugin and where to fetch it. You push it to a git host your company controls, people register it once, and they install your internal skills, commands, hooks and MCP servers by name and keep receiving your updates.
This is the owner's side of the job. If you are the admin deciding which marketplaces every machine must use or may use, that is managed settings, and how to manage Claude Code plugins for your organization covers it. Most companies need both: one person runs the catalog, and an admin points every machine at it.
Build the marketplace and test it locally
Build it on your own machine first and install from it yourself. That is the same loop your users go through once it is hosted, so every error you hit here is one they will not.
- Create a folder, for example my-marketplace, with a .claude-plugin folder inside it and a plugins folder next to that. Copy each plugin into plugins.
- Write .claude-plugin/marketplace.json. It needs a top-level name, an owner object with a name, and a plugins array. Each entry needs a name and a source, plus a description people see when they browse.
- Run claude plugin validate ./my-marketplace. It checks JSON syntax, required fields, naming rules and each relative-path plugin's own plugin.json. The last line should read Validation passed.
- Register it with claude plugin marketplace add ./my-marketplace, or /plugin marketplace add ./my-marketplace inside a session in the desktop app or the terminal.
- Install a plugin with claude plugin install plugin-name@marketplace-name. The install id is always the entry name, an @, and the marketplace's top-level name.
- Confirm with claude plugin list, then start a session and run one of the plugin's skills.
While you test from a local folder, Claude Code reads the plugin files in place, so an edit takes effect at the next session start or when you run /reload-plugins. People who install from the hosted copy get a cached copy instead, which is why versioning matters later.
The two mistakes behind most failed installs
Most failed installs from a new marketplace come from two things: a relative path written from the wrong folder, and an entry name that does not match the plugin's own name.
What breaks and where you find out
| Mistake | What you see | Fix |
|---|---|---|
| A source path containing .. | claude plugin validate rejects the entry with a message starting Path contains ".." | Write relative paths from the marketplace root, the folder that contains .claude-plugin, such as ./plugins/formatter |
| A source path to a folder that does not exist | Validate passes, then install fails with Source path does not exist | Install from the marketplace yourself before you share it |
| Entry name differs from the name in plugin.json | Plugin "name" not found in marketplace when someone installs by the plugin.json name | Keep the two names identical |
| A marketplace name reserved for official marketplaces, such as claude-plugins-official | Validate passes, then adding the marketplace is refused as reserved | Pick a top-level name other authors are unlikely to use, such as your company name plus plugins |
My rule: validate after every edit, and treat a passing validate as half the test. Validate only reads files inside the marketplace folder. Remote sources, wrong repo names and missing folders only show up when you actually install.
Pick where to host it
For a company, host it in a git repository only the company can read. Claude Code accepts four kinds of host, and each one changes what people need on their machine.
Hosting options for a private marketplace
| Host | What people add | What they need |
|---|---|---|
| GitHub | /plugin marketplace add your-org/your-marketplace | git, plus read access to the private repo |
| GitLab, Bitbucket, GitHub Enterprise Server or another git host | The full repo URL, because owner/repo shorthand always means github.com | git, plus access to that host from their machine |
| A hosted marketplace.json URL | The https URL of the file | HTTPS access only. Relative-path entries fail here, so every entry needs its own fetchable source |
| A shared network folder | The folder path | Read access to the path. Edits show up at the next session without a version bump |
Two details save a support thread later. Keep plugin files out of Git LFS, because Claude Code's clone never downloads LFS content and those files arrive as pointer files. And to pre-register the marketplace for everyone in one repository, run claude plugin marketplace add your-org/your-marketplace --scope project there once and commit the .claude/settings.json it writes. Each teammate gets it when they trust the folder. If your host is GHES, Claude Code with GitHub Enterprise Server covers what each surface needs.
Give people access without putting a token in the file
Claude Code has no git token of its own, and marketplace.json has no field for one. When someone adds, installs from or updates your marketplace, Claude Code runs git on their machine with prompts turned off and uses whatever credentials that machine already holds. If git would have to ask for a password, the step fails.
- For GitHub owner/repo, Claude Code tries SSH first and falls back to HTTPS. People with no GitHub SSH key should set CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1, because installs from /plugin inside a session and plugin updates do not fall back on their own.
- SSH needs a key that works without a passphrase prompt, for example one loaded in ssh-agent, and the host already in known_hosts.
- HTTPS needs a credential the git credential helper already stores. On GitHub, gh auth login followed by gh auth setup-git stores one.
- Setting GITHUB_TOKEN in the environment does not authenticate anything by itself. It only takes effect through a credential helper that reads it, such as the gh helper.
On a Team or Enterprise plan there is a cleaner route: distribute the marketplace through Organization settings, Plugins and skills, on claude.ai. That sync reads the repository through your organization's GitHub or GitLab connection, so nobody's personal git credentials are involved. It is stricter: on github.com and gitlab.com the repository must be private or internal, only some source types are accepted, and a plugin with a top-level bin folder is rejected. Keep scripts in a scripts folder instead.
Ship updates people actually receive
Background auto-update is off for your marketplace by default, and marketplace.json has no field to turn it on. Each person turns it on under Marketplaces in /plugin, or an admin sets autoUpdate to true on your marketplace's extraKnownMarketplaces entry in managed settings. Without it, people get changes only when they run /plugin marketplace update or claude plugin update.
Even with auto-update on, someone gets a new copy of a plugin only when its version changes. Pick one of two policies and stick to it:
- Bump version on every release. If you set version 1.0.0 and push new commits without changing it, nobody receives them.
- Omit version from both plugin.json and the marketplace entry. People then track your commits.
- Never set version in both places. Claude Code uses the plugin.json value without warning, and validate reports the mismatch.
For a stable track and an early-access track, run two marketplaces with different top-level names whose entries point at different branches of the same plugin repo, using the ref field on a github source. An admin can then give each group the matching marketplace. Before a plugin goes on the stable track, run it through Claude Code plugin evals so you know it beats having no plugin at all.
Rename or retire a plugin without breaking installs
A plugin's name is its identifier in everyone's enabledPlugins setting and in every install command, so changing it breaks existing installs. If you only want a friendlier label, set displayName in plugin.json and leave name alone.
- When you must rename, add a top-level renames map to marketplace.json, mapping the old name to the new one. Claude Code rewrites the old key in user, project and local settings and shows a one-time notice.
- When you remove a plugin, map its old name to null. Add forceRemoveDeletedPlugins set to true if you want it uninstalled from people's machines at their next session start.
- Treat renames as append-only history. For a second rename, add a new entry instead of editing the first, and run claude plugin validate to catch a chain that does not resolve.
- Managed settings are the exception. Claude Code cannot rewrite them, so the notice keeps appearing until the admin updates enabledPlugins there.
There is no deprecated state and no per-audience entry. Everyone who adds the marketplace sees the whole catalog, so if two departments need different plugins, host two marketplaces. Once the catalog is live, plugin recommendations let Claude Code suggest the right plugin when someone's project matches it.
Short, practical drops on skills, MCP, agents, prompts, and more. No spam, unsubscribe anytime.
Frequently asked questions
How do I make a private Claude Code plugin marketplace?
Create a folder with .claude-plugin/marketplace.json listing a name, an owner and your plugins, run claude plugin validate on it, install from it locally, then push it to a private git repository. People add it with /plugin marketplace add and the repo path or URL.
How do people authenticate to a private plugin marketplace?
With the git credentials already on their machine. Claude Code has no token of its own and marketplace.json has no token field. SSH needs a key loaded without a passphrase prompt, and HTTPS needs a stored credential, for example from gh auth login followed by gh auth setup-git.
Why are my teammates not getting plugin updates?
Either auto-update is off, which is the default until a user or admin turns it on, or the plugin's version did not change. If you set a version, bump it on every release, or remove version from both plugin.json and the marketplace entry so people track commits.
Can I host a Claude Code plugin marketplace on GitLab or GitHub Enterprise Server?
Yes. Give people the full repository URL, because the owner/repo shorthand always points at github.com, and make sure their machines have git access to that host.
How do I rename a plugin in my marketplace?
Add a top-level renames map in marketplace.json from the old name to the new one. Claude Code migrates existing installs and rewrites the old settings key. Map a removed plugin's name to null.
Can I distribute a marketplace without each person using git?
On Team and Enterprise plans, yes: sync it through Organization settings, Plugins and skills, on claude.ai, which reads the repository through your organization's GitHub or GitLab connection. You can also serve a marketplace.json URL whose entries use archive sources, or use a shared network folder.
Last reviewed by David Iya on November 22, 2026


