An enabled plugin rides along in every Claude Code session, whether or not you use it. The official docs state it flatly: “An enabled plugin is part of every session, not only the sessions where you use it.” For each skill, agent, and command Claude can invoke on its own, the name and description occupy context on every turn, and those tokens count toward your usage even in sessions where nothing from the plugin runs; the full text of a skill or agent loads only when it is used. Plugins in Anthropic’s official marketplace show a Context cost estimate in the /plugin pane before you install. Afterward, claude plugin details <name> prints an “Always-on” line with the number of tokens the plugin adds to every session where it is enabled, plus per-component rows showing which skill or agent contributes most (plugins overview, install and manage plugins).
The second fact sits on the first line of the security page: a plugin you install “can execute arbitrary code on your machine with your user privileges” (plugin security and trust). Everything below, the component model, the marketplace tiers, the scope rules, the dependency graph, lives between those two facts. Plugins are cheap to add and expensive to trust, and the current documentation is explicit about both halves.
What a plugin actually is
A plugin is a directory of components that Claude Code installs and loads as one unit. The manifest at .claude-plugin/plugin.json is optional: without one, Claude Code loads whatever it finds in the standard layout and takes the plugin’s name from the marketplace entry, or from the directory name when you load a folder directly with --plugin-dir. You write a manifest when you want metadata, a component outside its default directory, userConfig prompts, or an inline component definition, and every other plugin file lives at the plugin root rather than inside .claude-plugin/ (plugin manifest reference).
Most plugins arrive from a marketplace: a repository or directory holding a .claude-plugin/marketplace.json catalog that lists plugins and where to fetch each one. The docs’ own description is worth keeping: “It’s a catalog, not a hosted store.” You add a marketplace once, then install plugins from it by name, such as commit-commands@claude-plugins-official (create a marketplace).
What a plugin can contain
The default locations and rules below come from the official plugin documentation as retrieved on 2026-10-12.
| Component | Default location | What it adds | Documented at |
|---|---|---|---|
| Manifest | .claude-plugin/plugin.json, optional | Name, metadata, userConfig prompts, and any component defined inline or kept outside its default location | Manifest reference |
| Skills | skills/ | SKILL.md instructions Claude loads when relevant and can also run as a command | Plugins overview |
| Commands | commands/ | Flat Markdown slash commands; the docs say to prefer skills/ for new plugins | Manifest reference |
| Agents | agents/ | Subagent definitions Claude can delegate to; subfolders are part of the agent name | Plugins overview |
| Hooks | hooks/hooks.json | Shell commands Claude Code runs at lifecycle points, such as after every edit | Plugins overview |
| Mod | Hooks module written in JavaScript | Hooks as JavaScript functions, which can also draw panes and add commands; a plugin with one is called a mod | Plugins overview |
| MCP servers | .mcp.json | Tool servers Claude Code connects to while the plugin is enabled | Plugins overview |
| LSP servers | .lsp.json | Language servers Claude Code starts; diagnostics are pushed into context after edits by default | Manifest reference |
| Monitors | monitors/monitors.json | A shell command Claude Code runs as a persistent background process in the session working directory; experimental, interactive sessions only, and not on Amazon Bedrock, Google Cloud’s Agent Platform, or Microsoft Foundry | Manifest reference |
| Executables | bin/ | On the Bash tool’s PATH while the plugin is enabled; claude.ai and Cowork will not install a plugin that ships this directory | Manifest reference |
| Output styles, workflows, themes | output-styles/, workflows/, themes/ | Output style Markdown, workflow .js files, and theme JSON | Manifest reference |
| Settings | settings.json | agent and subagentStatusLine defaults applied while the plugin is enabled | Manifest reference |
A few rules from the manifest reference round this out. Component paths declared in a manifest must start with ./ and resolve inside the plugin root; a path containing .. fails validation with a path-traversal warning and never loads. Manifest component keys either replace, add to, or merge with the default locations: setting commands stops the default commands/ scan unless you list that folder explicitly, skills adds to the default scan, and hooks, MCP, and LSP declarations merge with the default files. MCP configuration can also point at .mcpb or .dxt bundles, or fetch one from an https:// URL. And a CLAUDE.md at the plugin root is not loaded as context; the validator warns about it, and instructions that should reach Claude’s context belong in a skill.
Names, versions, and prompted configuration
name is the only required manifest key. It must be kebab-case, and every component is namespaced under it: an agent named reviewer in a plugin called deploy-tools appears as deploy-tools:reviewer, and a command named about runs as /deploy-tools:about. Validation also refuses plugin names that could pass as Anthropic’s own, including anything starting with claude-, anthropic-, or anthropics-. The version field is a free-form string, not checked against semver; setting it pins users to that version until you change it. defaultEnabled (true by default) controls whether an installed plugin starts on, and a plugin that an enabled plugin depends on starts enabled regardless. userConfig declares values Claude Code prompts the user for at enable time, so nobody edits settings files by hand; sensitive values go to the platform’s credential store rather than settings.json. For CI, claude plugin validate is the authoritative check, and --strict turns warnings into failures.
Three marketplace tiers, enforced by name
Claude Code sorts marketplace names into three tiers, and it enforces the boundary mechanically: official and community names are accepted only for marketplaces sourced from github.com/anthropics/ repositories, so a third-party catalog cannot present itself as an Anthropic one. Adding a marketplace that uses a reserved name from elsewhere is refused outright.
The official tier covers claude-plugins-official plus a longer list of names, among them claude-code-plugins (the demo marketplace), agent-skills, life-sciences, claude-for-legal, claude-for-financial-services, and knowledge-work-plugins. Claude Code registers the official marketplace automatically the first time you start an interactive terminal session, unless a managed policy blocks it; it does not add Anthropic’s community or demo marketplaces on its own. The community tier is claude-community, claude-plugins-community, and healthcare, and the claude-community catalog pins nearly every entry to a commit SHA; Claude Code refuses to install a different commit. Every other marketplace, including ones your coworkers or your organization publish, is third-party (plugins overview, plugin security and trust).
Auto-update defaults follow the tier. Official names update automatically, with two documented exceptions (knowledge-work-plugins and first-party-plugins), as do marketplaces added from claude.ai. Community, third-party, and local development marketplaces have auto-update off by default. Updates are applied after a session starts: Claude Code refreshes the marketplace and rewrites the on-disk copies, while the running session keeps the versions it already loaded and tells you to run /reload-plugins to apply them. To browse before opening a terminal, the web directory is Claude Marketplace at claude.com/marketplace, where each plugin’s Claude Code button copies the shell install command (install and manage plugins).
Scopes: three you choose, one imposed
When you install a plugin you pick a scope, and the scope decides who the plugin is enabled for.
| Scope | Recorded in | Effect |
|---|---|---|
| User | enabledPlugins in ~/.claude/settings.json | Enabled for you in every project on the machine |
| Project | enabledPlugins in .claude/settings.json, committed | Enabled for everyone who works in the repository; committing the entry does not download anything, so each collaborator also runs the install once at project scope |
| Local | .claude/settings.local.json | Enabled for you in this repository only |
| Managed | Your organization’s managed settings | Installed by policy; the Installed tab lists these but you cannot enable, disable, or uninstall them locally |
When the same plugin is set at several scopes, local overrides project and project overrides user. The terminal, the desktop app’s local sessions, and the VS Code extension on one machine read the same settings files, so a user-scope install in any of them is available in the others. Cloud sessions, including the browser at claude.ai/code, do not load plugins from your local settings; your claude.ai account is instead a separate source that syncs the plugins you or your organization turn on there, listed as <name>@synced. Non-interactive runs such as claude -p have no /plugin panel; you manage from the shell with claude plugin commands. One trap worth knowing: uninstalling a plugin that the repository’s project settings enable prompts a choice between disabling it just for you or removing it for everyone.
Dependencies behave like a package manager’s
A plugin can declare the plugins it requires. Entries in the dependencies array are "name", "name@marketplace", or an object with name, marketplace, and version; bare names resolve against the plugin’s own marketplace. The behaviors around the graph are documented on the install page: installing a plugin also installs and enables its declared dependencies at the same scope; enabling it enables dependencies that are installed but disabled, and fails with instructions if a declared dependency is missing; disabling a plugin that another enabled plugin still needs is refused, with a chained command that disables both in the right order; and auto-installed dependencies survive uninstall until you run claude plugin prune (install and manage plugins). Groundy covered the enforcement rollout separately in Claude Code Adds Plugin Dependency Enforcement, so this piece skips the history.
Updates, reloads, and where plugin state survives
Two environment variables define where plugin state belongs. ${CLAUDE_PLUGIN_ROOT} points at the installed version’s directory and changes whenever the plugin updates, which is why the manifest reference tells authors not to write state there. ${CLAUDE_PLUGIN_DATA} resolves to ~/.claude/plugins/data/<id>/, is created on first reference, and is kept across plugin updates; uninstalling from the last scope deletes it by default. Cached plugin files live under ~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/ and stay on disk for 14 days before a background sweep removes them. Also worth knowing: closing the /plugin panel with pending changes applies them through an automatic reload, unless that reload would invalidate the prompt cache, in which case Claude Code warns and leaves the changes pending for /reload-plugins --force.
What an installed plugin can do to your machine
The security page enumerates what an installed plugin can do, and the list is longer than hooks. Hooks and monitors run as shell commands with your full user permissions, outside Claude Code’s sandbox. A mod runs JavaScript inside Claude Code with your permissions. MCP and LSP servers run as processes Claude Code starts on your machine. Anything in bin/ goes on the PATH of the Bash tool’s shell, so Claude’s commands can run those executables directly. Skills, commands, and agents enter Claude’s context as instructions. And when auto-update is on for the marketplace a plugin came from, the files you reviewed can change on disk in the background.
The line that matters for policy: Claude Code’s permission rules and sandbox cover the tool calls Claude makes, not the code a plugin runs by itself. A call to one of the plugin’s MCP tools, or a Bash command that runs an executable from bin/, is a tool call and passes through your permission rules. The plugin’s own hooks, monitors, and server processes do not. The trust warning in the details pane reads the same for every plugin regardless of marketplace, because “a marketplace’s name tells you who publishes the catalog, not what each plugin in it does.” Claude Code refuses rather than warns in two documented cases: a marketplace using an official or community name from a source outside github.com/anthropics/, and an archive source whose downloaded sha256 digest does not match its pin (plugin security and trust).
That caution is not hypothetical, though the strongest evidence here is researcher-documented rather than vendor-documented. In 2026, SentinelOne and Prompt Security documented a dependency-hijack pattern in which a benign-looking plugin from an unofficial marketplace ships a dependency-management skill that redirects package installs to an attacker-controlled source: when a developer asks Claude to install a library, the agent invokes the skill and pulls a trojanized build that imports cleanly, leaving the payload in the environment. The vendor pages above do not describe this attack; they do describe the surfaces it abuses.
Do you even need a plugin?
The overview page has a section the marketing never quotes: “Decide whether you need a plugin.” Skills, subagents, hooks, and MCP servers all work on their own, and a skill saved in ~/.claude/skills/ is available in every project on your machine. A plugin earns its overhead when you want several components packaged as one unit, a one-command install for teammates, or versioned releases from a marketplace you control (plugins overview).
| Standalone component | Plugin | |
|---|---|---|
| What it is | A skill in ~/.claude/skills/, a subagent, a hook, or an MCP server, each working on its own | Several components installed and loaded as one unit |
| Sharing | Files you hand over or commit yourself | One-command install and updates from a marketplace |
| Session footprint | Not documented on the pages cited here | Invocable components’ names and descriptions occupy context every session; claude plugin details prints the Always-on token count |
| Developing | Edit in place | Load straight from a folder with --plugin-dir, no marketplace needed |
The plugin system has settled into package-manager mechanics: namespaced components, an optional manifest with version pinning, a dependency graph with a guarded disable, tiered marketplace names with enforced provenance, and organizational policy layered on top. It also has an explicit cost model, down to a per-plugin token figure. Install accordingly: read the Always-on line before you add, read the hooks before you confirm, and pin the sources you intend to keep.
Join the discussion
Share a useful perspective or ask a question about this article.