---
type: "BlogPosting"
title: "Claude Code Plugins: The Complete Guide to the Extension System 2025"
description: "Claude Code Plugins revolutionize AI-powered development. Understand the differences between Skills, Plugins, MCP Servers, and Agents – and extend Claude Code with custom functionality."
resource: "https://www.contextstudios.ai/blog/claude-code-plugins-the-complete-guide-to-the-extension-system-2025"
language: "en"
tags: ["Claude Code", "Plugins", "MCP", "AI Development", "Anthropic", "Developer Tools", "Automation"]
generated:
  by: "process:contextstudios-md/1"
  at: "2026-10-08T19:59:08.259Z"
status: "stable"
---

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

Published: 2026-01-04
Tags: Claude Code, Plugins, MCP, AI Development, Anthropic, Developer Tools, Automation

![Claude Code Plugins: The Complete Guide to the Extension System 2025](https://wary-platypus-754.convex.cloud/api/storage/a6e2f14d-e250-41f9-aeaf-a67a5ee19ae1)

# 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:

| Component | Purpose | Invocation | Scope |
|-----------|---------|------------|-------|
| **Plugins** | Reusable packages with Commands, Agents, Skills & Hooks | `/plugin-name:command` | Team/Community |
| **Skills** | Contextual capabilities for Claude | Automatically by Claude | Project/User |
| **MCP Servers** | External tool integration | Via tool calls | Universal |
| **Agents/Subagents** | Specialized AI assistants | Via task delegation | Session |
| **CLAUDE.md** | Project context & rules | Automatically loaded | Project |

### 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)

```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

| Aspect | Skills | Plugins |
|--------|--------|---------|
| Invocation | Automatic by Claude | Explicit via `/command` |
| Namespace | No namespace | `plugin-name:command` |
| Distribution | Local or via Plugin | Via marketplaces |
| Complexity | Single SKILL.md | Multi-component package |

### Skill Structure (SKILL.md)

```yaml
---
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

| Type | Path | Priority |
|------|------|----------|
| Project | `.claude/skills/` | Highest |
| User | `~/.claude/skills/` | Medium |
| Plugin | `plugin/skills/` | Lowest |

---

## 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

| Aspect | MCP Servers | Plugins |
|--------|-------------|---------|
| Protocol | Standardized (JSON-RPC) | Claude Code specific |
| Client | Any MCP client | Claude Code only |
| Transport | stdio, HTTP, WebSocket | Integrated |
| Focus | Tool integration | Workflow extension |

### Including MCP in Plugins

Plugins can configure MCP servers via `.mcp.json`:

```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

| Aspect | Agents | Skills |
|--------|--------|--------|
| Execution | Own context window | In main context |
| Tools | Configurable/restrictable | Inherits all tools |
| Model | Configurable | Main model |
| Purpose | Task delegation | Capability extension |

### Agent Definition

```yaml
---
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:

| Agent | Purpose | Model |
|-------|---------|-------|
| **general-purpose** | Complex multi-step tasks | Sonnet |
| **Explore** | Codebase search (read-only) | Haiku |
| **Plan** | Research in plan mode | Sonnet |

---

## 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

```markdown
# 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:

```markdown
# 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

| File | Paths |
|------|-------|
| CLAUDE.md | `./CLAUDE.md`, `./.claude/CLAUDE.md` |
| AGENTS.md | `./AGENTS.md`, `./.claude/AGENTS.md` |

---

## 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**

| Component | Description |
|-----------|-------------|
| Command | `/new-sdk-app` – Interactive setup for Agent SDK projects |
| Agents | `agent-sdk-verifier-py`, `agent-sdk-verifier-ts` – Validation against best practices |

### 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**

| Component | Description |
|-----------|-------------|
| Command | `/code-review` – Starts review workflow |
| Agents | 5 parallel Sonnet agents for: CLAUDE.md compliance, bug detection, historical context, PR history, code comments |

Uses confidence scoring to filter false positives.

### 4. commit-commands
**Git workflow automation**

| Command | Function |
|---------|----------|
| `/commit` | Commit changes |
| `/commit-push-pr` | Commit, push & create PR |
| `/clean_gone` | Clean up deleted remote branches |

### 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**

| Component | Description |
|-----------|-------------|
| Command | `/feature-dev` – Guided development workflow |
| Agents | `code-explorer` – Codebase analysis |
| | `code-architect` – Architecture design |
| | `code-reviewer` – Quality review |

### 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**

| Command | Function |
|---------|----------|
| `/hookify` | Creates custom hooks |
| `/hookify:list` | Lists existing hooks |
| `/hookify:configure` | Configures hooks |
| `/hookify:help` | Shows help |

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**

| Component | Description |
|-----------|-------------|
| Command | `/plugin-dev:create-plugin` – 8-phase guided plugin creation process |
| Agents | `agent-creator`, `plugin-validator`, `skill-reviewer` |
| Skills | Hook development, MCP integration, plugin structure, settings, commands, agents, skill development |

### 11. pr-review-toolkit
**Comprehensive PR review system**

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

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

| Agent | Focus |
|-------|-------|
| `comment-analyzer` | Comment quality |
| `pr-test-analyzer` | Test coverage |
| `silent-failure-hunter` | Silent failures |
| `type-design-analyzer` | Type system design |
| `code-reviewer` | Code quality |
| `code-simplifier` | Simplifications |

### 12. ralph-wiggum
**Self-referential iteration loops**

| Command | Function |
|---------|----------|
| `/ralph-loop` | Starts autonomous iteration |
| `/cancel-ralph` | Stops iteration |

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

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

### Method 2: Local Development

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

### Method 3: Project Configuration

In `.claude/settings.json`:

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

---

## Creating Custom Claude Code Plugins

### Step 1: Create Plugin Structure

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

### Step 2: Create Manifest

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

### Step 3: Add a Command

```markdown
<!-- 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

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

### Step 5: Add an Agent

```yaml
# 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

```json
// 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:

```yaml
# ❌ 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:

```yaml
# ❌ 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:

```yaml
# 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?

| Use Case | Recommendation |
|----------|----------------|
| Personal workflow customization | Skills in `.claude/skills/` |
| Team-wide standards | Plugin via marketplace |
| External API integration | MCP Server |
| Specialized task delegation | Custom Agents |
| Project context for Claude | CLAUDE.md |
| AI-specific rules | AGENTS.md |
| Event-based automation | Hooks |
| Code intelligence for new languages | LSP via Plugin |

---

## 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.

## Related

- [AI Agent Development](https://www.contextstudios.ai/ai-agent-development.md)
- [AI Development](https://www.contextstudios.ai/ai-development.md)
- [AI API Development](https://www.contextstudios.ai/ai-api-development.md)
- [AI Automation](https://www.contextstudios.ai/ai-automation.md)