Claude Code Plugins: The Complete 2026 Guide to Install, Build, and Publish

If you've customized Claude Code with slash commands, subagents, hooks, or MCP servers, you've probably hit the same wall: none of it travels with you. Every new machine, every new teammate, every new repo means re-copying .claude/commands/, re-explaining your hooks, and re-typing MCP server configs. Plugins fix that. A plugin bundles all of those customizations — commands, agents, hooks, MCP servers, even LSP servers — into a single package you install with one command, and share with a team the same way.

This guide covers everything: installing plugins from a marketplace, building your own from scratch, and publishing a marketplace so others can install what you built.

What a Claude Code Plugin Actually Is

A plugin is a directory that packages any combination of:

Slash commands — custom shortcuts like /deploy or /review-pr
Subagents — specialized agent definitions for tasks like security review or test generation
Hooks — event handlers that fire on Claude Code lifecycle events (before a tool runs, after a session ends, etc.)
MCP servers — connections to external tools and data sources
LSP servers — language server integrations for richer code intelligence

The key distinction: skills are the content (what Claude can do), plugins are the distribution format (how that content gets installed and shared). You install a plugin; the plugin brings its skills, commands, and hooks along with it.

Plugins can be toggled on and off per-project, which matters more than it sounds — every command and agent definition you load adds to Claude's system prompt context. Plugins let you keep a large personal or team toolkit available without loading all of it into every session.

Installing Plugins from a Marketplace

Claude Code ships with access to Anthropic's official marketplace, and anyone can host their own. The workflow is a two-step add-then-install:

bash# 1. Add a marketplace (GitHub repo, git URL, or local path)
/plugin marketplace add anthropics/claude-code-plugins

# 2. Browse and install
/plugin

Running /plugin opens a browser with three tabs:

Tab	Shows
Installed	Plugins you've added, their status, and which skills/commands they expose
Discover	Available plugins across all marketplaces you're connected to
Marketplaces	Which plugin sources you're currently connected to

To pull updates when a marketplace publisher pushes changes:

bash/plugin marketplace update

This works identically in your terminal and in the VS Code extension, so a plugin your team installs is available everywhere Claude Code runs.

Anatomy of a Plugin: plugin.json

Every plugin needs a manifest at .claude-plugin/plugin.json. This is the only file that must live inside .claude-plugin/ — everything else (commands, agents, hooks, MCP config) sits at the plugin root.

json{
  "name": "pr-reviewer",
  "description": "Automated PR review with security and style checks",
  "version": "1.2.0",
  "author": {
    "name": "Your Team",
    "email": "[email protected]"
  },
  "homepage": "https://github.com/your-org/pr-reviewer-plugin",
  "repository": "https://github.com/your-org/pr-reviewer-plugin",
  "license": "MIT"
}

A typical plugin directory looks like this:

pr-reviewer/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   └── review-pr.md
├── agents/
│   └── security-reviewer.md
├── hooks/
│   └── hooks.json
└── .mcp.json

All component paths are relative to the plugin root and must start with ./ — you can override the default locations (skills/, commands/, agents/, hooks/, mcpServers, outputStyles, lspServers) in plugin.json if you want a different layout.

If you already have local commands/, agents/, or skills/ directories in a project, Claude Code can convert them straight into a plugin folder — including migrating settings.json hooks into hooks/hooks.json, since the hook format is identical in both places.

Building and Publishing a Marketplace

A marketplace is a catalog file — marketplace.json — that points to one or more plugins, whether hosted in the same repo, a different repo, or a local path.

json{
  "name": "acme-plugins",
  "owner": {
    "name": "Acme Engineering",
    "email": "[email protected]"
  },
  "plugins": [
    {
      "name": "pr-reviewer",
      "source": "./pr-reviewer",
      "description": "Automated PR review with security and style checks"
    },
    {
      "name": "deploy-toolkit",
      "source": "github:acme/deploy-toolkit-plugin",
      "description": "Slash commands and hooks for staged deployments"
    }
  ]
}

Publishing steps:

Build your plugin(s) with the components you need — skills, agents, hooks, MCP servers, or LSP servers.

Write marketplace.json at .claude-plugin/marketplace.json, listing each plugin and its source.

Host it — push to GitHub, GitLab, or any git remote. A local path works too for testing.

Share the add command — teammates run /plugin marketplace add your-org/your-repo and install from /plugin.

For a quick local test loop before publishing, point the marketplace add command at a local directory instead of a git URL — you can iterate on plugin.json and marketplace.json without pushing a commit every time.

Walkthrough: Build Your First Plugin in 10 Minutes

Let's build a small, real plugin: a /ship command that runs your test suite and drafts a commit message, plus a hook that blocks commits to main. This is the kind of thing worth packaging the moment a second person on your team wants it.

Step 1 — scaffold the directory.

bashmkdir -p ship-toolkit/.claude-plugin ship-toolkit/commands ship-toolkit/hooks
cd ship-toolkit

Step 2 — write the manifest.

json// .claude-plugin/plugin.json
{
  "name": "ship-toolkit",
  "description": "Test-and-commit workflow shortcuts",
  "version": "0.1.0",
  "author": { "name": "Your Team" },
  "license": "MIT"
}

Step 3 — add the slash command.

markdown<!-- commands/ship.md -->
---
description: Run tests, then draft a commit message from the diff
---

Run the project test suite. If it passes, summarize the staged diff into
a conventional-commit-style message and show it to the user before
committing — do not commit automatically.

Step 4 — add a hook that blocks commits to main.

json// hooks/hooks.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "scripts/block-main-commits.sh"
          }
        ]
      }
    ]
  }
}

The hook script inspects the command Claude is about to run and exits non-zero (blocking the tool call) if it detects git commit while the current branch is main. Hook definitions inside a plugin use the exact same JSON schema as hooks configured directly in settings.json — nothing new to learn if you've written a hook before.

Step 5 — test it locally, then publish.

bash/plugin marketplace add ./ship-toolkit
/plugin

Once it behaves the way you want, push the directory to a git repo and point /plugin marketplace add at your-org/ship-toolkit instead of the local path. Anyone on your team can now get /ship and the branch-protection hook with a single command.

Security: Treat Third-Party Plugins Like Third-Party Code

A plugin can run shell commands via hooks, register MCP servers with network access, and define agents with broad tool permissions — it has real capability, not just prompt text. Before adding a marketplace you didn't write:

Read the source first. A marketplace is just a git repo; git clone it and read hooks/hooks.json and any scripts it shells out to before installing.
Check what MCP servers it registers. .mcp.json entries can point at arbitrary endpoints or request broad credentials — verify they only ask for what the plugin's description implies.
Prefer marketplaces with a named, reachable owner. The owner field in marketplace.json is a real point of contact, not just metadata — a marketplace with no attribution is a red flag.
Uninstall what you don't use. Every installed plugin is attack surface as well as context overhead; the same toggle that saves system prompt space also limits blast radius if a plugin turns out to be poorly maintained.

This is the same due diligence you'd apply to any npm package or VS Code extension — plugins just make it easy to forget because installation is a single slash command.

Troubleshooting Common Issues

/plugin marketplace add fails silently. Confirm the source is a valid git remote or an absolute local path — relative paths from outside the target directory won't resolve. Run /plugin marketplace update after any change to confirm the manifest actually re-parsed. A command or agent from the plugin doesn't show up. Check that the component lives at the path declared in plugin.json (or the default commands/ / agents/ location) and that the file has the right frontmatter — a missing description field in a command file is a common cause of it not appearing in the picker. Hooks aren't firing. Verify hooks/hooks.json matches the schema Claude Code expects for the event type (PreToolUse, PostToolUse, SessionStart, etc.) and that the matcher pattern actually matches the tool name you're targeting — a typo'd matcher fails closed with no error. Team members get a different plugin version than you. They need to run /plugin marketplace update after you push changes — installs don't auto-pull. If version drift keeps biting your team, bump version in plugin.json on every change so it's obvious in the /plugin browser who's behind.

When to Build a Plugin vs. Just Use Commands

Not every customization needs to become a plugin. Use this as a rough filter:

Keep it local if it's a one-off command or hook only you use, in one repo.
Package as a plugin if more than one person needs it, or you reuse it across repos.
Publish a marketplace if you're distributing to a team, an open-source community, or the public — common cases include enforcing coding standards, supporting users of an open-source project, sharing productivity workflows, or wiring up internal tools via MCP.

Plugins are in public beta, so expect the manifest schema to gain fields over time — check /plugin in-app for the current component list before publishing broadly.

Key Takeaways

Plugins bundle commands, agents, hooks, MCP servers, and LSP servers into one installable unit — skills are the content, plugins are the distribution format.
Install with /plugin marketplace add then /plugin; update with /plugin marketplace update.
Every plugin needs .claude-plugin/plugin.json; every marketplace needs .claude-plugin/marketplace.json listing plugin sources.
Existing local commands/, agents/, and skills/ folders convert directly into a plugin structure — no rewrite needed.
Toggle plugins per-project to keep unused commands and agents out of your system prompt context.

Next Steps

Building your first plugin is the fastest way to stop re-explaining your Claude Code setup to every new teammate — and it's the same packaging format used for the study tools, practice-test workflows, and certification prep content in AI for Anything's Claude Certified Architect track. If you're prepping for the CCA exam and want structured, exam-aligned practice instead of scattered blog posts, check out our free sample quiz and study guides to see where your gaps are before test day.