Plugins: package and share your agent setup

Once your team has a few good skills, a reviewer agent and three hooks that everyone should run, copying folders between repositories stops working. A plugin packages that setup as one unit with a name and a version, so a teammate installs it with one command and gets updates when you release them.

A Claude Code plugin is a directory of components that Claude Code installs and loads together. An optional manifest at .claude-plugin/plugin.json gives it a name, a version and other metadata. Everything else sits at the plugin root.

Every component is namespaced under the plugin's name, so two plugins can each ship a review skill without a clash. A CLAUDE.md at the plugin root is not loaded. Put instructions in a skill.

Plugins usually come from a marketplace: a repository or directory with a .claude-plugin/marketplace.json file that lists plugins and where to fetch each one. It is a catalog, not a store. You add a marketplace once, then install from it by name, such as commit-commands@claude-plugins-official.

Make a plugin when you want to:

• give the same skills, agents and hooks to teammates without each of them copying files,
• use one setup across many repositories,
• ship versioned releases, so people move to a new version on purpose,
• require a setup across a company through managed settings.

Install a plugin when someone else has already built what you need and you have read what it runs.

Stay with plain files when the setup serves one project, which belongs in that repo's .claude/ folder, or only you, which belongs in ~/.claude/. One MCP server needs only claude mcp add. A single skill needs only a folder. Packaging adds a manifest, a marketplace and a release step, so do it when sharing is the problem.

Two limits shape the decision. Cloud sessions, including routines and claude.ai/code, do not install the plugins a repository enables in .claude/settings.json or the plugins in your user settings. And the same plugin folder installs on claude.ai and in Cowork with a different subset of components: a local stdio MCP server does not run on claude.ai, and claude.ai and Cowork refuse a plugin with a top-level bin/ folder.

A plugin reaches a session in three layers. Your settings list the marketplaces you added and the plugins you enabled. The disk holds what Claude Code fetched, under ~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/. And each session loads the enabled plugins at startup, or when you run /reload-plugins.

An enabled plugin is part of every session, not only the ones where you use it:

• Context. The name and description of each skill, agent and command that Claude can invoke on its own sit in context on every turn. Full text loads only when used.
• Processes. Its MCP servers run alongside the session, and its hooks fire on their events.
• Permissions. What the plugin runs, it runs as you, with your user privileges.

Check the footprint before and after you install. In /plugin, plugins from Anthropic's official marketplace show a context cost estimate. After installing, claude plugin details <name> prints the tokens the plugin adds to every session, and the Installed tab groups plugins you have not used recently.

Claude Code adds Anthropic's official marketplace, claude-plugins-official, the first time you start an interactive terminal session, unless a managed policy blocks it. Marketplace names that look like Anthropic's are accepted only from github.com/anthropics/ repositories, so a third-party catalog cannot pose as an official one. A coworker's marketplace is third-party, and so is your organization's.

GitHub Copilot and Cursor document plugin systems and marketplaces of their own, and both describe an Agent Plugins 1.0 format whose skills and MCP configuration other compatible clients can read. OpenAI distributes skills and connectors for ChatGPT and Codex as plugins too. Claude Code's docs describe its own .claude-plugin/plugin.json format, so check each tool's docs before you assume a plugin carries over. The skills inside a plugin follow the open Agent Skills format and are the most portable part.