Overview

Plugins allow you to bundle Claude Code features into distributable packages. They can contain commands, agents, skills, hooks, and MCP server configurations - everything needed to extend Claude Code's capabilities.

Quick Start

Create your first plugin in minutes:

1. Create Plugin Directory

mkdir -p my-plugin/.claude-plugin
cd my-plugin

2. Create plugin.json

{
  "name": "my-awesome-plugin",
  "description": "A plugin that does awesome things",
  "version": "1.0.0",
  "author": "Your Name",
  "repository": "https://github.com/yourusername/my-plugin"
}

3. Add Components

# Add a command
mkdir commands
echo "Your command content" > commands/hello.md

# Add an agent
mkdir agents
echo "---
name: helper
description: A helpful agent
---
Your agent prompt here" > agents/helper.md

# Add a skill
mkdir skills
echo "Your skill content" > skills/SKILL.md

4. Install Locally

claude /plugin install /path/to/my-plugin

Plugin Structure

Directory Layout

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Plugin metadata (required)
├── commands/                # Custom slash commands
│   ├── deploy.md
│   └── test.md
├── agents/                  # Sub-agents
│   ├── reviewer.md
│   └── debugger.md
├── skills/                  # Reusable skills
│   ├── SKILL.md
│   └── another-skill/
│       └── SKILL.md
├── hooks/
│   └── hooks.json          # Lifecycle hooks
├── .mcp.json               # MCP server configurations
└── README.md               # Plugin documentation

plugin.json Format

The plugin.json file defines your plugin's metadata:

{
  "name": "string",              // Required: Unique plugin identifier
  "description": "string",       // Required: Brief description
  "version": "1.0.0",           // Required: Semantic version
  "author": "string",           // Required: Author name or org
  "repository": "url",          // Optional: Source repository
  "homepage": "url",            // Optional: Documentation site
  "license": "MIT",             // Optional: License identifier
  "keywords": ["tag1", "tag2"], // Optional: Searchable tags
  "dependencies": {             // Optional: Plugin dependencies
    "other-plugin": "^1.0.0"
  },
  "engines": {                  // Optional: Claude Code version
    "claude": ">=1.0.0"
  }
}

Required Fields

Plugin Components

Commands

Add custom slash commands in the commands/ directory:

commands/
├── deploy.md           # Creates /deploy command
└── run-tests.md        # Creates /run-tests command

Each markdown file defines a command's behavior and prompt.

Agents

Include specialized sub-agents in the agents/ directory:

---
name: code-reviewer
description: Reviews code for quality and security
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are an expert code reviewer specializing in security and best practices.
Review code thoroughly and provide actionable feedback.

Agent Frontmatter

Plugins can ship agents with extended frontmatter fields to control agent behavior:

---
name: deep-researcher
description: Thorough research agent
tools: Read, Grep, Glob, Bash, WebSearch
model: opus
effort: thorough
maxTurns: 50
disallowedTools: Edit, Write
---

You are a research-only agent. Explore and analyze but never modify files.

Skills

Package reusable skills in the skills/ directory:

skills/
├── SKILL.md                    # Root-level skill
└── git-workflow/
    └── SKILL.md                # Named skill

Skills provide context and instructions that extend Claude's capabilities.

Skill Frontmatter Enhancements

Skills support frontmatter fields to control execution behavior:

---
effort: thorough
maxTurns: 30
disallowedTools: Edit, Write
---

Your skill instructions here...

Hooks

Automate workflows with hooks/hooks.json:

{
  "hooks": [
    {
      "event": "beforeResponse",
      "command": "npm test",
      "description": "Run tests before responding"
    },
    {
      "event": "afterEdit",
      "command": "npm run lint",
      "description": "Lint after code edits"
    }
  ]
}

MCP Servers

Bundle MCP integrations with .mcp.json:

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

Plugin Marketplaces

Marketplaces allow you to discover and install plugins from centralized registries.

marketplace.json Structure

Create a marketplace registry with a marketplace.json file:

{
  "name": "My Plugin Marketplace",
  "description": "Curated collection of Claude Code plugins",
  "plugins": [
    {
      "name": "git-workflow",
      "description": "Enhanced Git workflow commands and agents",
      "version": "1.2.0",
      "author": "GitTools Team",
      "repository": "https://github.com/gittools/git-workflow-plugin",
      "installUrl": "https://github.com/gittools/git-workflow-plugin/archive/v1.2.0.zip",
      "keywords": ["git", "workflow", "automation"]
    },
    {
      "name": "test-automation",
      "description": "Comprehensive testing and CI/CD automation",
      "version": "2.0.1",
      "author": "TestOps",
      "repository": "https://github.com/testops/test-automation",
      "installUrl": "https://github.com/testops/test-automation/archive/v2.0.1.zip",
      "keywords": ["testing", "ci-cd", "automation"]
    }
  ]
}

Adding Marketplaces

# Add a marketplace by URL
claude /plugin marketplace add https://example.com/marketplace.json

# Add a local marketplace
claude /plugin marketplace add /path/to/marketplace.json

# List configured marketplaces
claude /plugin marketplace list

Marketplace Fields

Settings-based Plugin Marketplace

You can declare plugins inline directly in settings.json using source: 'settings', without needing an external marketplace file or Git repository:

{
  "plugins": [
    {
      "source": "settings",
      "name": "my-inline-plugin",
      "commands": {
        "deploy": "Deploy the current project to staging"
      },
      "enabled": true
    }
  ]
}

This is useful for lightweight, project-specific plugins that don't warrant a separate repository or directory.

Plugin Persistent State

Plugins can store persistent state that survives plugin updates using the ${CLAUDE_PLUGIN_DATA} template variable. This resolves to a dedicated data directory for each plugin, separate from the plugin's own source files.

{
  "mcpServers": {
    "my-db": {
      "command": "node",
      "args": ["server.js", "--data-dir", "${CLAUDE_PLUGIN_DATA}"]
    }
  }
}

Use ${CLAUDE_PLUGIN_DATA} in your .mcp.json, hooks, or any configuration where you need a path that persists across plugin reinstalls and updates. The directory is created automatically and is unique per plugin.

Plugin Freshness

Plugins installed from Git repositories with a specific ref (branch, tag, or commit) are re-cloned on every load. This ensures you always get the latest version of the plugin at that ref, without needing to manually update.

# Install with a branch ref — always fresh on load
claude /plugin install https://github.com/company/plugin#main

# Install with a tag — pinned but still re-fetched
claude /plugin install https://github.com/company/plugin#v2.0.0

Ref-tracked plugins bypass the local cache entirely. If you need a stable, offline-capable install, omit the ref or use a local path instead.

Installing & Managing Plugins

Plugin Commands

Installation Methods

From Local Path

claude /plugin install /path/to/my-plugin

From Git Repository

claude /plugin install https://github.com/username/plugin-name

From Marketplace

# First add the marketplace
claude /plugin marketplace add https://example.com/marketplace.json

# Then install from marketplace
claude /plugin install git-workflow

From Archive

claude /plugin install https://example.com/plugins/my-plugin-v1.0.0.zip

Plugin Storage Locations

Plugin Project Scope

When you run /plugin uninstall, the removal is written to .claude/settings.local.json rather than the shared settings.json. This ensures that uninstalling a plugin in your local environment does not affect other team members who share the same project settings.

Plugin Validation

Use the claude plugin validate CLI command to check your plugin for correctness before publishing:

# Validate a plugin directory
claude plugin validate /path/to/my-plugin

The validator checks:

• Skill frontmatter fields (effort, maxTurns, disallowedTools)
• Agent frontmatter fields (effort, maxTurns, disallowedTools, model)
• Command frontmatter structure
• hooks.json schema and event names
• plugin.json required fields

Plugin Directories

--plugin-dir Flag

The --plugin-dir flag now accepts one path per flag. To specify multiple plugin directories, repeat the flag:

# New syntax (one path per flag)
claude --plugin-dir /path/to/plugins-a --plugin-dir /path/to/plugins-b

# Old syntax (colon-separated) — no longer supported
# claude --plugin-dir /path/a:/path/b

CLAUDE_CODE_PLUGIN_SEED_DIR

The CLAUDE_CODE_PLUGIN_SEED_DIR environment variable supports multiple seed directories. Plugins found in these directories are automatically available without explicit installation:

# Set multiple seed directories (colon-separated on Unix, semicolon on Windows)
export CLAUDE_CODE_PLUGIN_SEED_DIR="/opt/company-plugins:/home/user/my-plugins"

Seed directories are scanned at startup. Each subdirectory containing a .claude-plugin/plugin.json is loaded as a plugin.

Team Plugin Workflows

Share plugins across your team using version control and project settings.

Method 1: settings.json Reference

Reference plugins in .claude/settings.json:

{
  "plugins": [
    {
      "source": "https://github.com/company/internal-plugin",
      "enabled": true
    },
    {
      "source": "./team-plugins/code-standards",
      "enabled": true
    }
  ]
}

Team members will automatically be prompted to install these plugins when they open the project.

Method 2: Vendored Plugins

Include plugins directly in your repository:

.claude/
├── settings.json
└── plugins/
    ├── team-workflows/
    │   ├── .claude-plugin/
    │   │   └── plugin.json
    │   ├── commands/
    │   └── agents/
    └── company-standards/
        └── .claude-plugin/
            └── plugin.json

Plugins in .claude/plugins/ are automatically loaded for all team members.

Method 3: Private Marketplace

Host an internal marketplace for your organization:

{
  "name": "Acme Corp Internal Plugins",
  "description": "Approved plugins for Acme developers",
  "plugins": [
    {
      "name": "acme-deployment",
      "description": "Deployment workflows for Acme infrastructure",
      "version": "1.0.0",
      "author": "Acme DevOps",
      "repository": "https://github.com/acme/deployment-plugin",
      "installUrl": "https://artifacts.acme.com/plugins/deployment-v1.0.0.zip"
    }
  ]
}

Team members add the marketplace once and can install approved plugins easily.

Best Practices

Related