Claude Code Plugins vs Skills: What Each Does and When to Use Them

The Confusion Is Real

Claude Code has three extension mechanisms that overlap in name and function: skills, plugins, and MCP servers. The community keeps asking the same question: "Should I make a plugin or a skill?"

The answer depends on what you are building and who needs to use it. These are not competing options. They are layers in a stack.

Think of it like a web application. MCP is the HTTP layer. Skills are the business logic. Plugins are the Docker container that ships both to production. You can use each layer independently, but the most useful setups combine all three.

What Are Claude Code Skills?

A skill is a folder containing a SKILL.md file with YAML frontmatter and markdown instructions. When a skill is relevant to the current conversation, Claude loads it automatically and follows the instructions. You can also invoke skills manually with /skill-name.

Skills were the original extension mechanism, released with Claude Code in 2025. Over 60% of advanced Claude Code users create at least one custom skill within their first week.

Skill Structure

my-deploy-skill/
├── SKILL.md          # Required: instructions + metadata
├── scripts/          # Optional: executable scripts
│   └── deploy.sh
├── references/       # Optional: reference docs
│   └── runbook.md
└── assets/           # Optional: templates, configs
    └── template.yaml

---
name: deploy-to-production
description: Handles production deployments with pre-flight checks and rollback
disable-model-invocation: false
---

# Production Deployment

## Pre-flight Checks
1. Run `bun run typecheck:fast` and confirm zero errors
2. Run `bun run test` and confirm all tests pass
3. Check git status for uncommitted changes

## Deploy Steps
1. Create a git tag with semantic version
2. Push to main branch
3. Monitor Vercel deployment dashboard for errors
4. Run smoke tests against production URL

## Rollback
If smoke tests fail, revert the last commit and force-push.

Where Skills Live

Invocation Modes

By default, Claude matches skill descriptions against conversation context and loads relevant skills automatically. A skill about deployment activates when you mention deploying. You can control this behavior in the SKILL.md frontmatter:

• disable-model-invocation: true prevents Claude from auto-loading the skill. You must invoke it manually with /skill-name. Use this for skills with side effects like deployments or sending messages.
• user-invocable: false makes the skill invisible as a command. Only Claude can load it based on context. Use this for background knowledge that should not be a direct command.

What Are Claude Code Plugins?

A plugin is a distributable package that bundles skills, MCP server configurations, hooks, slash commands, and sub-agents into a single installable unit. Plugins shipped with Claude Cowork on January 30, 2026.

If a skill is a single procedure, a plugin is the entire toolkit for a job function. The legal team does not want to configure MCP connectors and write SKILL.md files individually. They want to install one thing and have /review-contract work against their playbook.

Plugin Structure

.claude-plugin/
├── plugin.json       # Required: name, version, description
├── commands/         # Slash commands (markdown prompt templates)
│   └── review.md
├── agents/           # Specialized sub-agents
│   └── reviewer/
│       └── AGENT.md
├── skills/           # Skills bundled with the plugin
│   └── contract-analysis/
│       └── SKILL.md
├── hooks/            # Event handlers (pre/post tool execution)
│   └── lint-on-edit.sh
└── .mcp.json         # MCP server configurations

{
  "name": "legal-review",
  "version": "1.0.0",
  "description": "Contract review toolkit with clause extraction and risk scoring",
  "author": "your-team",
  "skills": ["contract-analysis"],
  "commands": ["review"],
  "agents": ["reviewer"],
  "hooks": {
    "PostToolUse": ["lint-on-edit.sh"]
  }
}

What Plugins Can Contain

Installing Plugins

Plugins can be installed from the Anthropic plugin registry, from GitHub repositories, or loaded locally during development. Anthropic maintains an official directory of curated plugins at anthropics/claude-plugins-official.

# Install from registry
/plugin install legal-review

# Install from GitHub
/plugin install github:your-org/legal-review-plugin

# Load locally for development
claude --plugin-dir ./my-plugin

What Is MCP (Model Context Protocol)?

MCP is an open standard for connecting AI models to external systems. Build the connector once and it works across Claude Code, ChatGPT, Cursor, and any tool that speaks the protocol. MCP handles the transport: authentication, request routing, and response formatting.

MCP is not specific to Claude. It is a cross-platform protocol. A GitHub MCP server works identically whether Claude Code or Cursor calls it. This makes MCP the connection layer, while skills and plugins are Claude-specific.

MCP vs Skills vs Plugins

A common confusion: people think MCP and skills are alternatives. They solve different problems. MCP gives Claude access to a system (read your database, call an API). A skill tells Claude how to use that access (always filter by date range first, use pagination for large result sets). A plugin packages both together.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "your-token" }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": { "DATABASE_URL": "postgresql://..." }
    }
  }
}

Plugins vs Skills vs MCP: Complete Comparison

The Hierarchy

Plugins contain skills. Skills reference MCP connections. MCP provides the raw access. This is not a choice between three options. It is three layers that stack.

A standalone skill is fine for project-specific workflows (your team's deploy process, your coding conventions). A standalone MCP server is fine for connecting to a single external system. A plugin is what you build when you need to hand someone a complete, ready-to-use toolkit that combines multiple skills, MCP connections, hooks, and commands.

When to Use Each

Building a Skill: Step by Step

A skill takes about 5 minutes to create. No build step, no dependencies, no registry. Create a folder, write a SKILL.md, and Claude picks it up.

Step 1: Create the Directory

mkdir -p .claude/skills/code-review
touch .claude/skills/code-review/SKILL.md

Step 2: Write the SKILL.md

---
name: code-review
description: Reviews code changes for security, performance, and style issues
disable-model-invocation: false
---

# Code Review Checklist

When reviewing code changes, follow this checklist in order:

## Security
- Check for SQL injection in any database queries
- Verify user input is sanitized before use
- Confirm authentication checks on all protected routes
- Look for hardcoded secrets or API keys

## Performance
- Flag N+1 query patterns
- Check for missing database indexes on filtered columns
- Verify pagination on list endpoints

## Style
- Confirm TypeScript strict mode compliance
- Check that new functions have return types
- Verify error messages are user-facing, not internal

Output format: list each finding as [SEVERITY] file:line description

Step 3: Test It

# Claude auto-loads it when you mention code review
$ claude "Review the changes in my last commit"

# Or invoke it explicitly
$ claude "/code-review"

Optional: Add Scripts and References

Skills can include executable scripts and reference documents. Claude reads these when the skill is loaded.

.claude/skills/code-review/
├── SKILL.md
├── scripts/
│   └── check-deps.sh    # Claude can run this
└── references/
    └── style-guide.md   # Claude reads this for context

Building a Plugin: Step by Step

Plugins require more structure but unlock distribution. The official skill-creator skill can generate the scaffolding for you, or you can build it manually.

Step 1: Create the Manifest

mkdir -p my-plugin/.claude-plugin
mkdir -p my-plugin/skills/deploy-check
mkdir -p my-plugin/commands
mkdir -p my-plugin/hooks

{
  "name": "deploy-toolkit",
  "version": "1.0.0",
  "description": "Pre-deploy checks, staging deployment, and rollback procedures",
  "author": "your-team",
  "skills": ["deploy-check"],
  "commands": ["deploy", "rollback"],
  "hooks": {
    "PreToolUse": []
  }
}

Step 2: Add Components

Add skills, commands, hooks, and MCP configs as needed. Each skill goes in its own folder under skills/. Commands are markdown files in commands/. Hooks are shell scripts.

---
name: deploy
description: Run pre-flight checks and deploy to staging or production
---

Run the deploy-check skill first. If all checks pass, deploy to the
environment specified by the user. Default to staging if not specified.

After deployment, run smoke tests and report results.

Step 3: Test Locally

# Start Claude Code with your plugin loaded
claude --plugin-dir ./my-plugin

# Verify the plugin is loaded
/plugins

# Test your commands
/deploy staging

Step 4: Publish

# Push to GitHub
git init && git add . && git commit -m "Initial plugin release"
git remote add origin git@github.com:your-org/deploy-toolkit.git
git push -u origin main

# Others install it with:
/plugin install github:your-org/deploy-toolkit

How Plugins, Skills, and MCP Work Together

Real setups combine all three layers. Here is a concrete example: a data analytics plugin for a team that queries PostgreSQL and generates reports.

data-analytics-plugin/
├── .claude-plugin/
│   └── plugin.json
├── .mcp.json                    # MCP: connects to PostgreSQL
├── skills/
│   └── query-patterns/
│       ├── SKILL.md             # Skill: how to query safely
│       └── references/
│           └── schema.md        # Reference: database schema
├── commands/
│   └── report.md               # Command: /report generates analytics
└── hooks/
    └── validate-query.sh        # Hook: blocks DROP/DELETE queries

In this setup, MCP provides the database connection. The skill tells Claude to use parameterized queries, respect rate limits, and follow the schema conventions. The hook prevents destructive SQL from executing. The command gives users a simple /report entry point.

CLAUDE.md vs Skills

Another common question: when do you put instructions in CLAUDE.md versus a skill? CLAUDE.md is always loaded into every conversation. It is for project-wide context that applies to every task: architecture decisions, coding standards, environment setup. Skills are loaded on demand for specific workflows. If the instructions only matter during deployments, make it a skill. If they matter for every interaction with your codebase, put them in CLAUDE.md.

Frequently Asked Questions

What is the difference between a Claude Code plugin and a skill?

A skill is a folder with a SKILL.md file containing instructions that Claude loads on demand. A plugin is a distributable package that can contain multiple skills, plus MCP configurations, hooks, slash commands, and sub-agents. Plugins are the container format. Skills are one type of content inside them. You can use skills without plugins, but plugins always contain or reference skills.

Should I create a skill or a plugin?

Create a skill if you are customizing Claude Code for your own project or team. A SKILL.md in .claude/skills/ takes 5 minutes and covers most use cases. Create a plugin if you need to distribute a complete toolkit to people outside your team, or if your workflow requires hooks, MCP servers, and commands in addition to skills.

How does MCP relate to plugins and skills?

MCP is the connection layer that gives Claude access to external systems. Skills tell Claude how to use those connections. Plugins package both together. You can configure MCP in your project's .mcp.json without any skills or plugins. But adding a skill that documents your database schema and query patterns makes Claude significantly more effective with that MCP connection.

Where do Claude Code skills live on disk?

Three locations: project skills in .claude/skills/ (committed to version control), personal skills in ~/.claude/skills/ (available across all your projects), and plugin skills inside a plugin's skills/ directory. Project skills are the most common. They travel with the repository so every team member and CI system gets them.

Can Claude automatically invoke skills without a slash command?

Yes. Claude reads skill descriptions and loads relevant skills based on conversation context. A skill about database migrations activates when you ask Claude to modify the schema. Set disable-model-invocation: true in the SKILL.md frontmatter if you want manual-only invocation, which is recommended for skills with side effects.

What is the difference between a hook and a skill?

Skills are probabilistic: Claude decides when to load them based on context. Hooks are deterministic: they execute 100% of the time on their trigger event. Use hooks when something must happen every time without exception, like linting after every file edit or blocking commits until tests pass. Use skills for procedures where Claude should apply judgment.