Claude Code plugin scope controls where a package is enabled

Claude Code plugin scope controls where a package is enabled

Claude Code plugin scope controls where a package is enabled. User scope applies across one person’s projects on that machine, project scope records a repository’s shared configuration, and local scope applies to one person in one repository. Committing a project setting enables the package for collaborators, but each collaborator still installs it locally. (install and manage plugins)

Scope controls configuration reach; plugin code can still run with the user’s privileges. Choosing local scope for a trial limits where the setting applies, while source review determines whether the code is acceptable to run. These are separate decisions. (plugin security guidance)

A plugin packages components for a repeatable setup. It can contain instructions such as skills and agents, executable hooks, or connections to services. A marketplace supplies the catalog from which the package is fetched. Use a package when those pieces belong together, and inspect its contents before making it a shared dependency. (Claude Code plugin overview)

What a Claude Code plugin is

A plugin is a directory of components, usually with a .claude-plugin/plugin.json manifest. The manifest carries metadata and can declare components or point to files outside their standard locations. A manifest is optional when a package follows the standard layout, but it becomes valuable when a team needs configuration, dependencies, or explicit component paths. (plugin manifest reference)

The packaging decision is separate from the component decision:

Claude Code’s plugin documentation makes an important operational point: skills, agents, hooks, and MCP servers can also work on their own. Use a plugin when the pieces belong together, such as a repository workflow that needs a release checklist skill, a review agent, a controlled hook, and a named service connection. (Claude Code plugin overview)

For background on the distinctions among reusable instructions and tool connections, see Groundy’s comparison of the skills architecture. The package format does not turn every component into an MCP server, nor does it make an MCP server safe merely because it arrived inside a plugin.

Marketplaces are catalogs, not app stores

A marketplace is normally a repository containing .claude-plugin/marketplace.json. It tells Claude Code which plugins are available and where their files come from. Anthropic documents separate official, community, and demo marketplaces; a third-party marketplace is any other source. The marketplace name identifies the catalog’s publisher, not a security guarantee for every plugin it lists. (Anthropic’s marketplace guide; plugin security guidance)

The current official marketplace name is claude-plugins-official. Claude Code adds it the first time you start an interactive terminal session unless managed policy or an environment setting blocks that behavior. The community and demo marketplaces must be added explicitly. The demo catalog in anthropics/claude-code is not the official marketplace, so older setup instructions that add it should not be treated as the default path for a new installation. (Anthropic’s marketplace guide)

For a team marketplace, the useful control is ownership: know who maintains the repository, where the marketplace manifest lives, which plugins it names, and how updates reach developer machines. A repository is not automatically a good marketplace just because it contains prompts or shell scripts.

Install deliberately, then choose the scope

In an interactive session, /plugin opens the plugin interface and /plugin install <name>@<marketplace> opens a plugin’s details before the user chooses an installation scope. From a shell, claude plugin install can be used for scripted setup. A marketplace has to be registered before a plugin from it can be installed. (install and manage plugins)

Claude Code supports three scopes:

Project scope deserves the same review discipline as a development dependency. Committing an enabled-plugin entry lets collaborators know the project expects it, but each collaborator still installs the package locally. Local scope is a sensible first stop for an unfamiliar plugin because it limits the configuration’s reach without pretending the code itself is isolated. (install and manage plugins)

Use the details view before installing to check the declared components. The manifest reference documents component fields such as skills, commands, agents, hooks, MCP servers, and language servers; after installation, the details command reports a Component inventory for the installed copy. Anthropic’s official marketplace also presents context-cost estimates in the relevant details view. That makes it possible to ask a concrete question before rollout: what will this plugin add to every session, and what only loads when invoked? (install and manage plugins)

The security model: a plugin is executable supply chain

The most important fact about plugins is simple: an installed plugin can execute arbitrary code with the user’s privileges. Hooks run shell commands; monitors can run background commands; a mod runs JavaScript inside Claude Code; and enabled MCP or language-server processes can be started by Claude Code. Skills, commands, and agents also supply instructions that influence how Claude uses tools. (plugin security guidance)

Claude Code’s sandbox and permission rules cover its tool calls, but they do not automatically sandbox code that a plugin runs by itself. That is why an official marketplace label and a familiar author name are useful provenance signals, not substitutes for review. The same caution applies to update behavior: when auto-update is enabled for a marketplace, the installed files can change after the initial review. (plugin security guidance; install and manage plugins)

Before enabling a plugin in a shared repository, review at least these surfaces:

1. The marketplace source and the plugin’s source repository.
2. The component inventory in the plugin details view.
3. hooks/hooks.json, .mcp.json, and every executable under bin/ when they exist.
4. Any dependencies, user configuration, environment-variable references, and update behavior.
5. The scope and the owner who will review future changes.

Read the plugin’s source before installation. After installation, claude plugin details <name> reports the installed copy’s Component inventory. While developing a plugin, use --plugin-dir to load it directly from a local folder without a marketplace. These are separate inspection and development workflows. (plugin security guidance; Claude Code plugin overview)

A practical team workflow

Start with a local installation and a narrow, observable task. Local scope records the setting in .claude/settings.local.json; project scope records it in .claude/settings.json; user scope records it in ~/.claude/settings.json. Review the file that will carry the setting before promoting a trial to a team dependency. (install and manage plugins) Verify that the declared skills and commands appear, that any MCP server is configured for the intended account, and that the plugin’s hooks do not run unexpected commands. Then disable or uninstall it cleanly if it does not meet the team’s expectations.

If the plugin becomes a shared dependency, promote it deliberately: name the owning team, document the chosen marketplace and plugin version or revision, set an update policy, and keep a lightweight review record for changes to executable components. A plugin that only supplies a skill may merit a different review path from one that launches an MCP server or a hook, even when both come from the same marketplace.

For a deeper look at the policy and packaging distinction, see Anthropic’s official extension model. The durable takeaway is not that every coding team needs a large ecosystem. It is that Claude Code gives teams a way to package repeatable agent workflows, and that the package should be treated as software with permissions, updates, and owners.