Claude Code Plugins for Teams: Share, Require, Lock Down

To share Claude Code plugins with a team, put them in a marketplace repository (a repo with .claude-plugin/marketplace.json), then register that marketplace where your team will pick it up. For one repository, run claude plugin marketplace add your-org/your-marketplace --scope project and commit the .claude/settings.json it writes. For a whole company, put the same two keys, extraKnownMarketplaces and enabledPlugins, in managed settings and add a strictKnownMarketplaces allowlist so people cannot add marketplaces you have not approved.

Last updated: October 9, 2026. Commands and settings keys checked against the Claude Code plugin docs and changelog on this date. The project-scope steps below were run on Claude Code v2.1.295 against a local test marketplace.

The timing is not random. Claude Code v2.1.292 (October 6) added --marketplace to claude plugin install, which turns team onboarding into one shell command, and v2.1.295 now warns when claude plugin install, enable, disable or marketplace add writes to a settings file that does not load. Plugins have also gotten more powerful: since mods shipped, a plugin can run JavaScript inside Claude Code itself. A team that lets every developer add any marketplace they find can end up running unreviewed code with everyone's credentials. This guide is the setup that fixes that, from smallest to largest.

If you only want to install a plugin for yourself, the Claude Code skills and plugins hub covers that. This page is about everyone else on the team.

Pick the lever that fits your team#

Most teams start with the first row and move to managed settings when someone asks "who approved this plugin?"

Step 1: Build the team marketplace#

A marketplace is a directory with a .claude-plugin/marketplace.json that lists plugins and where to fetch each one. The minimal file needs a name, an owner and a plugins array. This is the one we used for testing:

{
  "name": "acme-tools",
  "description": "Plugins for the Acme platform team",
  "owner": { "name": "Acme Platform" },
  "plugins": [
    {
      "name": "house-style",
      "source": "./plugins/house-style",
      "description": "Team review conventions"
    }
  ]
}

Run claude plugin validate ./team-plugins before you push. On our test marketplace it printed Validation passed with warnings with one warning about a missing author field in plugin.json, which is advisory.

Two details matter later:

• The install name comes from name, not the repo. Teammates install with house-style@acme-tools, where acme-tools is the name field in marketplace.json.
• Approved third-party plugins can live in your catalog too. A plugin entry can point at another repository with a github, url or git-subdir source, and each takes ref (a branch or tag) and sha (a full 40-character commit). Pinning sha is how you approve one exact version of someone else's plugin without forking it.

Push the directory to a private repo your team can read. Claude Code clones with the git credentials already on each machine and never prompts: HTTPS works through your credential helper (gh auth login, Keychain), SSH needs the host in known_hosts and a key without a passphrase prompt.

Step 2: Share it with one repository#

From the repository you want to equip, run this once in your shell and commit the result:

claude plugin marketplace add your-org/your-marketplace --scope project
claude plugin install house-style@acme-tools --scope project

In our test the first command printed Successfully added marketplace: acme-tools (declared in project settings) and the second Successfully installed plugin: house-style@acme-tools (scope: project). The .claude/settings.json it wrote holds both keys. With a GitHub source it looks like this:

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "github", "repo": "your-org/your-marketplace" }
    }
  },
  "enabledPlugins": {
    "house-style@acme-tools": true
  }
}

What teammates get when they pull:

• Interactive sessions: the marketplace registers after they accept the workspace trust dialog for that folder. In an untrusted folder Claude Code ignores the entry without a message.
• Plugins stored inside the marketplace repo (relative ./plugins/... sources) load from the marketplace copy once it registers.
• Plugins whose entry points at an external repo do not install from settings alone. Each contributor sees Plugin "<name>" is enabled in project settings but isn't installed until they run claude plugin install <name>@<marketplace> --scope project.
• claude -p runs apply the repo's extraKnownMarketplaces only in folders whose trust was already accepted interactively.

One trap we hit while testing: claude plugin install house-style --marketplace ../team-plugins --scope project installed the plugin at project scope but declared the marketplace in user settings (declared in user settings). The docs confirm this is by design. So the one-liner is for onboarding a person, not for wiring up a repo. Use marketplace add --scope project when you want the marketplace committed.

Project scope sits in the middle of the precedence order: local settings override project, and project overrides user. A developer who does not want a team plugin can turn it off for themselves in .claude/settings.local.json without touching the shared file, and /plugin uninstall on a project plugin asks whether to disable it for you (press y) or remove it for everyone (press u).

Step 3: Make onboarding one command#

For a new teammate, or a README install section, the v2.1.292 form adds the marketplace and installs in one go:

claude plugin install deploy-helper --marketplace your-org/plugins

Give the plugin name without an @marketplace suffix. From the shell it adds the marketplace without a confirmation step and reuses one already added from the same source. Inside a session, /plugin install deploy-helper --marketplace your-org/plugins works from v2.1.275 and asks before adding a new marketplace. Check your version with claude --version first; older clients will not recognize the flag.

Step 4: Require plugins across the company#

Managed settings are the policy layer every machine reads, and they beat every other scope. Put the same two keys there and Claude Code registers the marketplace and installs the plugins at each user's next session start. A user who disables a managed plugin at their own scope still gets it, because managed settings win.

Pick one of three delivery mechanisms:

By default only one of the three applies on a machine: Claude Code checks server-managed first, then MDM, then the file, and uses the first that delivers a policy key. If your server-managed settings set even one unrelated key, plugin keys in a local file are ignored on that machine unless you set managedSourcesBehavior to "merge". This catches teams that pilot with a file and later turn on the admin console.

This is the policy most organizations want, adapted from the docs' "allow the official marketplace and your own" example:

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "anthropics/claude-plugins-official" },
    { "source": "github", "repo": "your-org/*" },
    { "source": "skills-dir" }
  ],
  "extraKnownMarketplaces": {
    "claude-plugins-official": {
      "source": { "source": "github", "repo": "anthropics/claude-plugins-official" }
    },
    "acme-tools": {
      "source": { "source": "github", "repo": "your-org/your-marketplace" },
      "autoUpdate": true
    }
  },
  "enabledPlugins": {
    "house-style@acme-tools": true
  },
  "disableSideloadFlags": true
}

What each piece does, and what it does not:

• strictKnownMarketplaces is the allowlist of marketplace sources. It does not register anything, which is why both marketplaces also appear in extraKnownMarketplaces. An empty list, [], blocks every source including the official marketplace.
• your-org/* matches every repo under that GitHub owner (v2.1.223 or later). The * must stand for the whole repo name; your-org/tools-* is ignored as invalid.
• { "source": "skills-dir" } keeps plugins in ~/.claude/skills/ or a project's .claude/skills/ loading. Set any allowlist without it and those stop loading, which looks like a bug the first time you see it.
• disableSideloadFlags rejects --plugin-dir, --plugin-url, --agents, folders named in CLAUDE_CODE_PLUGIN_DIRS, the Agent SDK plugins option and non-SDK --mcp-config. The allowlist alone does not block --plugin-dir. If you have read our take on plugin URLs as a supply chain, this is the switch that closes it.
• To block one plugin inside an allowed marketplace, set it to false in managed enabledPlugins. The allowlist only sees marketplaces, not entries.

Allowlist matching is exact. An entry without ref does not cover a source with ref: "main", and a trailing slash, a .git suffix or ssh:// instead of https:// all count as different values. If your marketplace can be cloned more than one way, use a hostPattern entry such as ^github\.example\.com$ instead. The blocklist, blockedMarketplaces, is checked first and matches more loosely: it canonicalizes git URLs, so one entry catches the git@ and https:// spellings of the same repo.

Both lists apply before any download and again at every session start, so tightening the policy unloads already-installed plugins from sources that no longer match. Users see Marketplace "<name>" is not in the allowed marketplace list or is blocked by enterprise policy in /plugin.

Plugins are only one part of the policy file. The same file carries your permission allow and deny rules, and if plugin hooks worry you, allowManagedHooksOnly limits which hooks run at all.

Step 5: Pin versions and control updates#

Auto-update is on by default for most of Anthropic's official marketplace names (claude-plugins-official included) and for marketplaces added from claude.ai. It is off for every third-party marketplace, which includes yours. You have three knobs:

• Per marketplace, fleet-wide: set "autoUpdate": true or false on the managed extraKnownMarketplaces entry. When the managed entry sets it, a user's /plugin toggle is refused with an error starting Auto-update for '<name>' is set by.
• Everything off: "env": { "DISABLE_AUTOUPDATER": "1" } in managed settings. It also stops Claude Code's own updates; add "FORCE_AUTOUPDATE_PLUGINS": "1" to keep plugin updates flowing while freezing the CLI.
• Pin what people get: users can add your-org/your-marketplace#stable to track a branch or tag, and plugin entries can carry ref and sha.

On the publishing side, a user gets a new copy only when the plugin's computed version changes. Either bump version on every release or omit it entirely so users track commits. Setting "version": "1.0.0" and pushing new commits without changing it means nobody receives them. Do not set version in both plugin.json and the marketplace entry; the plugin.json value wins silently. Our post on plugin evals in CI covers testing a release before you bump.

Server-managed settings apply to everyone in the org, so they cannot give different groups different plugins. For a stable and an early-access channel, host two marketplaces at different refs and deliver each group its own endpoint-managed settings or Claude apps gateway policy.

Step 6: CI runners and containers#

claude -p runs install marketplaces and plugins in the background, so a plugin can be missing from the first turn. Set CLAUDE_CODE_SYNC_PLUGIN_INSTALL=1 to make the run wait.

For images that cannot clone at runtime, build a seed:

CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin marketplace add your-org/your-marketplace
CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin install house-style@acme-tools

Then set CLAUDE_CODE_PLUGIN_SEED_DIR=/opt/claude-seed in the runtime environment and enable the plugins with enabledPlugins; seeding alone does not enable them. Seeds are read-only and auto-update is forced off, which is what you want in CI. On GitHub Actions, a private marketplace in another repo needs a token with read access exported as GH_TOKEN and gh auth setup-git, because the default workflow token only reads its own repo.

Verify it works#

• One machine: run /plugin and check the marketplace and plugins appear, or claude plugin list in the shell, which prints Version, Scope and Status for each.
• Managed settings loaded: run /status and look for Enterprise managed settings in the Setting sources line. Missing means the source did not load.
• CI: claude -p --output-format stream-json --verbose; the init event lists loaded plugins under plugins, and seeded ones have a path under the seed.
• Context cost: claude plugin details <plugin> prints an Always-on token figure, the cost every developer pays every session whether the plugin is used or not. Our one-skill test plugin cost about 32 tokens. In /plugin, official marketplace entries show this up front and highlight anything at 2,000 tokens or more. Multiply by headcount before you force-enable a heavy plugin for everyone.

Troubleshooting#

What managed settings still cannot do#

The docs are candid about gaps security reviews ask for. There is no key to hide /plugin; the closest you get is an allowlist naming only your marketplace, managed enabledPlugins, and disableSideloadFlags. Server-managed settings deliver one configuration per organization, so per-group targeting needs endpoint-managed files or gateway policies. And the claude.ai plugin toggles under Organization settings do not set these keys; plugins synced from claude.ai have their own switch, syncClaudeAiPlugins.

Remember also what the policy is guarding. A plugin can run hooks, MCP servers and mods outside Claude Code's sandbox with the user's full permissions. An allowlist decides who may publish into your fleet. It does not review what they publish. That review still has to happen in your marketplace repo's pull requests, which is the real argument for a single company catalog with sha-pinned third-party entries.

What people are actually saying#

• Distribution was the worry from day one. On the Hacker News thread for the plugin launch a year ago, joesaunderson wrote that "plugin maintainers do not want to have to build a marketplace as well as a plugin." The --marketplace flag goes some way toward making the marketplace an install detail rather than a project.
• The first failure people hit was auth. In the same thread, BrutalCoding reported that adding Anthropic's demo marketplace failed with an SSH authentication error until they switched to the HTTPS URL. Current versions check whether your SSH key works for github.com and fall back to HTTPS.
• Enterprises asked for exactly this shape. In GitHub issue #20301 (January 2026), hi120ki described wanting one company-managed marketplace and an allowlist because "it has become a de facto practice for users to add arbitrary third-party marketplaces." The request for a subdirectory path plus a pinned sha was flagged as a duplicate of earlier requests and closed; the git-subdir plugin source, which takes path, ref and sha, now covers it.
• Our counter-case: in our view, a small team with one repo does not need any of the managed machinery. Committed project settings plus code review on the marketplace repo is enough, and an allowlist added before you have a second marketplace mostly adds friction.

FAQ#

How do I share Claude Code plugins with my team?#

Put them in a marketplace repo with .claude-plugin/marketplace.json, then run claude plugin marketplace add your-org/your-marketplace --scope project in your project and commit .claude/settings.json. Teammates get the marketplace after they trust the folder.

What is the difference between extraKnownMarketplaces and strictKnownMarketplaces?#

extraKnownMarketplaces registers a marketplace on a machine. strictKnownMarketplaces is a managed-only allowlist of sources plugins may come from, and it registers nothing. Most company policies use both.

Does claude plugin install --marketplace work for project setup?#

It installs the plugin at the scope you pass, but the marketplace it adds is always declared in user settings, even with --scope project. Use claude plugin marketplace add --scope project to commit the marketplace for a repo.

Can I stop developers installing plugins from random GitHub repos?#

Yes, with strictKnownMarketplaces in managed settings plus disableSideloadFlags. When you set the allowlist in the claude.ai admin console, claude.ai also refuses marketplaces added there from repositories the allowlist does not admit.

Do plugins auto-update for my team?#

Not for your own marketplace by default. Turn it on with "autoUpdate": true on the managed extraKnownMarketplaces entry, or have each user enable it in /plugin under Marketplaces.

Continue Reading#

• Best Claude Code Skills and Plugins in 2026 - where to find plugins worth putting in your team catalog, and the personal install flow
• Claude Code Plugin URLs Turn Skills Into a Supply Chain - why sideloaded plugins are the part of this to lock down first
• Claude Code Mods: What They Are and How to Write One - the plugin type that runs JavaScript inside Claude Code, and why it raises the stakes
• Claude Code Hooks Explained - what plugin hooks can run on every tool call
• Claude Code Plugin Evals Make Agent Extensions Testable - test a plugin before you bump its version for the whole team

Sources#

• Claude Code docs: Install and manage plugins - scopes, --marketplace version requirements, private marketplace credentials, auto-update defaults (fetched October 9, 2026)
• Claude Code docs: Manage plugins for your organization - delivery mechanisms, control matrix, allowlist matching, seeds, update policy, limits (fetched October 9, 2026)
• Claude Code docs: Host and maintain a marketplace - marketplace add --scope project, versioning rules, release channels (fetched October 9, 2026)
• Claude Code docs: Create a marketplace - marketplace.json required fields and validation
• Claude Code docs: Marketplace reference - plugin and marketplace source types, ref and sha
• Claude Code docs: Plugin security and trust - what a plugin can run, official marketplace names
• Claude Code docs: Managed settings - file paths per platform
• Claude Code docs: Measure plugin cost and usage - claude plugin details and the 2,000-token highlight
• Claude Code changelog - v2.1.292 --marketplace on claude plugin install, v2.1.295 settings-file warnings
• Hacker News: Customize Claude Code with plugins - launch discussion
• GitHub issue #20301 - enterprise request for a single pinned company marketplace
• Test run: Claude Code 2.1.295, local directory marketplace, marketplace add --scope project, install --marketplace, plugin list and plugin details, October 9, 2026