Plugin System

Plugins bundle Skills, Agents, Hooks, and MCP/LSP servers into a single package so you can share them across projects and teams. Namespacing prevents collisions, and you can distribute them through a marketplace.

Plugin vs Standalone Setup

Approach	Skill name	Best when
Standalone (`.claude/`)	`/hello`	Personal workflows, project-specific, quick experiments
Plugin (`.claude-plugin/`)	`/plugin-name:hello`	Team sharing, community distribution, version management, reuse across projects

Plugin Structure

my-plugin/
├── .claude-plugin/
│   └── plugin.json           # Manifest (plugin info)
├── skills/                   # Skills (SKILL.md files)
├── agents/                   # Custom subagents
├── commands/                 # Skills (markdown files)
├── hooks/
│   └── hooks.json            # Hook event handlers
├── .mcp.json                 # MCP server config
├── .lsp.json                 # LSP server config
└── settings.json             # Default settings applied when the plugin is enabled

Directory rules

Only plugin.json goes inside .claude-plugin/. Every other directory (skills/, agents/, hooks/, etc.) is placed at the plugin root level.

Manifest (plugin.json)

{
  "name": "my-awesome-plugin",
  "description": "A collection of code quality automation tools",
  "version": "1.0.0",
  "author": {
    "name": "Team Awesome"
  },
  "homepage": "https://github.com/team/my-plugin",
  "repository": "https://github.com/team/my-plugin",
  "license": "MIT"
}

Field	Required	Description
`name`	O	Unique identifier and Skill namespace
`description`	-	Shown in the plugin manager
`version`	-	Semantic versioning (can also be managed in the marketplace)
`author`	-	Author info (object: `{"name": "Name"}`)
`homepage`	-	Homepage URL
`repository`	-	Source code repository
`license`	-	License

Packaging Skills

Put SKILL.md files in the skills/ directory. The folder name becomes the Skill name, prefixed with the plugin namespace:

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

This Skill is invoked with /my-awesome-plugin:code-review.

---
name: code-review
description: Reviews code changes for best practices and security
---

When reviewing code, check:
1. Code structure and organization
2. Error handling
3. Security issues

Passing arguments

Use the $ARGUMENTS placeholder to receive user input:

---
description: A Skill that greets the user
---

Warmly greet $ARGUMENTS and ask if they need any help.

Usage: /my-awesome-plugin:hello Alex

Packaging Agents

Put custom subagent markdown files in the agents/ directory:

---
name: security-reviewer
description: An agent specialized in security audits
tools: Read, Grep, Glob
model: sonnet
---

Inspect for security vulnerabilities against the OWASP Top 10.

Packaging Hooks

Define event handlers in hooks/hooks.json:

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

Packaging MCP/LSP Servers

MCP servers (`.mcp.json`)

Define MCP servers with a .mcp.json file at the plugin root.

LSP servers (`.lsp.json`)

LSP servers provide real-time code intelligence:

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

LSP requirements

The language server binary must be installed on the user's system.

Default Settings (settings.json)

Default settings to apply when the plugin is enabled:

{
  "agent": "security-reviewer"
}

You can activate a custom agent from the agents/ directory as the main thread.

Namespace Rules

Plugin Skills are always namespaced to prevent collisions
Format: /plugin-name:skill-name
The namespace is determined by the name field in plugin.json
Standalone Skills use the short /skill-name form

Installation and Management

Local testing

# Load a plugin directly during development
claude --plugin-dir ./my-plugin

# Load multiple plugins at once
claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

After making changes, you have to restart Claude Code for them to take effect.

Plugin management commands

# Plugin management interface
/plugin

# Install / remove / list
/plugin install
/plugin remove
/plugin list

# Check available Skills (including from plugins)
/help

Verification

Confirm the Skill is invocable via /plugin-name:skill-name
Confirm the agent appears in /agents
Confirm the Hook behaves as expected

Dependencies

A plugin can depend on other plugins. Dependency plugins are installed automatically alongside it. Requires Claude Code v2.1.110+.

Author — declaring dependencies

Declare them in the dependencies array of plugin.json. If no version is specified, latest is used; you can also specify a semver range:

{
  "name": "deploy-kit",
  "version": "3.1.0",
  "dependencies": [
    "audit-logger",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

The version field uses npm semver range syntax (~2.1.0, ^2.0, >=1.4, =2.1.0). Dependencies are fetched from the marketplace at the highest git tag that satisfies the range.

Release tag convention: {plugin-name}--v{version} (e.g., secrets-vault--v2.1.0). Tag directly with git tag, or use claude plugin tag --push to auto-validate the plugin.json and marketplace entry before tagging.

User — handling dependency errors

/plugin list and /doctor surface dependency problems. Common cases:

Error	Cause	Fix
`dependency-unsatisfied`	The dependency plugin is not installed or is disabled	Run the `claude plugin install` command shown in the error. If it's not registered in a marketplace, run `claude plugin marketplace add` first
`range-conflict`	Multiple plugins require conflicting version ranges for the same dependency	Uninstall/update one of the conflicting plugins, or ask the upstream author to widen the range
`dependency-version-unsatisfied`	The installed dependency version is outside your range	Re-resolve with `claude plugin install <dependency>@<marketplace>`
`no-matching-tag`	The dependency repo has no `{name}--v*` tag within the range	Upstream hasn't released a tag — relax the range or contact the author

The errors field of claude plugin list --json lets you check for this in automation.

Cleaning up orphan dependencies

Even after you uninstall a plugin, its dependencies remain on disk (in case of reinstallation or direct use). To clean up:

# List and remove dependencies that no plugin needs (with a confirmation prompt)
claude plugin prune

# Prune together with your own uninstall
claude plugin uninstall deploy-kit --prune

Plugins you installed directly are never pruned — only ones installed automatically as dependencies. claude plugin prune requires v2.1.121+.

For detailed dependency constraints and cross-marketplace policy, see the official plugin-dependencies page.

Distribution

Submitting to a marketplace

Document it with README.md
Manage versions with semantic versioning
Test it with other users
Submit to a marketplace:
- Claude.ai: claude.ai/settings/plugins/submit
- Console: platform.claude.com/plugins/submit

Migrating from standalone to plugin

Convert your existing .claude/ files into a plugin structure:

Create the .claude-plugin/plugin.json manifest
Copy .claude/skills/ → skills/ at the plugin root
Copy .claude/agents/ → agents/
Move Hook config → hooks/hooks.json
Move MCP config → .mcp.json

Marketplace Plugin Suggestions (relevance)

A marketplace operator can add a relevance block to a plugin entry in marketplace.json so that Claude Code suggests installing that plugin when it fits the user's work context (v2.1.152+). This is a feature for enterprise admins running an in-org marketplace.

{
  "name": "terraform-helpers",
  "source": "./plugins/terraform-helpers",
  "relevance": {
    "topic": "Terraform",
    "signals": {
      "cli": ["terraform"],
      "filesRead": ["**/*.tf"]
    }
  }
}

Signals: a suggestion is made if any one of cwd (working directory), cli (executed commands), hosts (URL hosts), filesRead (files read), or manifestDeps (manifest dependencies) matches
Signal matching happens locally only; which signal matched is not sent to Anthropic or the operator
Where suggestions appear: spinner tips / session-start notification (on cwd match) / the top of the /plugin Discover tab
Activation requirement: declaration alone isn't enough — an admin must allowlist the marketplace in the managed settings' pluginSuggestionMarketplaces for suggestions to appear (including for the official Anthropic marketplace)
Claude Code never auto-installs; the user always confirms

If you're an individual user

This feature is for marketplace operators and enterprise admins. If you're just installing plugins, see the plugin management commands above.

Found an issue on this page? Report it →

Plugin vs Standalone Setup​

Plugin Structure​

Manifest (plugin.json)​

Packaging Skills​

Passing arguments​

Packaging Agents​

Packaging Hooks​

Packaging MCP/LSP Servers​

MCP servers (.mcp.json)​

LSP servers (.lsp.json)​

Default Settings (settings.json)​

Namespace Rules​

Installation and Management​

Local testing​

Plugin management commands​

Verification​

Dependencies​

Author — declaring dependencies​

User — handling dependency errors​

Cleaning up orphan dependencies​

Distribution​

Submitting to a marketplace​

Migrating from standalone to plugin​

Marketplace Plugin Suggestions (relevance)​