skip to content

Rolling a Claude Code plugin out to twenty repositories, what do the user, project and local install scopes each write, and which wins?

level: middleimportance: should knowfreq 14%

answer

  1. three settings files, one key
  2. enabledPlugins entries per plugin id
  3. local over project over user
  4. project scope enables, does not download
  5. extraKnownMarketplaces in committed settings

basics

~20 s

Each scope writes an enabledPlugins entry: user to ~/.claude/settings.json, project to the committed .claude/settings.json, local to .claude/settings.local.json. Local beats project beats user, and a project entry turns an externally sourced plugin on without downloading it.

solid answer

~40 s

The scope names the settings file that records `"name@marketplace": true` under `enabledPlugins`: user scope (the default) writes `~/.claude/settings.json` for every project on the machine, project scope writes the committed `.claude/settings.json` for everyone in the repository, and local scope writes the gitignored `.claude/settings.local.json` for you in that repository. Entries merge per plugin id, and the highest source that mentions the id wins: local over project over user, with the `--settings` flag and managed settings above them. Committing a project entry turns the plugin on for collaborators but does not download an externally sourced plugin, so each one also runs `claude plugin install <name>@<marketplace> --scope project`, unless the marketplace lists it by relative path. To opt out of a project-enabled plugin, set it to `false` in `.claude/settings.local.json`.

code

json · 10 lines
json
{
  "extraKnownMarketplaces": {
    "platform-tools": {
      "source": { "source": "github", "repo": "example-org/platform-tools" }
    }
  },
  "enabledPlugins": {
    "team-toolkit@platform-tools": true
  }
}

go deeper

for a junior

Recall the three scopes and their files: user in ~/.claude/settings.json, project in the committed .claude/settings.json, local in the gitignored .claude/settings.local.json.

for a middle

Explain the per-id merge of enabledPlugins, why local beats project beats user, and how a developer opts out of a plugin the repository turns on.

for a senior

Diagnose rollout gaps: project entries that enable but never download, extraKnownMarketplaces ignored until trust, plugins missing on the first -p turn, and cloud sessions loading none of it.

for a principal

Decide whether a plugin should follow repositories or people, and how much to commit per repository versus delegating a fleet-wide requirement to managed policy.

## The question behind scopes When a team wants the same skills, reviewer agent, format hook and MCP servers in twenty repositories, the real decision is **who should get the plugin, and through which file**. A plugin's **install scope** answers both: it names the settings file that records the plugin as enabled, and therefore who that file reaches. Installation (fetching files into `~/.claude/plugins/`) and enablement (an entry in settings) are separate stages, and most rollout surprises come from confusing them. ## What each scope writes Every scope writes the same key, `enabledPlugins`, as `"<plugin>@<marketplace>": true`, into a different file: | Scope | File | Reaches | |---|---|---| | `user` (default) | `~/.claude/settings.json` | You, in every project on this machine | | `project` | `.claude/settings.json` (committed) | Everyone who works in the repository | | `local` | `.claude/settings.local.json` (gitignored) | You, in this repository only | In a session, the `/plugin` details pane offers the three as "Install for you", "Install for all collaborators on this repository" and "Install for you, in this repo only". From a shell or setup script, `claude plugin install <id> --scope user|project|local` does the same; `install` and `uninstall` default to `user`, while `enable` and `disable` act on the most specific scope that already lists the plugin. ## Which entry wins `enabledPlugins` merges **key by key**: for each plugin id, the value from the highest-precedence source that mentions it applies, and a source that is silent leaves the lower value in place. From lowest to highest: 1. A directory passed with `--add-dir` (only a `true` counts, and anything else overrides it). 2. User settings. 3. Project settings. 4. Local settings. 5. The `--settings` flag for that session. 6. Managed settings, whose `true` force-enables and `false` blocks; locking plugins for an organization is a separate topic. So a developer who sets a plugin to `false` in user settings still gets it in a repository whose project file says `true`; `/plugin` and `claude plugin list` say the project setting overrides the user one. The fix is a `false` in that repository's `.claude/settings.local.json`. Choosing **Uninstall** on a project-enabled plugin offers exactly that ("Disable for me") or removing it from the shared file for everyone. ## Project scope enables, it does not download Committing a project entry turns the plugin on for collaborators, but Claude Code **does not fetch an externally sourced plugin** from a project file alone. Each teammate sees `Plugin "<name>" is enabled in project settings but isn't installed` in the `/plugin` Errors tab until they run `claude plugin install <name>@<marketplace> --scope project` once. Two setups avoid that step: - **Relative-path plugins**: when the marketplace lists the plugin by a path inside itself, it loads from the marketplace copy, with no install record needed. - **Committed marketplace registration**: `claude plugin marketplace add example-org/platform-tools --scope project` writes `extraKnownMarketplaces` into `.claude/settings.json`, so every teammate gets the catalog. Those entries apply only after the teammate accepts the workspace trust dialog for the folder; in an untrusted folder they are ignored silently. ## Confirming the rollout on one machine Before committing the same block to twenty repositories, check one teammate's machine end to end: 1. `claude plugin list` prints each plugin with `Version`, `Scope` and `Status` lines, so you can see whether the project entry or a personal install is the one in effect. 2. The `/plugin` **Installed** tab shows the plugin with its scope, and a disabled-but-still-loading row names the source that overrode the user setting. 3. The `/plugin` **Errors** tab shows `Plugin "<name>" is enabled in project settings but isn't installed here` when the download step was skipped. 4. Typing `/` and finding `/<plugin>:<skill>` confirms the session actually loaded it. ## Rollout notes for twenty repositories - Commit the same `extraKnownMarketplaces` and `enabledPlugins` block to each repository, or ask developers to install at user scope if the plugin should follow people rather than repositories. - In `claude -p` and CI runs, plugins install in the background and can be missing from the first turn; `CLAUDE_CODE_SYNC_PLUGIN_INSTALL=1` makes the run wait. - A cloud session, including claude.ai/code, loads neither your machine's plugins nor the ones a repository's `.claude/settings.json` enables. - The terminal, the desktop app's local sessions and the VS Code extension read the same files, so a user-scope install appears in all three.

  • A developer disabled a plugin in ~/.claude/settings.json, yet it still loads in one repository. Why, and what is the fix?
    That repository's `.claude/settings.json` sets the plugin to `true`, and project settings outrank user settings for that id; `/plugin` and `claude plugin list` name the overriding source. The developer sets the id to `false` in `.claude/settings.local.json`, which outranks the project file, or picks "Disable for me" when uninstalling. If managed settings force it on, no user file can turn it off.
  • In a CI job with claude -p, why can a project-enabled plugin's skill be missing on the first turn?
    In non-interactive runs, marketplaces and plugins install in the background after the session starts, so the first query can run before the plugin arrives. Setting `CLAUDE_CODE_SYNC_PLUGIN_INSTALL=1` makes the run wait for the install. The repository's `extraKnownMarketplaces` entries also apply only in a folder whose trust was already accepted.

  • Committing enabledPlugins alone downloads a GitHub-sourced plugin for every teammate.
  • A user-level false always beats a project-level true.
  • Local scope writes a file every teammate shares through git.
  • Project scope is the default for claude plugin install.
  • Repository extraKnownMarketplaces entries apply before the folder is trusted.