Claude Code Plugin Marketplace: Complete Guide to Installing, Building, and Publishing Plugins (2026)

Claude Code plugins were quietly one of the most underreported additions of 2026. While the community spent months debating model quality and context windows, Anthropic shipped a composable extension system that lets you install a full suite of skills, subagents, hooks, MCP servers, and LSP servers in a single command — and share it with your entire team.

This guide covers the full lifecycle: discovering what exists, installing it, building your own, and distributing it through a marketplace. If you’ve used VS Code extensions or npm packages, the mental model will click fast. If you haven’t, this guide starts from scratch.

What Is the Claude Code Plugin Marketplace

Before getting into mechanics, a quick orientation on what “plugin” and “marketplace” mean here.

A plugin is a self-contained directory that extends Claude Code. It can bundle:

Skills — slash commands like /my-plugin:review that Claude executes on demand
Agents — specialized subagents with their own system prompts and tool restrictions
Hooks — event handlers that fire automatically (before/after tool use, session start, etc.)
MCP servers — pre-configured connections to external services like GitHub, Sentry, or Linear
LSP servers — language intelligence for code navigation and real-time diagnostics
Monitors — background watchers that stream logs or file events into Claude’s context

A marketplace is a catalog file (a marketplace.json) that lists plugins and points to where they live. It can be hosted anywhere — a GitHub repo, a GitLab instance, a local path, a remote URL.

The combination means: add a marketplace once, then install any plugin in it with a single command. No manual file copying, no hunting for repositories, no version mismatches across team members.

Two marketplaces ship with every Claude Code installation:

claude-plugins-official — Anthropic’s curated set, including LSP servers for 11 languages, GitHub/Figma/Slack/Sentry integrations, security review, and workflow tools
Community marketplace (anthropics/claude-plugins-community) — third-party plugins that have cleared Anthropic’s validation pipeline, opt-in via /plugin marketplace add anthropics/claude-plugins-community

And you can create your own.

Plugin Architecture

Understanding the component types up front makes everything else easier. Here’s how they fit together inside a plugin directory.

Skills

Skills are slash commands that Claude executes when you call them. They live in skills/<name>/SKILL.md. The file has YAML frontmatter for metadata and a body that tells Claude what to do.

my-plugin/
└── skills/
    └── code-review/
        └── SKILL.md

---
description: Reviews code for bugs, security issues, and performance. Use when reviewing a PR or auditing a file.
---

Review the specified code for:
1. Potential bugs and edge cases
2. Security vulnerabilities (injection, auth bypass, exposed secrets)
3. Performance bottlenecks
4. Missing error handling

Be specific and actionable. Cite line numbers where possible.

Claude uses the description field to decide when to invoke the skill automatically (model-invoked mode). When disable-model-invocation: true is set in the frontmatter, the skill only runs when explicitly called. For commands that should be predictable and human-triggered — deploys, commits, reviews — disable automatic invocation.

Skill names get namespaced by the plugin: a skill named review in a plugin named my-plugin becomes /my-plugin:review. This prevents conflicts when multiple plugins define skills with the same name.

Agents (Subagents)

Agents are specialized Claude instances defined in the agents/ directory. Each agent has its own system prompt, tool allowlist/denylist, and optionally a specific model.

my-plugin/
└── agents/
    └── security-reviewer.md

---
name: security-reviewer
description: Specialist in identifying security vulnerabilities in code changes
tools: Read, Bash, Grep
---

You are a security-focused code reviewer. Your role is to identify potential security vulnerabilities in code changes...

A plugin can designate one of its agents as the default — when the plugin is active, that agent becomes the main thread. This is how you can ship a plugin that fundamentally changes how Claude Code behaves in a given project context.

Hooks

Hooks fire automatically on Claude Code events. They live in hooks/hooks.json and mirror the format of hooks in .claude/settings.json.

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

Packaging hooks in a plugin means they install with everything else. No more onboarding doc that says “also paste this into your settings.json.”

MCP Servers

MCP servers bundled in a plugin live in .mcp.json at the plugin root. When the plugin is installed, those servers become available automatically — no separate claude mcp add command needed.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

This is how the official github and slack plugins work: they’re essentially pre-configured MCP bundles with a clean install path.

LSP Servers

LSP servers in .lsp.json give Claude real-time code intelligence — jump to definition, find references, type error diagnostics after every edit. The official marketplace ships pre-built LSP plugins for TypeScript, Python, Go, Rust, Java, and eight other languages.

The Full Directory Layout

my-plugin/
├── .claude-plugin/
│   └── plugin.json          ← manifest (ONLY this goes here)
├── skills/
│   └── review/
│       └── SKILL.md
├── agents/
│   └── security-reviewer.md
├── hooks/
│   └── hooks.json
├── .mcp.json
├── .lsp.json
├── monitors/
│   └── monitors.json
├── bin/                     ← executables added to Bash tool's PATH
├── settings.json            ← default settings applied when plugin is active
└── README.md

One critical rule the docs flag explicitly: commands/, agents/, skills/, and hooks/ must be at the plugin root — not inside .claude-plugin/. Only plugin.json lives inside .claude-plugin/. This catches a lot of “why isn’t my skill loading?” bugs.

Discovering Plugins

The primary interface is the /plugin command, which opens an interactive manager with four tabs:

Discover — browse all plugins from your configured marketplaces
Installed — view and manage what’s installed
Marketplaces — add, update, or remove marketplaces
Errors — plugin load failures and diagnostics

From the Discover tab, you can filter by name, see each plugin’s components (what skills and agents it adds), check its context cost (how many tokens it adds per turn), and choose installation scope before confirming.

Plugins marked as relevant to your current working directory are pinned at the top of the Discover tab with a “suggested for this directory” label. If you open a Rust project and have the rust-analyzer-lsp plugin, it appears first. This contextual surfacing makes the marketplace feel less like a static list and more like a recommendations layer.

Browsing via the web: claude.com/plugins has the official marketplace catalog.

Adding a Marketplace

Before you can browse or install from a third-party marketplace, you add it:

# GitHub repo
/plugin marketplace add anthropics/claude-plugins-community

# Any Git host
/plugin marketplace add https://gitlab.com/company/plugins.git

# Specific branch or tag
/plugin marketplace add https://gitlab.com/company/plugins.git#v2.0

# Local path (useful during development)
/plugin marketplace add ./my-local-marketplace

You can shorten /plugin marketplace to /plugin market in any command.

Installing Plugins

From the CLI

Once a marketplace is added, install a plugin by name:

# Install from official marketplace
/plugin install github@claude-plugins-official

# Install from community marketplace
/plugin install deploy-toolkit@claude-community

# Install from a specific marketplace you added
/plugin install code-formatter@my-team-tools

The default scope is user — the plugin is available across all your projects. To install for all collaborators on a repository, use the project scope via the interactive UI or the CLI flag:

claude plugin install formatter@my-team-tools --scope project

Installation Scopes

Claude Code has three scopes for plugin installation, mirroring the settings file hierarchy:

Scope	Storage	Who sees it
User	`~/.claude/settings.json`	You, across all projects
Project	`.claude/settings.json` (committed)	All collaborators on the repo
Local	`.claude/settings.local.json` (not committed)	You, in this repo only

Project scope is the right default for team tooling. A new developer clones the repo, opens Claude Code, and gets prompted to install the team’s standard plugins. No Slack messages required.

Applying Changes Mid-Session

After installing, enabling, or disabling plugins, run:

/reload-plugins

This reloads all active plugins without restarting Claude Code. You’ll see a count of plugins, skills, agents, hooks, MCP servers, and LSP servers that are now active.

Testing Before Installing

For plugins you haven’t committed to installing yet, use --plugin-dir to load one directly:

claude --plugin-dir ./some-plugin

This works with local directories and .zip archives. It also works with remote URLs via --plugin-url:

claude --plugin-url https://example.com/my-plugin.zip

The --plugin-dir version takes precedence over any installed version of the same plugin name, so you can safely test updates without uninstalling the current release.

Plugin File Structure in Detail

`plugin.json` — The Manifest

The manifest lives at .claude-plugin/plugin.json and defines your plugin’s identity:

{
  "name": "deploy-toolkit",
  "description": "Deployment automation for AWS and Vercel with rollback support",
  "version": "2.1.0",
  "author": {
    "name": "Your Name",
    "email": "you@example.com"
  },
  "homepage": "https://github.com/your-org/deploy-toolkit",
  "repository": "https://github.com/your-org/deploy-toolkit",
  "license": "MIT",
  "keywords": ["deploy", "aws", "vercel", "ci"]
}

Key fields:

name — This becomes the namespace for all your skills. A skill named rollback in a plugin named deploy-toolkit is invoked as /deploy-toolkit:rollback. Keep names short and descriptive.

version — If set, Claude Code only updates the plugin when you bump this value. If omitted and the plugin is in a git repo, every commit counts as a new version (the commit SHA is used). Both approaches are valid: semantic versions for stable tools users install permanently, commit-SHA tracking for internal tools where you want automatic updates.

author.name and homepage — These appear in the Discover tab and help users verify they’re installing what they think they’re installing. Worth setting, especially for public distribution.

`SKILL.md` Frontmatter Reference

---
description: One-line summary of what the skill does and when Claude should use it
disable-model-invocation: true   # true = human-triggered only
---

Skill body here. Plain English instructions. Can reference $ARGUMENTS.

$ARGUMENTS captures everything the user types after the skill name. /deploy-toolkit:rollback production v1.4.2 passes production v1.4.2 as $ARGUMENTS.

Building Your First Plugin: Step-by-Step

Let’s build a real plugin: a code-review plugin that checks code quality, security, and test coverage. It includes a skill, a hook, and a background monitor for error logs.

Step 1: Create the Directory Structure

mkdir -p code-review-plugin/.claude-plugin
mkdir -p code-review-plugin/skills/review
mkdir -p code-review-plugin/skills/security-scan
mkdir -p code-review-plugin/hooks
mkdir -p code-review-plugin/monitors

Step 2: Write the Manifest

// code-review-plugin/.claude-plugin/plugin.json
{
  "name": "code-review",
  "description": "Code quality, security scanning, and error log monitoring for development workflows",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  },
  "keywords": ["code-review", "security", "quality", "lint"]
}

Step 3: Create the Skills

The main review skill:

// code-review-plugin/skills/review/SKILL.md
---
description: Full code review for quality, bugs, and test coverage. Use when reviewing changes or auditing code.
disable-model-invocation: true
---

Review $ARGUMENTS (or the most recent changes if no argument given) for:

**Quality**
- Code organization and single responsibility
- Error handling completeness
- Duplicate logic that should be extracted

**Correctness**
- Off-by-one errors and boundary conditions
- Race conditions or async issues
- Unhandled null/undefined paths

**Test coverage**
- Are edge cases tested?
- Are error paths tested?
- Any obvious missing assertions?

Format output as: Summary → Critical Issues → Warnings → Suggestions.
Keep each item to one sentence with a line reference.

A focused security scan skill:

// code-review-plugin/skills/security-scan/SKILL.md
---
description: Security-focused review for OWASP vulnerabilities, injection, auth issues. Use before merging security-sensitive code.
disable-model-invocation: true
---

Scan $ARGUMENTS for security vulnerabilities. Check specifically:

1. SQL/NoSQL/Command injection risks
2. Authentication and authorization gaps
3. Sensitive data exposure (keys, tokens, PII in logs)
4. Insecure direct object references
5. Dependency issues (outdated packages with known CVEs)

For each finding: severity (Critical/High/Medium/Low), location, and a one-line fix recommendation.

Step 4: Add a Hook

Auto-lint after every file write:

// code-review-plugin/hooks/hooks.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path // empty' | xargs -I{} sh -c 'test -f {} && npx eslint --fix {} 2>/dev/null || true'"
          }
        ]
      }
    ]
  }
}

Step 5: Add a Background Monitor

// code-review-plugin/monitors/monitors.json
[
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log 2>/dev/null",
    "description": "Application error log — Claude sees new entries automatically"
  }
]

Step 6: Test Locally

claude --plugin-dir ./code-review-plugin

Inside the session:

# Try the skills
/code-review:review src/auth/login.ts
/code-review:security-scan src/api/

# Reload after making changes to the plugin
/reload-plugins

# Verify the plugin loaded
/help

Your plugin skills appear under their namespace in the /help output. If they don’t, check the Errors tab in /plugin — the most common cause is a directory structure mistake (component directories inside .claude-plugin/ instead of at the plugin root).

Step 7: Develop in Your Skills Directory

For a plugin you want to use personally across projects without marketplace overhead, use claude plugin init:

claude plugin init code-review

This scaffolds the plugin at ~/.claude/skills/code-review/ and loads it automatically on the next session as code-review@skills-dir. No install step, no marketplace.

Publishing to Marketplaces

When your plugin is ready to share, the path is:

Push the plugin to a Git repository
Create a marketplace.json catalog
Push the catalog to its own repository (or the same one)
Share the marketplace add command with your users
Optionally, submit to the community marketplace

Step 1: Push Your Plugin

Your plugin should be a public (or private, for team distribution) Git repository. The repository root should be the plugin root — the directory containing .claude-plugin/.

Step 2: Create a Marketplace Catalog

A marketplace is a marketplace.json at .claude-plugin/marketplace.json in a separate catalog repository:

// .claude-plugin/marketplace.json
{
  "name": "my-dev-tools",
  "owner": {
    "name": "Your Name",
    "email": "you@example.com"
  },
  "description": "Development workflow plugins for teams",
  "plugins": [
    {
      "name": "code-review",
      "source": {
        "source": "github",
        "repo": "your-org/code-review-plugin"
      },
      "description": "Code quality, security scanning, and error log monitoring",
      "author": {
        "name": "Your Name"
      },
      "homepage": "https://github.com/your-org/code-review-plugin",
      "keywords": ["code-review", "security", "quality"],
      "category": "development"
    }
  ]
}

For multiple plugins in the same repository (a monorepo structure), use relative paths and the metadata.pluginRoot shorthand:

{
  "name": "my-dev-tools",
  "owner": { "name": "Your Name" },
  "metadata": {
    "pluginRoot": "./plugins"
  },
  "plugins": [
    {
      "name": "code-review",
      "source": "./code-review-plugin",
      "description": "Code quality and security scanning"
    },
    {
      "name": "deploy-toolkit",
      "source": "./deploy-toolkit",
      "description": "Deployment automation for AWS and Vercel"
    }
  ]
}

With pluginRoot set to ./plugins, the source ./code-review-plugin resolves to ./plugins/code-review-plugin.

Pinning Plugin Versions

By default, if you omit version from your plugin entry, every git commit to the plugin repository is a new version. Users get the latest commit on every update. For stable releases, pin explicitly:

{
  "name": "code-review",
  "source": {
    "source": "github",
    "repo": "your-org/code-review-plugin",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  },
  "version": "2.0.0"
}

sha pins to an exact commit, preventing surprise updates even if a tag is moved.

Validate Before Publishing

Run the built-in validator before pushing:

claude plugin validate

This runs the same checks the community marketplace review pipeline uses. Fix any reported issues before submitting.

Step 3: Host the Catalog

Push your catalog repository to GitHub (or any Git host). A typical structure:

your-org/plugin-catalog/
├── .claude-plugin/
│   └── marketplace.json
├── plugins/           ← if you're co-hosting plugins
│   ├── code-review/
│   └── deploy-toolkit/
└── README.md

/plugin marketplace add your-org/plugin-catalog

That’s the command your users run. After adding the marketplace, they install individual plugins:

/plugin install code-review@my-dev-tools

Private Repositories

For team-internal plugins, keep the repository private. Users need Git credentials (SSH key or personal access token) with read access to clone it. Claude Code uses the system Git configuration, so if git clone works in their terminal, plugin installation will too.

For projects, embed the marketplace in .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "my-team-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/plugin-catalog"
      }
    }
  }
}

Team members who trust the project folder will be prompted to add this marketplace automatically.

Submitting to the Community Marketplace

For public plugins you want discoverable by everyone:

Run claude plugin validate locally — the review pipeline runs this same check
Submit via claude.ai/settings/plugins/submit or platform.claude.com/plugins/submit
Approved plugins get pinned to a specific commit SHA in anthropics/claude-plugins-community
The catalog syncs nightly — expect up to 24 hours between approval and general availability

To verify your plugin is installable after approval:

# Check the community catalog directly
# Look for your plugin name at:
# https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json

Note: the community marketplace (anthropics/claude-plugins-community) is separate from the official marketplace (claude-plugins-official). Community plugins pass automated validation. Official plugins are curated by Anthropic and there’s no application process.

Plugin Discovery Best Practices

If you want your plugin to be found and installed, the description and metadata fields do real work.

Write a description that explains the trigger. Claude uses your skill’s description field to decide when to invoke it automatically. “Review code” is worse than “Reviews code for bugs, security issues, and performance problems. Use when reviewing a PR, auditing a file before merging, or after refactoring.” The second form tells Claude exactly when to reach for it.

Use keywords strategically. The Discover tab filter searches plugin names and descriptions. Keywords add searchable terms without cluttering the description. Include the problem domain (security, testing, deployment) and the specific tools or frameworks (pytest, terraform, aws).

Set homepage and repository. These appear in the plugin detail pane. Users check them to vet unknown plugins. A missing homepage is a credibility gap for anything you’re asking developers to install with execution privileges.

Category matters for browsing. Use a category that matches how users think about their problem, not how you implemented it. A plugin that adds GitHub integration belongs in integrations, not utilities.

Keep plugin names kebab-case. The name becomes a CLI identifier and a namespace prefix. code-review works. Code Review breaks the namespace, and codeReview is inconsistent with the rest of the ecosystem.

Managing Plugin Updates and Versioning

Manual Updates

/plugin marketplace update my-team-tools

This refreshes the marketplace catalog. If any installed plugins have newer versions available, Claude Code will notify you. Apply the update:

/reload-plugins

Auto-Updates

Official Anthropic marketplaces have auto-update enabled by default. For third-party marketplaces, toggle it in the Marketplaces tab of /plugin.

For CI environments where you want plugin updates but not Claude Code updates:

export DISABLE_AUTOUPDATER=1
export FORCE_AUTOUPDATE_PLUGINS=1

The Plugin Cache

Installed plugins live at ~/.claude/plugins/cache/. If a plugin is behaving strangely after an update (wrong skill content, stale hooks), clear the cache:

rm -rf ~/.claude/plugins/cache

Then restart Claude Code and reinstall the plugin. This is the fix for most “my plugin changes aren’t showing up” problems.

Versioning Strategy

For plugins with active users, two approaches work well:

Semantic versioning with explicit pins — bump version in plugin.json when you want users to receive an update. Users stay on their installed version until you bump. Good for stable tools where surprise updates break workflows.

SHA pinning in marketplace.json — pin the sha in your catalog entry and update it when you’re ready to ship. You control the rollout from the catalog side without requiring users to take any action. Good for internal team tools.

The git-SHA default (no version field, no sha pin) gives users the latest commit automatically. Convenient for development-phase plugins. Risky for anything used in production.

Real-World Plugin Examples

Career-Ops Plugin

A plugin for job search workflows: a resume-review skill that checks for ATS compatibility, a cover-letter skill that tailors language to job descriptions, and a background monitor that watches for email replies to applications. The monitor streams new emails into Claude’s context so you can run /career-ops:draft-reply without copy-pasting.

Plugin structure:

career-ops/
├── .claude-plugin/plugin.json
├── skills/
│   ├── review-resume/SKILL.md
│   ├── tailor-cover-letter/SKILL.md
│   └── draft-reply/SKILL.md
└── monitors/monitors.json     ← watches mail spool or IMAP log

Code Review Plugin (from the tutorial above)

Used at the project scope: commit it to .claude/settings.json and every developer on the team gets the review skill, the auto-lint hook, and the error log monitor without any individual setup.

Deploy Plugin

A deploy plugin that wraps AWS and Vercel workflows:

/deploy:stage — runs tests, builds, deploys to staging
/deploy:promote — promotes staging to production with confirmation prompt
/deploy:rollback — rolls back production to the previous version
Hooks: PostToolUse on Write/Edit triggers a diff report
MCP server: a pre-configured AWS CLI wrapper

// .claude-plugin/plugin.json
{
  "name": "deploy",
  "description": "Staging and production deployment workflows for AWS and Vercel",
  "version": "1.2.0",
  "author": { "name": "Ops Team" }
}

The value is atomicity: one /plugin install deploy@team-tools gives a new developer the full deployment workflow, hooked into Claude Code, with no separate tool setup.

FAQ

What’s the difference between a plugin and standalone skills/hooks in .claude/?

Standalone configuration works great for personal or single-project use. Plugins add namespacing, versioning, and distribution. If you’re writing a skill just for yourself, put it in ~/.claude/skills/. If you want to share it with your team or the community, package it as a plugin.

Can a plugin execute arbitrary code?

Yes, and this is worth taking seriously. Hooks run shell commands. MCP servers spawn processes. Background monitors run long-lived commands. Only install plugins from sources you trust. The official marketplace and community marketplace both apply automated safety screening, but that’s a floor, not a ceiling.

Will installing a plugin affect my context window?

Each plugin adds a Context Cost displayed in the Discover tab before you install (Claude Code v2.1.143+). Skills and agents contribute their content to the context on each turn. Heavy use of multiple large plugins will reduce available context for your actual work. Disable unused plugins rather than leaving everything installed.

Can I convert my existing .claude/ configuration into a plugin?

Yes. Create the plugin directory structure, move your commands/ and skills/ directories to the plugin root, migrate hooks from settings.json to hooks/hooks.json, write a plugin.json manifest, and test with --plugin-dir. The official migration guide has the exact steps.

How do namespaced skill names work with arguments?

Exactly the same as standalone skills. /deploy:rollback production passes production as $ARGUMENTS inside rollback/SKILL.md. The namespace prefix is only for invocation — inside the skill body, you work with $ARGUMENTS as usual.

Can a plugin depend on another plugin?

Yes, via the plugin dependency system. In plugin.json, list dependencies under the dependencies field. When a user installs your plugin, Claude Code auto-installs dependencies from allowed marketplaces. Cross-marketplace dependencies require the marketplace author to configure allowCrossMarketplaceDependenciesOn in marketplace.json.

How does the community marketplace review process work?

Submit via the in-app form. The pipeline runs claude plugin validate plus automated safety screening (malware, credential harvesting patterns, known bad actors). Approved plugins get pinned to a specific commit SHA in the anthropics/claude-plugins-community catalog. CI bumps the pin automatically as you push new commits, so once approved, your updates ship without re-review. The catalog syncs nightly.

The plugin system changes how Claude Code scales across teams. Instead of every developer setting up their own hooks, MCP connections, and custom skills, you package it once, put it in a marketplace, and the entire team installs it in a single command. The lifecycle — build, test with --plugin-dir, publish via marketplace, distribute via project settings — maps cleanly onto how teams already manage shared tooling.

For deeper dives into specific components:

How to Write Claude Code Skills (2026) — full skill authoring guide including progressive disclosure and model invocation control
Claude Code Hooks Complete Reference (2026) — every hook event, matcher syntax, and shell integration pattern
Claude Code MCP Complete Guide (2026) — transport types, authentication, and production MCP deployment