Guides ·
How to build and distribute a Claude Code plugin — bundle skills and agents into a one-line install
A Claude Code plugin bundles skills, subagents, hooks and MCP servers into one folder. What goes in plugin.json, how to test with --plugin-dir, how to check it with claude plugin validate, how to distribute through marketplace.json, and an example of shipping it all from one repo.
A Claude Code plugin is a folder that bundles skills, subagents, hooks and MCP servers into one unit. The manifest is .claude-plugin/plugin.json, and the only required field is name. skills/, agents/, hooks/hooks.json and .mcp.json go at the plugin root, not inside .claude-plugin/. Plugin skills are called as /plugin-name:skill-name. While building, load it for a single session with claude --plugin-dir and check it with claude plugin validate. There are three ways to distribute: hand over the folder or a .zip, your own marketplace (a git repo containing .claude-plugin/marketplace.json), or submitting to the Anthropic directory. Users install with claude plugin marketplace add owner/repo followed by claude plugin install name@marketplace. If you set version, you must bump it on every release for updates to reach users.
Claude Code: A Hands-On Guide · Part 6 of 10
The short version: a plugin is packaging that bundles skills, subagents and hooks into one folder so other people can install them with one command. Put .claude-plugin/plugin.json at the top of the folder, and folders like skills/ and agents/ next to it. To distribute it, add one more file, marketplace.json, to the git repo that holds the folder, and you're done. This post was written by AI (Claude) and checked against the official Claude Code docs — Plugins and the pages under it.
When to make a plugin
Skills, subagents, hooks and MCP servers all work without a plugin. The skills from part 5 work in all your projects if you put them in ~/.claude/skills/. The official docs draw the line like this:
- Just you, in one project → leave them as they are
- Sharing with a team, installing across projects, or shipping with a version number → bundle them into a plugin
Two things change when you move them into a plugin. The files move under the plugin folder, and the plugin name is prefixed to their names. A hello skill becomes /my-plugin:hello. So two plugins can have skills with the same name without clashing.
There is a cost too. An enabled plugin comes into every session. Its skills' and agents' names and descriptions go into context on every turn, and its hooks run on every event. All of it runs with your permissions.
Folder layout
The top folder of a plugin is called the "plugin root." Only create the folders you use.
| Location | Contains |
|---|---|
.claude-plugin/plugin.json |
The manifest (name, description, version, etc.) |
skills/<name>/SKILL.md |
Skills. One per folder |
agents/<name>.md |
Subagents. One per file |
hooks/hooks.json |
Hooks configuration |
.mcp.json |
MCP server definitions |
commands/ |
Old-style commands. Use skills/ for new ones |
Two things the official docs flag as warnings:
- Only
plugin.jsongoes inside.claude-plugin/. Putskills/in there and it won't load. This is a common cause of "the plugin shows up but the skills don't." - A
CLAUDE.mdat the plugin root is not read. Put instructions in skills.
plugin.json fields
From the official docs: the manifest is optional, and if you write one, the only required field is name. Without a manifest, whatever is found in the default folders is loaded, and the name comes from the folder name (or the marketplace entry).
| Field | What it controls |
|---|---|
name |
Plugin identifier. kebab-case. Prefixed to every skill and agent name |
displayName |
Name shown on screen instead of name. Spaces allowed |
version |
Version string. If set, users stay on that version until you change it |
description |
Description shown in /plugin |
author |
name required, email and url optional |
homepage |
Docs URL. If it doesn't parse as a URL, the plugin won't load |
repository, license, keywords |
Repo address, SPDX license (MIT etc.), search tags |
userConfig |
Values to ask the user for when enabling (use sensitive: true for tokens) |
The skills, agents, hooks and mcpServers fields can point to locations other than the default folders. Paths are relative to the plugin root, must start with ./, and the plugin won't load if .. points outside the root.
Unknown top-level fields are dropped without an error, and validation only shows a warning.
Build your first plugin and run it
This is the order of the first example in the official docs.
mkdir -p my-first-plugin/.claude-plugin
mkdir -p my-first-plugin/skills/hello
my-first-plugin/.claude-plugin/plugin.json:
{
"name": "my-first-plugin",
"description": "A greeting plugin to learn the basics",
"version": "1.0.0",
"author": { "name": "Your Name" }
}
skills/hello/SKILL.md is a skill file exactly like the ones in part 5. Now validate it and load it.
claude plugin validate ./my-first-plugin
claude --plugin-dir ./my-first-plugin
If validation passes, it prints ✔ Validation passed. Once the session starts, type /my-first-plugin:hello.
--plugin-dirloads the plugin for that session only and writes nothing to your settings. A.zipworks instead of a folder too.- If you edited files during the session, type
/reload-plugins. - If it doesn't show up, check the Errors tab in
/plugin. Missing paths show aspath not found.
If you already built things in .claude/
Copy skills, agents and commands from under .claude/ to the plugin root, and move the hooks block from settings.json into hooks/hooks.json in the same shape. One caution: until you delete the originals, hooks run twice, because hooks have no plugin-name prefix to tell them apart. Confirm the plugin works, then delete the originals.
Three ways to distribute
| Route | Who installs | Updates |
|---|---|---|
Hand over the folder or a .zip |
Whoever receives it | None. They keep the copy they got |
| Your own marketplace | Anyone with access to the repo (private repos work) | When the user runs claude plugin update, or has auto-update on |
| Submit to the Anthropic directory | People who add it in claude.ai or Cowork. It also reaches Claude Code via account sync | After the submitted version is published |
Directory submission requires a paid claude.ai plan and is done in the developer portal at claude.ai/directory/manage. The official marketplace (claude-plugins-official) does not take submissions through this portal.
Making a marketplace
A marketplace is a list, not a store. It is a folder or repo containing .claude-plugin/marketplace.json, where you write plugin names and where to fetch them from. The three required fields are name, owner and plugins, and each entry in plugins needs name and source.
Choose source based on where the plugin lives:
| source | When to use |
|---|---|
A relative path like "./plugins/my-plugin" |
The plugin is in the same repo |
github |
The plugin is its own GitHub repo |
git-subdir |
It's a subfolder of another repo (a monorepo) |
url, archive, npm, command |
Another git host, an HTTPS zip, an npm package, command output |
Relative paths are counted from the marketplace root, outside .claude-plugin/. The official docs say most install failures come from getting that base wrong, or from the entry's name not matching the name in plugin.json. Keep the two names the same.
After you push, users type two lines in their shell:
claude plugin marketplace add your-org/your-marketplace
claude plugin install deploy-helper@your-marketplace
The install ID is plugin-name@marketplace-name. From Claude Code v2.1.275, you can do both at once inside a session with /plugin install deploy-helper --marketplace your-org/your-marketplace.
Example: marketplace and plugin in one repo
This is a common layout when you're shipping a single plugin on your own. One repo is both the marketplace and the plugin's home. The example name is team-tools.
team-tools/
├── .claude-plugin/
│ └── marketplace.json (marketplace list)
└── plugin/ (plugin root)
├── .claude-plugin/
│ ├── plugin.json
│ └── icon.png
├── skills/review/SKILL.md
├── agents/ (checker.md etc.)
└── README.md
marketplace.json at the top of the repo:
{
"name": "team-tools",
"owner": { "name": "your-org" },
"plugins": [
{ "name": "team-tools", "source": "./plugin" }
]
}
plugin/.claude-plugin/plugin.json:
{
"name": "team-tools",
"displayName": "Team Tools",
"version": "0.1.0",
"description": "Review skill and checker agent for our team",
"author": { "name": "your-org" },
"license": "MIT",
"icon": "./.claude-plugin/icon.png",
"privacyPolicyUrl": "https://example.com/privacy"
}
Checked against the official docs:
- The plugin lives in a
plugin/subfolder. That's whysourceis"./plugin", and it doesn't mix with the repo's other code. - Both the marketplace entry and
plugin.jsonuse thenameteam-tools. The install ID becomesteam-tools@team-tools. - Agents get the plugin name prefixed, like
team-tools:checker. The skill is/team-tools:reviewtoo. Writing/reviewin the README is a common mistake. Plugin agents ignore thepermissionMode,hooks,mcpServersandinitialPromptfrontmatter, so put hooks and MCP servers at the plugin level. iconandprivacyPolicyUrlare fields Claude Code doesn't read. The Anthropic directory listing reads them. The official docs say to put these fields only inplugin.json, not in the marketplace entry.versionis set. So the number has to go up on every release (see the mistakes list below).
The install instructions in the README can be one line:
/plugin install team-tools --marketplace your-org/team-tools
On versions older than v2.1.275, type /plugin marketplace add your-org/team-tools and then /plugin install team-tools@team-tools separately.
Common mistakes
- Pushing without changing
version. Ifplugin.jsonhas aversionand you don't bump it,claude plugin updatesays "already up to date" and keeps the old copy. Bump it every release, or for a git marketplace, leaveversionout so the commit SHA is used as the version. - Renaming a published plugin's
name. Existing installs are recorded under the old name, so the plugin disappears. To change only the displayed name, usedisplayName; if you really must rename, userenamesinmarketplace.json. - Pointing
--plugin-dirat the marketplace root. This option doesn't readmarketplace.json. The plugin just doesn't load, with no error. Point it at a single plugin folder. - Hardcoding hook script paths. Install locations differ per person. Write it like
"${CLAUDE_PLUGIN_ROOT}"/scripts/format.sh. That path changes on updates, so keep data you want to persist in${CLAUDE_PLUGIN_DATA}. - Validating but never installing. A relative path to a folder that doesn't exist passes
validateand fails at install. Before sharing, install it yourself withclaude plugin marketplace add ./path.
FAQ
What is the difference between a plugin and a skill?
A skill is a single SKILL.md describing how to do a job, and a plugin is the packaging that bundles skills, subagents, hooks and MCP servers. Bundle them into a plugin when you share them with others or ship them with a version number.
What should I check before distributing?
Run claude plugin validate --strict ./your-plugin in your shell. --strict treats warnings as failures too. Run it on a marketplace folder and it also checks marketplace.json and the plugin.json of every relative-path plugin.
Can I put "claude" in the name?
A name starting with claude- or anthropic- fails validation with an error. Having it as a word in the middle, like mcp-for-claude, gives a warning. Marketplace names also can't use official names like claude-plugins-official.
Sources
- Claude Code docs — Plugins overview
- Claude Code docs — Create a plugin
- Claude Code docs — Plugin components
- Claude Code docs — Plugin manifest reference
- Claude Code docs — Create a marketplace
- Claude Code docs — Marketplace reference
- Claude Code docs — Publish and distribute a plugin
- How to create Claude Code skills (part 5)
- How to create Claude Code subagents (part 4)
Written with AI (Claude) and checked against the linked sources.