Shared Context

How Claude Plugins Work

Claude Code's plugin system bundles skills, agents, MCP servers, and hooks into a single installable directory. Here's the anatomy of a plugin, how marketplaces distribute them, and where Shared Context fits in.

Why plugins exist

A real team workflow rarely fits in one primitive. A "PR review" workflow might want a review skill, a code-review sub-agent, an MCP that reaches the issue tracker, and a hook that blocks merge if checks fail. Asking users to install four things from four places is friction; a plugin is the box that holds them.

Claude Code introduced its plugin system in late 2025. The shape is intentionally simple: a folder, a manifest, conventional sub-folders, and a marketplace that lists what's available.

Anatomy of a plugin directory

A Claude plugin is a directory containing a .claude-plugin/plugin.jsonmanifest plus any of the standard subdirectories the host knows how to read:

my-plugin/
├── .claude-plugin/
│   └── plugin.json        # name, version, description, author
├── skills/
│   └── review-pr/
│       └── SKILL.md       # individual skill
├── agents/
│   └── researcher.md      # sub-agent definition
├── hooks/
│   └── hooks.json         # lifecycle event handlers
├── .mcp.json              # MCP server configurations
└── scripts/               # shell scripts referenced by hooks

The plug-in host scans this layout on install. Skills and agents become discoverable; hooks register against their declared events; MCP entries get merged into the user's global MCP config so the servers boot on next session. Any of those subdirectories is optional — a plugin can be skills-only, hooks-only, or any combination.

The manifest

The minimum:

{
  "name": "my-plugin",
  "version": "1.0.5",
  "description": "What this plugin does in one line.",
  "author": { "name": "Example Org" }
}

Optional fields cover homepage URL, tags, required Claude version, and license. Versions usually follow 1.0.<commit-count> in tooling that auto-publishes from a Git history; the manifest is a snapshot of the build, not hand-edited.

Hooks-with-paths trick

Hooks that reference scripts inside the plugin use ${CLAUDE_PLUGIN_ROOT} as a placeholder for the install location. The host resolves it at run time so the hook works regardless of where the user installed the plugin.

Marketplaces

A marketplace is a server that lists plugins and points to the directory each one lives in. Claude Code uses simple HTTPS endpoints — there is no proprietary registry. Run claude plugin marketplace add <url>; the host fetches a JSON listing of available plugins; claude plugin install <name> pulls the plugin into your local install location.

Three categories of marketplace exist in practice:

  • Anthropic's own. Curated, narrow, signed.
  • Public GitHub-backed. Each plugin lives in a Git repository with the standard layout. The marketplace is a single JSON file pointing at those repos. Easy to host (a static file on a CDN), no auth required for public content.
  • Private team or org marketplaces. Same pattern, but the marketplace and the plugin repos live behind authentication. Companies use these for proprietary workflows.

Where Shared Context fits

A collection on Shared Context can be exported as a valid Claude plug-in directory by appending ?format=plugin to its public URL. The server synthesises a plug-in manifest from the collection metadata, restores the YAML front matter to skill files, aggregates hooks into the standardhooks/hooks.json shape, and merges MCP configurations into a single.mcp.json. The user gets one zip; the host treats it like any other plugin.

For private org libraries the same path works behind authentication, which is why most teams use a layer like Shared Context rather than running the public Claude marketplace flow directly: the auth, the cross-platform install (Cursor, Gemini, Codex use different on-disk shapes), and the version tracking are all problems somebody has to solve.

Cross-platform reality

The Claude plugin spec is the most mature today. Cursor, Gemini CLI, and Codex are catching up — each treats the same primitives slightly differently, and a "plugin" installed on three tools usually means three slightly-different on-disk layouts. Shared Context's CLI hides this by mapping the canonical shape to each platform's native directory at install time.

Anthropic's plug-in documentation at docs.claude.comis the canonical reference for the Claude side. For the underlying primitives that gointo a plugin, see Skills vs Agents vs MCPs vs Hooks.

When to package as a plugin vs ship loose

Loose skills are easier — one file, one purpose. A plugin pays off when the constituent pieces have to ship together: a hook that depends on a skill, a sub-agent whose system prompt assumes a particular MCP is connected, a workflow that spans three primitives. For anything below that threshold, prefer a single skill or a small collection over the ceremony of a full plugin.

If you want to try it

Browse the collections hub — every published collection on Shared Context can be served as a Claude plug-in directory. Install one via the CLI on any of the four supported tools and you'll see the install flow at work.