How to Create a Claude Code Plugin, Step by Step

Published 2026-10-25 · 6 min read · by AgentKit Co

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 and 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, 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

mkdir -p my-plugin/.claude-plugin

Save this as my-plugin/.claude-plugin/plugin.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

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:

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

{
  "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 and hooks examples have configs you can copy in.

3. Validate

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

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:

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:

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

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

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, 13 MIT-licensed skills packaged exactly this way. If you're setting up the files a plugin sits next to, the Agent Config Kit has drop-in AGENTS.md, CLAUDE.md and .claude/rules templates for 12 stacks, and Agent Skills and SKILL.md explained covers the skill format in more depth.

Keep reading