How to Use Claude Code Plugins (Install from a Marketplace or Build Your Own)

My Claude Code setup took months to accrete: a review command here, a formatting hook there, an MCP server for the database, a subagent for QA. Then I started a second project and discovered the setup didn’t come with me — it was smeared across four config surfaces in the first repo, and “install my tooling” meant a twenty-minute archaeology dig through my own dotfiles. Plugins are Claude Code’s answer to exactly that problem: one directory that bundles all of it, installable with one command.

What a plugin actually is

A plugin is a folder with a manifest. Inside it, the same primitives you can already wire up by hand, packaged to travel together:

• Skills and commands — the prompt templates behind /name invocations, the same format as a custom slash command
• Agents — subagent definitions that show up in /agents
• Hooks — lifecycle event handlers, same schema as Claude Code hooks in your settings, just living in hooks/hooks.json
• MCP servers — a bundled .mcp.json, so installing the plugin connects the tools without anyone running claude mcp add

Plugins can also carry LSP servers for code intelligence, background monitors, and executables — but the four above are the ones you’ll actually package first.

The one behavioral difference from hand-wired pieces: namespacing. A skill named hello in a plugin named my-plugin is invoked as /my-plugin:hello, not /hello. That’s deliberate — two plugins can both ship a deploy skill without colliding. Your own standalone .claude/ files keep their short names.

Install one from a marketplace in two minutes

A marketplace is a catalog — a repo or URL that lists plugins and where to fetch them. Using one is a two-step deal: add the catalog, then install individual plugins from it. Think app store: adding the store installs nothing.

Anthropic’s official marketplace (claude-plugins-official) is registered automatically. Run /plugin inside a session and you get a tabbed manager — Discover, Installed, Marketplaces, Errors, cycled with Tab. Browse Discover, hit Enter on a plugin, and the details pane shows what it contains, its context cost in tokens, and a “Will install” inventory before you commit.

Or skip the browsing and install directly:

/plugin install github@claude-plugins-official

For third-party catalogs, add the marketplace first. The community marketplace — where reviewed third-party submissions land, each pinned to a specific commit — is the obvious second stop:

/plugin marketplace add anthropics/claude-plugins-community
/plugin install some-plugin@claude-community

/plugin marketplace add accepts a GitHub owner/repo shorthand, a full git URL (include the https:// and the .git), a local directory, or a direct URL to a hosted marketplace.json.

Installing prompts you for a scope:

• user — you, across all projects (the default)
• project — written to .claude/settings.json, so everyone who clones the repo gets it
• local — this repo only, gitignored

Then activate without restarting:

/reload-plugins

That’s the full loop. The plugin’s skills now show up under their namespace — install commit-commands from Anthropic’s demo marketplace and you get /commit-commands:commit.

Managing what you’ve installed

The day-to-day commands:

/plugin list                                # what's installed, grouped by scope
/plugin disable plugin-name@marketplace-name  # turn off without uninstalling
/plugin enable plugin-name@marketplace-name
/plugin uninstall plugin-name@marketplace-name
/plugin update plugin-name@marketplace-name   # pull a plugin update
/plugin marketplace update marketplace-name   # refresh a catalog

Everything also exists as a shell command (claude plugin install formatter@my-marketplace --scope project) for scripts and CI. Two things worth knowing before you accumulate a pile: removing a marketplace uninstalls every plugin you got from it, and every enabled plugin adds tokens to every session — claude plugin details <name> shows the projected cost, split into always-on and on-invoke. Audit occasionally; the Installed tab literally flags plugins you haven’t touched in weeks.

When a plugin beats hand-wiring each piece

Honest answer: not always. The decision is about distribution, not capability — a plugin can’t do anything the standalone pieces can’t.

Hand-wire when it’s one project, it’s just you, and you’re still iterating. Files in .claude/ are faster to edit, need no manifest, and keep short names. Every plugin in my own setup started life as a loose skill or hook I was still fiddling with.

Package a plugin when:

• Someone else needs your setup. The alternative is a README that says “create these four files, paste this JSON, run these three commands.” A plugin turns that into one install — and the MCP servers, hooks, and agents arrive pre-wired to each other.
• You need it in more than one repo. User-scope install once beats copying .claude/ folders around and watching them drift.
• You want versioned updates. Bump the version field, users get the update; your copied-folder users get nothing, forever.
• The pieces only make sense together. A deploy skill that calls a deploy MCP server guarded by a deploy hook is one product, not three configs. Shipping them separately invites the broken half-install.

The tell is the second consumer. The moment a setup has one — a teammate, your own second machine, a future you — packaging pays for itself.

Build your own: the anatomy

A minimal plugin is two files. The manifest lives at .claude-plugin/plugin.json:

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

name is the only required field — it becomes the namespace prefix. version is optional but load-bearing: set it and users only get updates when you bump it; omit it and the git commit SHA is the version, so every push ships. Set it for stable releases, omit it while iterating.

Components sit at the plugin root, not inside .claude-plugin/ — the number-one structural mistake, per Anthropic’s own docs. Only plugin.json goes in there:

my-plugin/
├── .claude-plugin/
│   └── plugin.json       # only the manifest lives here
├── skills/
│   └── hello/
│       └── SKILL.md      # becomes /my-plugin:hello
├── commands/             # flat .md files, same format as custom slash commands
├── agents/               # subagent definitions
├── hooks/
│   └── hooks.json        # same schema as hooks in settings.json
└── .mcp.json             # bundled MCP servers

skills/ is the recommended layout for new plugins (each skill a folder with a SKILL.md); commands/ holds flat Markdown files in the older style. If you already have working pieces in a project’s .claude/ directory, migration is mostly cp -r — copy commands/, agents/, skills/ across, and move your hooks object out of settings.json into hooks/hooks.json, same shape.

One rule saves you a debugging afternoon: use ${CLAUDE_PLUGIN_ROOT} for every internal path in hook commands and MCP configs. Installed plugins are copied into a cache at ~/.claude/plugins/cache, not run from where the user cloned them — so relative paths that reach outside the plugin directory (../shared-utils) simply don’t exist after install. The variable always resolves to wherever the plugin actually landed.

Test locally, then validate

Point Claude Code at the directory — no marketplace, no install:

claude --plugin-dir ./my-plugin

Invoke your skill (/my-plugin:hello), check /agents for your agents, trigger your hooks. As you edit, /reload-plugins picks up changes mid-session. Before shipping, lint the whole structure:

claude plugin validate ./my-plugin

It checks plugin.json, skill and agent frontmatter, and hooks/hooks.json for schema errors — the same check Anthropic’s review pipeline runs on community submissions. There’s also claude plugin init my-tool, which scaffolds a manifest and starter skill under ~/.claude/skills/ that loads automatically next session — the fastest path from nothing to a working plugin skeleton.

Distribute it: a marketplace is one JSON file

To share, you publish a catalog. A marketplace is a repo with a .claude-plugin/marketplace.json listing your plugins:

{
  "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"
    }
  ]
}

source can be a relative path inside the same repo (the simple case: one repo, plugins/ folder, catalog at the root) or an object pointing at another GitHub repo, so one catalog can index plugins living anywhere. Test the whole flow locally before pushing:

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

Then push to GitHub and your users run /plugin marketplace add your-name/your-repo. For a team, go one step further: add the marketplace to the project’s .claude/settings.json under extraKnownMarketplaces, and Claude Code prompts every collaborator who trusts the repo to install the team plugins. That plus a committed CLAUDE.md file is the whole “onboard a new dev’s AI tooling” problem, solved in two files.

The security paragraph you shouldn’t skip

A plugin is code execution with your user privileges — hooks run shell commands, MCP servers are processes, and installing from a marketplace means trusting whoever controls that repo, including their future pushes. Anthropic verifies none of it for third-party sources. The same rules as any dependency: read the component inventory before installing, prefer pinned catalogs like the community marketplace, and be pickier about marketplaces than about plugins — the catalog decides what an update contains.

Where this fits

Plugins are the distribution layer for everything else in this cluster: the slash commands you templatize, the hooks that enforce your rules, the MCP servers that feed Claude real data, the subagents that parallelize the work. Once your setup is a plugin, it follows you to every project — which means the economics of running it everywhere start to matter. I keep the heavy drafting lanes on the z.ai GLM Coding Plan — that’s a referral link, it helps fund our compute, and the plan costs the same with or without it; setup walkthrough in how to set up Claude Code with the GLM API.

And the honest limit of packaging: a plugin makes instructions installable, not good. A bad prompt shipped to five repos is a bad prompt five times. The skill and agent bodies inside your plugin are system prompts, and writing those tight is its own craft — Meta-Prompt + System Prompt Architect ($8.99, one-time) is the skill I use to turn rough intent into the kind of precise, reusable, failure-aware instructions that are actually worth namespacing and shipping. Package the wiring with a plugin; make what’s inside worth installing.