Claude Code Plugins Guide: Build, Install, and Publish (2026)

What Is a Claude Code Plugin?

A plugin is a directory with a .claude-plugin/plugin.json manifest that bundles every extensibility surface Claude Code exposes. Install one and you install all of it: skills, hooks, MCP servers, subagents, LSP configs, and background monitors.

According to the official Anthropic plugin docs, plugins are the distribution unit that replaces copy-pasting .claude/ folders between projects. Skills inside a plugin are namespaced (e.g. /my-plugin:review) so two plugins never collide.

VERSIONED

Semver releases

Each plugin ships with a version string. Users pin versions, upgrade on their timeline, and roll back when a release breaks something.

NAMESPACED

No skill collisions

Plugin name becomes the prefix. Install 20 plugins and you can still ship a /review skill in each without conflicts.

BUNDLED

Skills + hooks + MCP

One install ships the full integration: the skill that prompts Claude, the hook that enforces rules, the MCP server that exposes tools.

SHAREABLE

Marketplace install

Users install with one command from the official Anthropic marketplace or any community marketplace you add by git URL.

How to Install Claude Code Plugins

Claude Code ships with the official Anthropic marketplace (claude-plugins-official) connected by default. You get to browsing and installing in under five seconds.

Option 1: Interactive browser

/plugin

Opens the plugin manager. Tab to Discover, arrow through the catalog, hit enter to install. Installed plugins land in ~/.claude/plugins/ and work across every project.

Option 2: Direct install by name

/plugin install superpowers@claude-plugins-official

Faster if you already know the name. Format is plugin-name@marketplace-name. No restart required -- the skills load into the current session.

Option 3: Add a community marketplace

/plugin marketplace add owner/repo

Points at any GitHub repo, git URL, or local path. Anthropic does not review community marketplaces, so audit the code before installing anything that runs hooks or adds MCP servers.

Heads up: no auto-updates

The plugin system has no automatic update mechanism yet. Reinstalling a plugin pulls the latest version. Run /plugin install <name>@<marketplace> on a schedule if you need fresh versions.

Anatomy of a Plugin: Every File That Matters

A plugin is a directory. Only one file is required: the manifest at .claude-plugin/plugin.json. Everything else is optional and loads from known locations at the plugin root.

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # required manifest
├── skills/
│   └── review/
│       └── SKILL.md         # model-invoked capability
├── commands/                # user-invoked slash commands
├── agents/
│   └── reviewer.md          # subagent definition
├── hooks/
│   └── hooks.json           # PreToolUse, PostToolUse, etc
├── .mcp.json                # MCP server bundle
├── .lsp.json                # language servers
├── monitors/
│   └── monitors.json        # background watchers
├── bin/                     # executables added to PATH
├── settings.json            # default agent + statusline
└── README.md

The #1 plugin mistake

Do NOT nest skills/, hooks/, or agents/ inside the .claude-plugin/ directory. Only plugin.json goes there. Everything else lives at the plugin root. This is the single most common error in submitted plugins.

Minimum viable plugin.json

{
  "name": "my-plugin",
  "description": "Greets the user with a personalized message",
  "version": "1.0.0",
  "author": { "name": "Your Name" }
}

Field	Required	Purpose
name	Yes	Unique ID + skill namespace prefix
description	Yes	Shown in the /plugin browser
version	Yes	Semver string for release tracking
author	No	Attribution object with name + url
homepage	No	Docs / landing URL
repository	No	Git URL for source
license	No	SPDX identifier (e.g. MIT)

Build Your First Plugin in 4 Minutes

The fastest path to a working plugin: create a directory, add one manifest, add one skill, load it with --plugin-dir. No install, no publish, instant feedback.

STEP 1

Scaffold the plugin

mkdir -p code-reviewer/.claude-plugin
mkdir -p code-reviewer/skills/review
cd code-reviewer

STEP 2

Write the manifest

Save to .claude-plugin/plugin.json:

{
  "name": "code-reviewer",
  "description": "Opinionated code review for TypeScript PRs",
  "version": "0.1.0",
  "author": { "name": "Kai" }
}

STEP 3

Add the review skill

Save to skills/review/SKILL.md:

---
description: Review a PR against project conventions
---

Review the pull request at $ARGUMENTS for:
1. Type safety and error handling
2. Test coverage of new code paths
3. Adherence to project conventions in CLAUDE.md
4. Security concerns (SQL injection, XSS, auth)

End with a verdict: approve, request-changes, or comment.

STEP 4

Load and test

claude --plugin-dir ./code-reviewer

# Inside Claude Code:
/code-reviewer:review 42

Edit the SKILL.md, run /reload-plugins, iterate. No restart needed.

Level Up: Add Hooks, Subagents, and MCP Servers

Skills alone are a thin wrapper around prompts. The real power of plugins is bundling skills with the infrastructure that enforces them: hooks that run after every edit, subagents with tool restrictions, MCP servers that expose external data.

Bundle a hook

Drop hooks/hooks.json at the plugin root. The format matches settings.json hooks exactly.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix"
          }
        ]
      }
    ]
  }
}

Bundle an MCP server

Drop .mcp.json at the plugin root. Users who install your plugin get the server auto-configured.

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "@linear/mcp-server"],
      "env": { "LINEAR_API_KEY": "${LINEAR_API_KEY}" }
    }
  }
}

Bundle a subagent

Drop a markdown file in agents/reviewer.md with frontmatter describing when to use it. The main Claude thread can dispatch to it via the Task tool.

---
name: reviewer
description: Deep code review with filesystem and git access
tools: Read, Grep, Bash(git diff:*), Bash(git log:*)
model: claude-opus-4-7
---

You are a senior code reviewer. Focus on correctness, not style...

Plugin vs Skill vs MCP vs Slash Command

Claude Code exposes four extensibility surfaces. They overlap, and new users pick the wrong one. Here is when each fits.

Surface	Invoked by	Scope	Ship when
Slash command	User (typed)	One prompt	You want a reusable prompt
Skill	Claude (model)	One capability + files	Claude should auto-use it
MCP server	Claude (tools)	External system access	You need real API tools
Plugin	(container)	All of the above	You want to distribute a bundle

Rule of thumb: if you would be fine committing it to a single project's .claude/ directory, it is a standalone skill or command. If you want to ship it to teammates or publish it, wrap it in a plugin.

7 Plugin Patterns That Ship Work

These patterns come from real plugins running in the KaiShips agent stack. Each one solves a distinct problem. You can steal the shape.

1. Commit + PR workflow

Bundle /commit, /commit-push-pr, and /clean_gone slash commands with a PostToolUse hook that rejects commit messages missing the Co-Authored-By line.

2. Code review automation

A code-review skill plus a reviewer subagent with restricted tools (Read, Grep, git only). The skill delegates to the subagent so the main thread stays clean.

3. Playwright browser automation

Wraps the Playwright MCP server in a plugin with a browser-test skill that teaches Claude the viewport resize + snapshot dance. One install, full browser capabilities.

4. Security review gate

A security-review skill plus a PreToolUse hook that blocks git push on branches that have not been reviewed. The hook reads a marker file the skill writes.

5. Scheduled task runner

A schedule slash command that writes launchd plist files, plus a background monitor that tails the log and surfaces failures in the current Claude session.

6. CLAUDE.md management

A claude-md-improver skill that audits project CLAUDE.md files, plus a SessionEnd hook that proposes updates based on conversation learnings.

7. Discord bridge

Wraps a Discord MCP server plus skills for routing notifications. Cron-friendly: a notify command that every background agent can reach for status updates without re-wiring the MCP in each repo.

Publish Your Plugin

You have two paths to distribution: submit to the official Anthropic marketplace for discoverability, or host your own marketplace for control. Most plugins start self-hosted and submit to the official catalog after real-world validation.

OFFICIAL

Anthropic marketplace

●Submit at claude.ai/settings/plugins/submit
●Reviewed for quality and safety
●Installs with zero marketplace setup

COMMUNITY

Self-hosted marketplace

●Push to any public GitHub repo
●No review, ship whenever
●Users add with /plugin marketplace add

Pre-publish checklist

●Semver in plugin.json. Start at 0.1.0 for beta, bump to 1.0.0 once the API is stable.
●README with install command. Show the exact /plugin install string and at least one usage example per skill.
●No hard-coded secrets. MCP servers must pull credentials from env vars, not commit them to .mcp.json.
●Hooks documented. Any PreToolUse hook that blocks actions must be called out in the README so users are not surprised.
●Tested with a clean install. Run /plugin install in a fresh project before shipping. --plugin-dir testing misses path-dependent bugs.

The complete playbook

Every plugin pattern, manifest field, and distribution trick the KaiShips Guide to Claude Code ships to production.

This post covers plugins end to end. The full guide goes deeper into hook orchestration, MCP routing, subagent design, and cron automation across a 40+ plugin portfolio that runs the KaiShips $0 to $1M agent.

Get the KaiShips Guide to Claude Code -- $29

Mistakes That Break Plugins

Every pattern in this list has broken a plugin we shipped. Most are cheap to avoid once you know they exist.

Nesting directories inside .claude-plugin/

Only plugin.json lives there. Skills, hooks, agents, and MCP configs belong at the plugin root. The loader silently ignores anything nested incorrectly.

Forgetting to reload after edits

Editing SKILL.md or hooks.json does nothing until you run /reload-plugins. This burns an hour for every developer once.

Over-broad skill descriptions

Model-invoked skills trigger on description match. A description like "help with code" fires on every message. Be specific: name the trigger conditions and the expected inputs.

Colliding plugin names

Plugin names share a global namespace inside a marketplace. Prefix with a namespace (e.g. kaiships-code-review) to avoid conflicts with existing plugins.

Shipping hooks without tests

A bad PreToolUse hook can brick Claude Code sessions. Test hooks in a scratch repo first. Log their output. Ship behind a settings flag if the behavior is aggressive.

Claude Code Plugins FAQ

What is a Claude Code plugin?

A Claude Code plugin is a versioned package that bundles skills, subagents, hooks, MCP servers, and slash commands into a single installable unit. Plugins live in directories containing a .claude-plugin/plugin.json manifest, install via the /plugin command or --plugin-dir flag, and distribute through marketplaces like the official Anthropic catalog at claude-plugins-official.

How do I install a Claude Code plugin?

Run /plugin inside Claude Code to open the plugin manager, switch to the Discover tab, and pick a plugin from the official marketplace. Or install directly with /plugin install <name>@claude-plugins-official. The official Anthropic marketplace is connected by default. Installed plugins live in ~/.claude/plugins/ and are available across every project without restart.

What is the difference between a plugin and a skill?

A skill is a single capability defined in SKILL.md. A plugin is a bundle that can contain many skills plus hooks, MCP servers, subagents, LSP configs, and background monitors. Use a standalone skill for personal workflows. Use a plugin when you want versioned releases, team distribution, or namespaced commands like /my-plugin:review.

Where do Claude Code plugins live on disk?

Installed plugins live in ~/.claude/plugins/ and work across every project. Project-scoped plugins land in .claude/plugins/ inside the repo, which is where you version-control team plugins. Local development happens anywhere on disk via claude --plugin-dir ./my-plugin, which loads the plugin without installing it.

How do I create a Claude Code plugin?

Make a directory, add .claude-plugin/plugin.json with name, version, and description fields, then add at least one skill at skills/<name>/SKILL.md. Test with claude --plugin-dir ./my-plugin, iterate with /reload-plugins, and ship via a marketplace. The full plugin structure supports commands/, agents/, hooks/hooks.json, .mcp.json, .lsp.json, and monitors/monitors.json at the plugin root.

How do plugins compare to MCP servers and slash commands?

MCP servers expose external tools to Claude Code (Linear, Stripe, Sentry). Slash commands are user-invoked prompts. Plugins can contain both, plus model-invoked skills, subagents, and hooks. Install an MCP server alone when you only need external tool access. Ship a plugin when you want to distribute a bundle of skills, commands, hooks, and MCP configuration as one unit.

How do I submit a plugin to the official Anthropic marketplace?

Anthropic reviews submissions through two in-app forms: claude.ai/settings/plugins/submit and platform.claude.com/plugins/submit. Your plugin needs a public git repository, semantic versioning in plugin.json, a README with install instructions, and evidence of real-world use. Community marketplaces have no review gate and can be added by any GitHub repo URL.

Keep Going

Plugins compose with every other Claude Code primitive. These posts cover each piece in depth.