# 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.

- URL: https://aiweekly.app/en/blog/claude-code-plugins/
- Published: 2026-11-07
- Publisher: AI Weekly (https://aiweekly.app)

## Key takeaways

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.


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](https://code.claude.com/docs/en/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](https://aiweekly.app/en/blog/claude-code-skills/) 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.json` goes inside `.claude-plugin/`.** Put `skills/` in there and it won't load. This is a common cause of "the plugin shows up but the skills don't."
- **A `CLAUDE.md` at 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.

```bash
mkdir -p my-first-plugin/.claude-plugin
mkdir -p my-first-plugin/skills/hello
```

`my-first-plugin/.claude-plugin/plugin.json`:

```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.

```bash
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-dir` loads the plugin **for that session only** and writes nothing to your settings. A `.zip` works 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 as `path 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](https://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:

```bash
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`.

```text
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:

```json
{
  "name": "team-tools",
  "owner": { "name": "your-org" },
  "plugins": [
    { "name": "team-tools", "source": "./plugin" }
  ]
}
```

`plugin/.claude-plugin/plugin.json`:

```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:

1. **The plugin lives in a `plugin/` subfolder.** That's why `source` is `"./plugin"`, and it doesn't mix with the repo's other code.
2. **Both the marketplace entry and `plugin.json` use the `name` `team-tools`.** The install ID becomes `team-tools@team-tools`.
3. **Agents get the plugin name prefixed, like `team-tools:checker`.** The skill is `/team-tools:review` too. Writing `/review` in the README is a common mistake. Plugin agents ignore the `permissionMode`, `hooks`, `mcpServers` and `initialPrompt` frontmatter, so put hooks and MCP servers at the plugin level.
4. **`icon` and `privacyPolicyUrl` are fields Claude Code doesn't read.** The Anthropic directory listing reads them. The official docs say to put these fields only in `plugin.json`, not in the marketplace entry.
5. **`version` is 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:

```text
/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`.** If `plugin.json` has a `version` and you don't bump it, `claude plugin update` says "already up to date" and keeps the old copy. Bump it every release, or for a git marketplace, leave `version` out 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, use `displayName`; if you really must rename, use `renames` in `marketplace.json`.
- **Pointing `--plugin-dir` at the marketplace root.** This option doesn't read `marketplace.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 `validate` and fails at install. Before sharing, install it yourself with `claude 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](https://code.claude.com/docs/en/plugins)
- [Claude Code docs — Create a plugin](https://code.claude.com/docs/en/plugins/create)
- [Claude Code docs — Plugin components](https://code.claude.com/docs/en/plugins/components)
- [Claude Code docs — Plugin manifest reference](https://code.claude.com/docs/en/plugins/manifest-reference)
- [Claude Code docs — Create a marketplace](https://code.claude.com/docs/en/plugins/create-marketplace)
- [Claude Code docs — Marketplace reference](https://code.claude.com/docs/en/plugins/marketplace-reference)
- [Claude Code docs — Publish and distribute a plugin](https://code.claude.com/docs/en/plugins/publish)
- [How to create Claude Code skills (part 5)](https://aiweekly.app/en/blog/claude-code-skills/)
- [How to create Claude Code subagents (part 4)](https://aiweekly.app/en/blog/claude-code-subagents/)
