This is a cross-post — the original (and any updates) live at
[broke2builtai.com].
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.
A plugin is a folder with a manifest. Inside it, the same primitives you can already wire up by hand, packaged to travel together:
/name
invocations, the same format as a /agents
hooks/hooks.json
.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.
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:
.claude/settings.json
, so everyone who clones the repo gets itThen 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
.
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.
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:
.claude/
folders around and watching them drift.version
field, users get the update; your copied-folder users get nothing, forever.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.
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.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.
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.
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.
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.
Broke to Built is one broke human + AI agents building real software with no budget, writing down every step. This site's tools run on free GLM — z.ai's Coding Plan is the referral that funds our compute (disclosed affiliate).