# How to Create a Claude Code Plugin, Step by Step

A Claude Code plugin is a folder of skills, subagents, hooks and MCP servers with one manifest file, `.claude-plugin/plugin.json`, that names it. Claude Code loads the folder as one unit, so you can hand your whole setup to a teammate, install it in every project, or publish versioned releases.

This guide builds one from an empty folder, tests it without publishing, then lists it in your own marketplace. Everything here was checked against Anthropic's [create a plugin](https://code.claude.com/docs/en/plugins/create) and [publish](https://code.claude.com/docs/en/plugins/publish) docs on 2026-10-25. Claude Code changes fast, so re-check anything you depend on.

We also ship our own plugin, [agentkit-dev-skills](https://github.com/agentkitco/agentkit-dev-skills), and got it rejected from a community directory twice before it went through. Those lessons are at the end.

## Do you even need a plugin?

Probably not, at first. A skill in `~/.claude/skills/` already works in every project on your machine, and hooks, subagents and MCP servers all work standalone. The docs put it plainly: keep the standalone setup while it serves one project or only you. Make a plugin when you want to share it, install it in several projects, or ship versions.

One cost to know: an enabled plugin is part of every session. The name and description of each skill and agent Claude can invoke on its own sit in context on every turn, and its MCP servers and hooks run in every session where it's enabled. Keep descriptions short and ship only what people will use.

## 1. Create the folder and the manifest

```bash
mkdir -p my-plugin/.claude-plugin
```

Save this as `my-plugin/.claude-plugin/plugin.json`:

```json
{
  "name": "my-plugin",
  "displayName": "My Plugin",
  "description": "Code review and release helpers for our team",
  "version": "1.0.0",
  "author": { "name": "Your Name" },
  "license": "MIT"
}
```

- `name` is the only required field. It becomes the prefix on every skill and agent, so a skill called `review` runs as `/my-plugin:review`. Use kebab-case and treat it as permanent: users install by `name@marketplace`, so a renamed plugin is a different plugin to every existing install.
- `displayName` is the label people see, so you can change the wording without renaming.
- `version` is optional. If you set it, users stay on that version until you change it (more on this below).
- `homepage`, if you add one, must parse as a URL or the plugin fails to load.

The rule people trip on most: **only `plugin.json` goes inside `.claude-plugin/`.** Skills, agents and hooks saved in there don't load.

## 2. Add components at the plugin root

```text
my-plugin/
  .claude-plugin/plugin.json
  skills/review/SKILL.md
  agents/reviewer.md
  hooks/hooks.json
  .mcp.json
```

Add only the folders you use. A skill is a folder with a `SKILL.md`:

```markdown
---
name: review
description: Review the staged diff for bugs, missing tests and risky changes. Do not use for formatting-only changes.
disable-model-invocation: true
---

Run `git diff --staged`. List real bugs first, then missing tests, then risky changes. Skip style nits.
```

`disable-model-invocation: true` means Claude only runs it when you type the command. Drop that line for skills you want Claude to pick up on its own. Use `skills/` for new plugins; the flat `commands/` folder is the older form.

`hooks/hooks.json` has a top-level `"hooks"` key with the same shape as `hooks` in a settings file. Refer to your own scripts through `${CLAUDE_PLUGIN_ROOT}`, and wrap it in double quotes, because an unquoted path breaks when the install folder has a space in it:

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/format.sh" }]
      }
    ]
  }
}
```

`.mcp.json` uses the same format as a project `.mcp.json`, with `${CLAUDE_PLUGIN_ROOT}` for paths to bundled servers. Our [.mcp.json examples](https://agentkitco.com/blog/claude-code-mcp-json-examples/) and [hooks examples](https://agentkitco.com/blog/claude-code-hooks-examples/) have configs you can copy in.

## 3. Validate

```bash
claude plugin validate ./my-plugin
```

A clean run prints `✔ Validation passed`. Otherwise each line above `✘ Validation failed` names the field to fix. Add `--strict` in CI so warnings, such as an unknown manifest field or a missing `version`, fail the build too. The validator also checks every skill and agent's frontmatter and, on recent versions, `.mcp.json`.

## 4. Test without publishing

```bash
claude --plugin-dir ./my-plugin
```

Then run `/my-plugin:review`. `--plugin-dir` loads the plugin for that session only and also accepts a `.zip`. After editing files on disk, run `/reload-plugins` instead of restarting.

If something is missing, check in this order:

1. `/plugin`, **Errors** tab: shows things like `skills path not found`.
2. Skills missing but the plugin loads? Your `skills/` folder is probably inside `.claude-plugin/`. Move it to the root.
3. Pointed `--plugin-dir` at a marketplace repo? It takes the plugin's own root, the folder holding `.claude-plugin/plugin.json`.
4. MCP server not showing? Run `/mcp`. A server entry that fails the schema is dropped quietly, and `claude plugin validate` is the fastest way to find it.

## 5. Already have a .claude/ setup? Convert it

Create `my-plugin/.claude-plugin/plugin.json`, then copy what you have:

```bash
cp -r .claude/skills .claude/agents .claude/commands my-plugin/
```

Move the `hooks` object from `.claude/settings.json` into `my-plugin/hooks/hooks.json` unchanged. Test with `--plugin-dir`, then delete the originals. Until you do, skills and agents show up twice (as `/deploy` and `/my-plugin:deploy`), and hooks run twice, because hooks have no prefix.

## 6. Publish through your own marketplace

A marketplace is just a `.claude-plugin/marketplace.json` in a git repo. There's no submission form. To publish from the plugin's own repo, put it next to `plugin.json` with `source` set to the repo root and the same `name` as the manifest:

```json
{
  "name": "my-marketplace",
  "owner": { "name": "Your Name" },
  "plugins": [
    { "name": "my-plugin", "source": "./" }
  ]
}
```

Run `claude plugin validate .` before you push. Users then install with:

```bash
claude plugin marketplace add your-org/your-repo
claude plugin install my-plugin@my-marketplace
```

A private repo makes a private marketplace: anyone who can clone it can install.

**Versioning trap:** if you set `version` and push new commits without bumping it, `claude plugin update` tells users they're already on the latest version and they keep the old copy. Either bump `version` on every release, or leave it out in a git-hosted marketplace so Claude Code uses the commit SHA.

## What our directory rejections taught us

We submitted agentkit-dev-skills to a community plugin directory and it came back twice:

1. **No `plugin.json`.** The first version was a bare folder of skills. The directory wanted a real manifest, even though Claude Code will load a folder without one. Ours now has name, displayName, version, description, author, homepage, repository, license and keywords.
2. **Skills that act without asking.** The second review asked that skills treat changelogs and instruction files as data rather than commands, and that our dependency-upgrade skill show the target version and files it would touch, then wait for a yes. That's good practice for any plugin: a plugin runs as the user, so anything that edits, installs or deletes should stop and confirm first.

We also added a "Do not use for" line to each skill description. It keeps Claude from firing the wrong skill, which matters more once a plugin is loaded in every session.

## Quick checklist

1. Kebab-case `name` you'll never change, plus `displayName`.
2. Only `plugin.json` inside `.claude-plugin/`; everything else at the root.
3. Short skill descriptions with a "Do not use for" line.
4. `"${CLAUDE_PLUGIN_ROOT}"` (quoted) in hooks and MCP paths.
5. `claude plugin validate --strict` passes.
6. Tested with `--plugin-dir` and `/reload-plugins`.
7. `marketplace.json` entry name matches the manifest.
8. Version bumped on every release, or omitted.

Want a finished example to read? Install our free [AgentKit Dev Skills](https://agentkitco.com/skills/), 13 MIT-licensed skills packaged exactly this way. If you're setting up the files a plugin sits next to, the [Agent Config Kit](https://agentkitco.com/products/agent-config-kit/) has drop-in AGENTS.md, CLAUDE.md and `.claude/rules` templates for 12 stacks, and [Agent Skills and SKILL.md explained](https://agentkitco.com/blog/agent-skills-skill-md-explained/) covers the skill format in more depth.

---

*Originally published at [agentkitco.com](https://agentkitco.com/blog/how-to-create-a-claude-code-plugin/). Disclosure: I run AgentKit Co, which makes the free skills and paid kit linked above.*

