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.

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.

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

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

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