Claude Code Plugins: From Personal Setup to Org Standard

The pattern shows up in every team that adopts Claude Code seriously. One engineer figures out a smart hook. Another builds an MCP server that wraps the internal docs API. A third writes a slash command for the deploy script. None of it travels. New hires inherit a blank .claude/ folder and a Slack thread of partial screenshots, and the team's productivity ceiling is whatever the original engineer remembers to write down that week.

Anthropic gave that failure mode a name in May 2026: tribal knowledge. The fix is a Claude Code plugin. A plugin bundles skills, hooks, MCP server configs, sub-agents, slash commands, and LSP definitions into one installable package. Run /plugin install, and a teammate's harness becomes yours, versioned, namespaced, and updatable when the maintainer ships v1.2. The skill your senior engineer wrote on a Sunday afternoon becomes installable on a new laptop by Monday morning.

That's the promise. The reality is more nuanced. Plugins are one of Anthropic's five extension points and the distribution component in the broader seven-part harness model. They are the only component whose value comes from distribution rather than runtime behavior. A plugin doesn't make Claude smarter. It makes a working setup shareable. That distinction shapes everything about how you build them, when you reach for them, and which patterns survive contact with a team larger than two people.

This guide covers what plugins contain, how the marketplace mechanism actually works, and how to move from a one-engineer harness to an org-wide standard without losing the engineer who built it. The reference implementation we keep coming back to is Cole Medin's helpline repo, which ships a runnable plugin under 200 lines of config. We've verified the install commands against his README so you can clone, install, and pick it apart in fifteen minutes.

Skim the AI layer overview first if you're new to the framework. The rest of this post assumes you know what hooks, skills, and MCP servers do separately, and focuses on the layer that ties them into something distributable.

What a Claude Code Plugin Actually Contains

A plugin is a directory with a manifest at .claude-plugin/plugin.json plus any harness components it ships. The manifest declares the plugin's name, version, and author. The rest of the directory holds the working parts.

Components you can bundle:

• Skills in skills/, each in its own folder with a SKILL.md
• Hooks in hooks/hooks.json, using the same schema as .claude/settings.json
• MCP servers declared in .mcp.json at the plugin root
• Sub-agents as .md files in agents/
• Slash commands as flat markdown in commands/
• LSP server configs in .lsp.json (for symbol-level search at scale)
• Background monitors in monitors/monitors.json that stream events into the session
• Default settings in settings.json

A plugin is the distribution unit for an entire workflow, not a single component. The MCP-only solutions in our recommended MCP add-ons roundup extend Claude with one external service at a time. A plugin can extend Claude with the service, the hook that formats its output, the skill that knows when to call it, and the agent that orchestrates the result, all in one command. ClaudeFast's Code Kit follows the same composition principle, shipping 18 agents wired to hooks, skills, and the /team-plan + /build pipeline as one integrated bundle.

One rule before building: only plugin.json goes inside .claude-plugin/. Everything else lives at the plugin root. Putting skills/ or hooks/ inside .claude-plugin/ is the most common first-time mistake, and Claude Code will silently fail to discover them.

The Plugin Manifest, Verbatim

Here is the minimum viable plugin.json Anthropic documents:

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

Four fields. name becomes the namespace prefix for every skill in the plugin, so a hello skill inside my-first-plugin is invoked as /my-first-plugin:hello. That namespacing is mandatory and prevents collisions when teammates install three plugins that each ship a /deploy skill.

The version field is optional but load-bearing. Set it, and users only receive updates when you bump the version. Omit it (and host in git), and the commit SHA becomes the version, so every push counts as a new release. Most teams settle on explicit semver after a few iterations to stop pushing breaking changes into every developer's session.

Optional fields like homepage, repository, license, and keywords follow the same shape as package.json. They show up in the plugin manager when users browse your marketplace.

How /plugin marketplace add Actually Works

Plugins distribute through marketplaces. A marketplace is a catalog at .claude-plugin/marketplace.json that lists plugins and where to fetch each one. The catalog can live locally, in a public git repo, or in a private repo your team owns.

The minimum catalog:

{
  "name": "my-plugins",
  "owner": { "name": "Your Name" },
  "plugins": [
    {
      "name": "quality-review-plugin",
      "source": "./plugins/quality-review-plugin",
      "description": "Adds a quality-review skill for quick code reviews"
    }
  ]
}

The source field accepts a relative path in the same repo, a GitHub object ({"source": "github", "repo": "owner/repo"}), a generic git URL, an npm package, or a git-subdir for monorepos where each team owns a folder.

Once the catalog exists, users add it and install:

/plugin marketplace add ./my-marketplace
/plugin install quality-review-plugin@my-plugins

The @my-plugins suffix names the marketplace, which disambiguates when two marketplaces ship a plugin with the same name. After install, skills are callable as /quality-review-plugin:quality-review.

Version pinning works on both layers. The catalog can pin a plugin to a specific commit SHA. The manifest can pin itself to a semver string. When you push an update, users run /plugin marketplace update to refresh the catalog and pull the new version.

Cole's Helpline as a Reference Implementation

Cole Medin's helpline repo ships a marketplace called helpline-tooling with one plugin called helpline-ai-layer. It exists as a reference, not a production tool, so you can clone it and read every file in an hour.

The exact install sequence from the repo README:

/plugin marketplace add /path/to/helpline/tooling
/plugin install helpline-ai-layer@helpline-tooling

That single install delivers four working pieces:

• A stop hook that runs after every Claude turn, spawns a headless Claude session, and proposes CLAUDE.md updates. We unpack the pattern in self-improving CLAUDE.md.
• An explorer sub-agent for read-only codebase mapping. Anthropic's framing is that you should never explore and edit in the same session; the explorer encodes that discipline. See agent fundamentals for why context isolation matters.
• A codebase-search MCP server that exposes AST-based structured search, not raw grep. Cole's demo runs find_definition and find_references queries in seconds where grep returns thousands of irrelevant hits.
• A scoped-tests skill as an example of layout-agnostic skill design. The skill works without assuming a specific test runner or directory structure.

Cole's own framing in the README: "Consider this plugin a starting point if you want to quickly pull in these things to experiment on your own codebase." That's the right way to read any reference plugin. You install it, run a session, dig into the hook script that interests you, and rip out the rest.

Building Your First Plugin

The fastest path from zero to a working plugin is converting something that already lives in .claude/. Most teams have one good skill or one useful hook; the plugin wrapper takes about twenty minutes.

Start with the directory layout:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── code-review/
│       └── SKILL.md
├── hooks/
│   └── hooks.json
└── .mcp.json

Reuse plugin.json from above. The skill is whatever you already have in .claude/skills/code-review/SKILL.md, copied over without modification. The hooks.json uses the same schema as the hooks block in .claude/settings.json, so copy that block verbatim. See the Claude Code hooks guide for the schema details.

The .mcp.json file looks identical to the format in the MCP basics guide, with one wrinkle: paths inside the file resolve relative to the plugin's cache location, not your project root. If your MCP server needs a config file shipped with the plugin, reference it with ${CLAUDE_PLUGIN_ROOT} so it resolves correctly on every install.

Test locally before pushing to a marketplace:

claude --plugin-dir ./my-plugin

That loads the plugin into a single session without installing it. After every edit, run /reload-plugins to pick up changes. Check that skills appear under the plugin namespace (/my-plugin:skill-name), that agents show up in /agents, and that hooks fire as expected.

You can also test against a packaged .zip or a remote URL via --plugin-url. The remote variant is useful for testing what users will actually receive after install.

Plugin Distribution Patterns

Three patterns cover almost every real-world deployment.

Internal-only via private git. Host marketplace.json in a private GitHub or GitLab repo. Users add it with /plugin marketplace add your-org/your-marketplace. Access control falls back to whatever the git host already enforces. Default pattern for any company that doesn't want its harness in public.

Public open-source marketplace. Push to a public repo, add an MIT or Apache license, and people install with /plugin marketplace add pointed at your slug. Anthropic runs two public catalogs: claude-plugins-official (curated, available by default in every install) and claude-community (third-party submissions after review). The community marketplace adds with /plugin marketplace add anthropics/claude-plugins-community, with plugins installed via the @claude-community suffix.

Hybrid open-core. Open-source the base plugin publicly, then ship a private marketplace with the team-specific extensions. The base gets community battle-testing; the private extensions encode org-specific conventions, secrets, and proprietary MCP servers. Most companies that ship developer tooling externally end up here within six months.

The right pattern depends on what's in the harness. A plugin that wraps your internal incident-response MCP server stays private. A plugin that ships a generic git-history skill can go public and earn you a few stars.

Versioning and Updates

The version field controls when developers receive updates. Three modes.

Explicit semver. Set "version": "1.2.0" in plugin.json. Users get new code only when you bump and they run /plugin marketplace update. Safest pattern once your plugin has more than a handful of users.

Commit-SHA versioning. Omit the version field. Every commit becomes a new "version." Fine for solo work, risky with teammates.

Marketplace-level pinning. The catalog can override the manifest by pinning a plugin entry to a specific commit SHA via the sha field on the source. Anthropic's community marketplace works this way: CI pins each approved plugin to a commit, and the pin updates only after re-review.

For rollback, the catalog is the lever. If v1.3 breaks something, edit the entry back to v1.2's SHA, push, and users get the older code on next session start.

Plugin vs Skill vs Agent vs MCP Server

The taxonomy trips up nearly every first-time plugin author:

• Skill: one workflow. A markdown file plus optional scripts Claude loads on demand. See the skills primer and our comparison of the best Claude Code skill repos for how standalone packs differ from integrated bundles.
• Sub-agent: a configured persona with its own context window. It can use skills, but the agent is the actor; the skill is the playbook.
• MCP server: an external tool accessed through a standardized protocol, exposing callable tools to the model.
• Plugin: a bundle of any of the above plus hooks, LSP configs, and slash commands. The distribution unit; everything else is a component.

When to reach for which:

• New workflow for personal use: skill in .claude/skills/
• Workflow worth sharing across one team: plugin with that single skill
• External service Claude needs to call: MCP server
• Specialist persona for a recurring task type: sub-agent, optionally bundled in a plugin
• Install in one command for ten teammates: plugin

Treat plugins as "just bigger skills" and the mental model collapses. A plugin is closer to an npm package: version, manifest, namespace, marketplace, update mechanism. If your thing doesn't need any of that, ship it as a standalone skill and save the manifest.

The Tribal Knowledge to Org Standard Path

The lifecycle Anthropic documented is straightforward in the abstract and surprisingly difficult in practice.

1. One engineer builds a working personal setup. The harness as it lives in .claude/ on one machine. A stop hook, a custom MCP, three skills. It works because the author knows when to use each piece.
2. Package as a plugin. Wrap the pieces in plugin.json, add marketplace.json, push to a private repo. Two hours the first time, twenty minutes after.
3. Roll out to one team. Five to ten developers install and use it for a sprint. The author runs office hours, fixes what breaks, and documents the assumptions that didn't survive contact with other developers.
4. Expand based on feedback. Cut the skills nobody uses. Rewrite the descriptions that were too vague. Debounce the hook that fires every fifteen seconds during a refactor.
5. Standardize. The plugin becomes the team's baseline. New hires install on day one. The maintainer role is what the agent manager post calls a DRI, even if the title is unofficial.

Step three is the killer. Most plugins die between "works on the author's machine" and "works for five other engineers" because the author treated their own conventions as universal. Path-scoped skills help here: scope every behavior to the directories where it makes sense, and the plugin gets safer to install in repos the author has never seen.

Where Plugins Sit in the Harness

Plugins are explicitly the distribution layer for everything else. CLAUDE.md governs conventions, hooks automate behavior, skills load workflows, MCP servers expose external tools, LSP gives symbol search, sub-agents split context, and plugins bundle the lot for shipping.

The ordering matters. You don't start with a plugin. You build the harness piece by piece, run it on your own work for a few weeks, find what survives, then package the survivors once the pattern stabilizes. Building the plugin first usually means shipping someone else's bad ideas on day one.

That's also the honest read on why most teams need a starting point. The current state of the art is "build it yourself, and good luck." We built ClaudeFast's Code Kit on the same logic: a curated harness shipping 18 specialized agents, 167 skill files across 21 categories, the SkillActivation hook, the ContextRecovery hook, and the /team-plan + /build pipeline as one integrated system. Not literally a Claude Code plugin yet (the harness predates the plugin spec by several months), but it occupies the same conceptual slot: the curated harness, like a plugin but with team orchestration baked in.

Common Pitfalls

A few traps catch nearly every first-time author.

Putting components inside .claude-plugin/. Only plugin.json lives there. Skills, hooks, agents, MCP configs all go at the plugin root. The error mode is silent.

Forgetting the namespace. Plugin skills are always invoked as /plugin-name:skill-name. If a skill works in .claude/skills/ locally but breaks after packaging, the invocation path changed. Update cross-references in CLAUDE.md and sub-agent definitions.

Hard-coding paths. Plugins get copied to ~/.claude/plugins/cache after install. A hook with cd /Users/you/repos/your-plugin works for you and breaks for everyone else. Use relative paths or ${CLAUDE_PLUGIN_ROOT}.

Shipping secrets. An MCP server with an API key baked into the config is a credential leak waiting to happen. Reference environment variables instead.

Treating commit-SHA versioning as permanent. Fine for prototyping. The moment you have teammates, switch to explicit semver, or every merge becomes an unannounced update to every developer's session.

The Direction This Is Heading

Anthropic ships two public marketplaces today, and the submission pipeline pins approved plugins to specific commits. The community catalog syncs nightly. That infrastructure didn't exist nine months ago, and the fact that it shipped before most engineering orgs have a single plugin in production tells you which way this is moving.

Expect more first-party marketplaces curated by tool vendors (the language LSP plugins are an early example), more skills shipped in plugin form by default, and some convergence around versioning conventions across orgs over the next twelve months. The harness matures fastest when there's a public distribution mechanism for the components.

If you're starting from zero: build the pieces in .claude/, package the survivors once patterns stabilize, ship to a private marketplace, then decide later whether any of it belongs in public. Or pick up the Code Kit for $89, get the curated harness preconfigured, and spend the plumbing time on actual work.

A harness that lives on one developer's machine is a liability. A harness that installs in one command is leverage. Plugins are the cheapest way to cross that line.