Claude Code Plugins: The Complete Guide to the Extension System 2025

Claude Code Plugins, Anthropic's official extension system for the Claude Code CLI, transform how developers customize their AI coding workflows. Claude Code Plugins are distributable packages that bundle slash commands, agents, skills, hooks, and MCP servers into shareable units. With 12 official Claude Code Plugins already available from Anthropic, the Claude Code Plugins ecosystem covers everything from automated code review to autonomous development loops. This complete guide to Claude Code Plugins explains how to install, create, and configure Claude Code Plugins for your team — plus how Claude Code Plugins interact with Skills, MCP Servers, and Agents.

---

Claude Code Plugins: Key Takeaways

• Five Extension Types: Claude Code offers Plugins (distributable packages), Skills (auto-invoked capabilities), MCP Servers (external tool integration), Agents (specialized assistants), and CLAUDE.md (project context)—each serving different customization needs
• Plugins vs Skills: Plugins are explicitly invoked via /plugin:command and can contain multiple components; Skills are automatically invoked by Claude based on task context
• 12 Official Plugins: Anthropic provides production-ready plugins including code-review (multi-agent PR review), feature-dev (7-phase workflows), and ralph-wiggum (autonomous iteration loops)

---

Claude Code Plugins and the Extension System Overview

Claude Code Plugins claude Code offers five different extension mechanisms, each covering different use cases:

Understanding the Hierarchy

┌─────────────────────────────────────────────────────────────┐
│                      Claude Code CLI                         │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │   Plugins   │  │   Skills    │  │    MCP Servers      │  │
│  │  (Packages) │  │(Capability) │  │ (External Tools)    │  │
│  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘  │
│         │                │                     │             │
│         ▼                ▼                     ▼             │
│  ┌─────────────────────────────────────────────────────────┐│
│  │                    Agents/Subagents                      ││
│  │              (Specialized Assistants)                    ││
│  └─────────────────────────────────────────────────────────┘│
│                            ▲                                 │
│                            │                                 │
│  ┌─────────────────────────────────────────────────────────┐│
│  │    CLAUDE.md / AGENTS.md (Project Context & Rules)      ││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘

---

1. Claude Code Plugins – The Complete Plugin Solution

Claude Code Plugins are the most powerful extension format in the Claude Code ecosystem. They bundle multiple components into a distributable package:

What Plugins Can Contain

• Slash Commands – Custom commands (/plugin:command)
• Agents – Specialized subagents
• Skills – Context-sensitive capabilities
• Hooks – Event handlers for automation
• MCP Servers – External tool configurations
• LSP Servers – Code intelligence for languages

Plugin Structure

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Plugin metadata (required)
├── commands/                # Slash commands
│   └── hello.md
├── agents/                  # Subagent definitions
│   └── reviewer.md
├── skills/                  # Agent Skills
│   └── code-review/
│       └── SKILL.md
├── hooks/                   # Event handlers
│   └── hooks.json
├── .mcp.json                # MCP server configuration
├── .lsp.json                # LSP server configuration
└── README.md                # Documentation

Plugin Manifest (plugin.json)

{
  "name": "my-plugin",
  "description": "Description of the plugin",
  "version": "1.0.0",
  "author": {
    "name": "Your Name",
    "email": "email@example.com"
  },
  "repository": "https://github.com/user/my-plugin",
  "license": "MIT"
}

---

2. Skills – Contextual Capabilities

Skills are model-invoked: Claude automatically decides when a skill is relevant, based on task context.

Difference from Plugins

Skill Structure (SKILL.md)

---
name: code-review
description: Reviews code for best practices. Use when reviewing PRs or code changes.
---

When reviewing code, analyze:
1. Code structure and readability
2. Security vulnerabilities
3. Performance implications
4. Test coverage

Provide feedback organized by priority:
- Critical (must fix)
- Warnings (should fix)
- Suggestions (consider)

Skill Storage Locations

---

3. MCP Servers – External Tool Integration

Model Context Protocol (MCP) enables Claude to access external data sources and tools. Claude Code Plugins MCP Servers are independent of Claude Code and can be used by various clients.

MCP vs. Plugin

Including MCP in Plugins

Plugins can configure MCP servers via .mcp.json:

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@my-org/db-mcp-server"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

When MCP vs. Plugin?

Use MCP when:

• Integrating external APIs/databases
• Functionality should be client-agnostic
• You want to use existing MCP servers

Use Plugins when:

• Customizing Claude Code workflows
• You need slash commands or hooks
• You want to define specialized agents

---

4. Agents & Subagents – Specialized Assistants

Agents (also called subagents) are pre-configured AI personalities that Claude Code can delegate tasks to.

Difference from Skills

Agent Definition

---
name: code-reviewer
description: Expert code review. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
permissionMode: default
---

You are a senior code reviewer. Focus on:
- Code quality and readability
- Security best practices
- Performance considerations
- Test coverage

Provide actionable feedback with examples.

Built-in Agents

Claude Code includes these built-in agents:

---

5. CLAUDE.md & AGENTS.md – Project Context

These Markdown files provide Claude with persistent context about your project.

CLAUDE.md

Automatically loaded and contains:

• Project description & architecture
• Code conventions & style guides
• Build & test commands
• Important files & structures

# Project: My Web App

## Architecture
- Frontend: Next.js 14 with App Router
- Backend: Python FastAPI
- Database: PostgreSQL with Prisma

## Commands
- `npm run dev` - Start development
- `npm test` - Run tests
- `npm run build` - Production build

## Conventions
- Use TypeScript strict mode
- Follow ESLint rules
- Write tests for all new features

AGENTS.md

Specific instructions for AI agents:

# Agent Instructions

## Code Review Rules
- Always check for security vulnerabilities
- Require test coverage for new features
- Flag deprecated API usage

## Commit Guidelines
- Use conventional commits
- Include ticket numbers
- Sign commits with GPG

Storage Locations

---

Official Claude Code Plugins

Anthropic provides 12 official Claude Code Plugins that demonstrate best practices:

1. agent-sdk-dev

Development kit for the Claude Agent SDK

2. claude-opus-4-5-migration

Migration to Claude Opus 4.5

Automated migration from Sonnet 4.x and Opus 4.1:

• Model string updates
• Beta header adjustments
• Prompt optimizations

3. code-review ⭐

Automated PR review with multi-agent system

Uses confidence scoring to filter false positives.

4. commit-commands

Git workflow automation

5. explanatory-output-style

Learning-oriented outputs

Session start hook that instructs Claude to explain implementation decisions and codebase patterns.

6. feature-dev ⭐

Structured 7-phase feature development workflow

7. frontend-design

Professional frontend design

Skill for creating distinctive, production-ready interfaces. Avoids generic "AI aesthetics" by focusing on:

• Typography & spacing
• Animations & micro-interactions
• Visual details

8. hookify

Custom hook generator

Analyzes conversations to identify problematic behavior patterns.

9. learning-output-style

Interactive learning mode

Hook that encourages users to write 5-10 lines of code themselves at decision points.

10. plugin-dev ⭐

Plugin development toolkit

11. pr-review-toolkit

Comprehensive PR review system

/pr-review-toolkit:review-pr [aspects]

Available aspects: comments, tests, errors, types, code, simplify, all

12. ralph-wiggum

Self-referential iteration loops

Claude works repeatedly on the same task until completion.

13. security-guidance

Security reminder hook

Monitors 9 security patterns during file edits:

• Command injection
• XSS vulnerabilities
• eval() usage
• Dangerous HTML
• Pickle deserialization
• os.system calls
• And more...

---

Claude Code Plugins Installation

Method 1: Via Marketplace

# In Claude Code
/plugin install marketplace-name/plugin-name

Method 2: Local Development

# Load plugin directory
claude --plugin-dir ./my-plugin

Method 3: Project Configuration

In .claude/settings.json:

{
  "plugins": [
    {
      "name": "my-plugin",
      "source": "./plugins/my-plugin"
    }
  ]
}

---

Creating Custom Claude Code Plugins

Step 1: Create Plugin Structure

mkdir -p my-plugin/.claude-plugin
mkdir -p my-plugin/commands
mkdir -p my-plugin/agents

Step 2: Create Manifest

// my-plugin/.claude-plugin/plugin.json
{
  "name": "my-plugin",
  "description": "My first Claude Code plugin",
  "version": "1.0.0"
}

Step 3: Add a Command

<!-- my-plugin/commands/hello.md -->
---
description: Greets the user warmly
---

# Hello Command

Greet the user named "$ARGUMENTS" warmly and ask how you can help.

Step 4: Test

claude --plugin-dir ./my-plugin
# Then in Claude Code:
/my-plugin:hello Max

Step 5: Add an Agent

# my-plugin/agents/reviewer.md
---
name: code-reviewer
description: Performs code reviews. Use proactively after code changes.
tools: Read, Grep, Glob
model: sonnet
---

You are an experienced code reviewer. Check:
1. Code quality and readability
2. Security vulnerabilities
3. Performance issues
4. Test coverage

Step 6: Add Hooks

// my-plugin/hooks/hooks.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint:fix $FILE"
          }
        ]
      }
    ]
  }
}

---

Claude Code Plugins Best Practices

1. Naming Conventions

plugin-name/           # kebab-case for plugin names
├── commands/
│   └── my-command.md  # kebab-case for command names
├── agents/
│   └── my-agent.md    # kebab-case for agent names
└── skills/
    └── my-skill/      # kebab-case for skill folders
        └── SKILL.md   # UPPERCASE for SKILL.md

2. Focused Components

Each component should do one thing well:

# ❌ Bad: One agent for everything
---
name: super-agent
description: Does everything
---

# ✅ Good: Specialized agents
---
name: security-reviewer
description: Reviews code for security vulnerabilities only
tools: Read, Grep
---

3. Clear Descriptions

Descriptions help Claude decide when to use an agent/skill:

# ❌ Vague
description: Helps with code

# ✅ Specific
description: Reviews TypeScript code for type safety issues. Use proactively when editing .ts or .tsx files.

4. Tool Restriction

Give agents only the tools they need:

# Security reviewer only needs read access
tools: Read, Grep, Glob

# Build agent also needs Bash
tools: Read, Write, Bash

---

Claude Code Plugins vs Other Extensions: When to Use What?

---

Claude Code Plugins: Conclusion

Claude Code Plugins and the broader Claude Code extension system offer maximum flexibility:

• Plugins for complete, distributable packages
• Skills for contextual capabilities
• MCP Servers for external tool integration
• Agents for specialized task delegation
• CLAUDE.md for project context

With the 12 official Claude Code Plugins as inspiration and this guide as reference, you can perfectly customize Claude Code Plugins for your development workflows.

Next Steps:

1. Install an official plugin like code-review or feature-dev
2. Create your first custom plugin with a simple command
3. Experiment with agents and skills
4. Share your plugins via team marketplaces

---

Claude Code Plugins: Frequently Asked Questions

What's the difference between a Claude Code Plugin and an MCP Server?

Claude Code Plugins are Claude Code-specific extension packages that bundle Commands, Agents, Skills, and Hooks. MCP Servers are protocol-based tool servers that can be used by any MCP-compatible client. Plugins can configure MCP servers, but MCP servers are usable independently of plugins.

Can I convert existing Claude Code .claude/ configurations to plugins?

Yes! You can copy your existing commands from .claude/commands/, agents from .claude/agents/, and skills from .claude/skills/ directly into a plugin directory. Just add a .claude-plugin/plugin.json manifest and your configuration becomes a shareable Claude Code Plugin.

When should I use a Claude Code Agent instead of a Claude Code Skill?

Use Agents when you need: your own context window, restricted tool access, a different model (e.g., Haiku for fast searches), or to delegate complex multi-step tasks. Use Skills for simpler capability extensions that should run in the main context.

How can I share plugins with my team?

Several options: 1) Create a team marketplace (Git repository with plugin index), 2) Share the plugin directory via your monorepo, 3) Publish to a public marketplace. For team use, a private Git-based marketplace is recommended.

Which hooks are most useful for developer workflows?

The most popular hooks are: PostToolUse for automatic linting after file changes, PreToolUse for security checks before dangerous operations, and SessionStart for context injection. The security-guidance plugin demonstrates effective PreToolUse hooks for security monitoring.