---
title: "Claude Code Skills vs Subagents vs MCP: When to Use Each"
description: "Skills are portable tools, subagents handle parallel work, agents are deployable automation and MCP connects Claude to external systems. Which one to use when in Claude Code."
author: "Colin McNamara"
tags: ["AI","Claude Code","Development","MCP","Developer Tools"]
date: 2025-10-18
url: https://colinmcnamara.com/blog/understanding-skills-agents-and-mcp-in-claude-code
---

# Claude Code Skills vs Subagents vs MCP: When to Use Each

## TL;DR

Claude Code has evolved into a powerful ecosystem with four key extension mechanisms:

- **Skills**: Portable, reusable tools that work across Claude Code, Claude apps, and API
- **Subagents**: Claude Code-only feature for parallel work and context separation
- **Agents**: Deployable automation using the Claude Agent SDK for full autonomous loops
- **MCP (Model Context Protocol)**: The open standard connecting AI to external tools and data sources

**When to use what?**
- Use **Skills** when you want portable, shareable tools that work everywhere Claude does
- Use **Subagents** when you need parallel workstreams or isolated contexts in Claude Code
- Use **Agents** when building deployable, autonomous systems with decision loops
- Use **MCP** when integrating external APIs, databases, or third-party systems

Let's dive deeper into each.

---

## What Are Skills?

[Skills](https://www.anthropic.com/news/skills) are portable, reusable capabilities that extend what Claude can do. They're the most versatile extension mechanism because they work across Claude Code, Claude apps (web and mobile), and the API.

### The Anatomy of a Skill

A Skill uses **progressive disclosure** - Claude only sees what it needs, when it needs it:

1. **Skill name and description** (always visible in system prompt)
2. **SKILL.md file** (loaded when Claude needs details)
3. **Additional files** (like code snippets, loaded as needed)

This design keeps context efficient while providing rich functionality.

### Example: A Simple Skill

```
my-calculator-skill/
├── SKILL.md           # Main documentation
├── calculator.py      # Executable code
└── examples.txt       # Usage examples
```

**SKILL.md:**
```markdown
# Calculator Skill

Performs mathematical calculations with high precision.

## Usage

Use the calculator.py executable:
- Input: Mathematical expression as string
- Output: Calculated result with full precision

## Examples

See examples.txt for common use cases.
```

When you install this Skill:
- Claude sees: "Calculator Skill - Performs mathematical calculations"
- When needed: Claude reads SKILL.md for details
- If necessary: Claude reads examples.txt or executes calculator.py

### Skills Work Everywhere

The same Skill file works in:
- **Claude Code**: Desktop coding assistant
- **Claude.ai**: Web interface
- **Claude mobile apps**: iOS/Android
- **Claude API**: Programmatic access

This portability makes Skills ideal for tools you want to share across your team or the community.

### Skills Can Include Code

Skills aren't just documentation - they can include **executable code**:

```python
# in a Skill file
def analyze_logs(log_file):
    """Deterministic log analysis"""
    # This code runs locally
    # Results returned to Claude
    return parsed_results
```

This enables:
- **Deterministic operations** (precise math, data parsing)
- **Local processing** (sensitive data stays on your machine)
- **Tool integration** (call existing scripts/tools)

### Installing Skills

**In Claude Code:**

```bash
# Register the Skills marketplace (one-time setup)
/plugin marketplace add anthropics/skills

# Then use skills by mentioning them in conversation
# Example: "use the pdf skill to extract form fields from my-form.pdf"
```

**In Claude.ai:**

Skills are pre-installed for paid plans (Pro, Team, Enterprise). Enable them in Settings > Features.

**Via API:**

Upload skills programmatically using the Skills API. See the [Skills API Quickstart](https://docs.claude.com/en/api/skills-guide#creating-a-skill).

### Skills Best Practices

1. **Clear descriptions**: Name and description appear in every Claude interaction
2. **Focused purpose**: One Skill should do one thing well
3. **Portable design**: Avoid platform-specific code
4. **Security first**: Only install Skills from trusted sources

**Security Note**: Skills can execute code on your machine. Only install from trusted sources and review the code first.

---

## What Are Subagents?

[Subagents](https://docs.claude.com/en/docs/claude-code/sub-agents) are a **Claude Code-only** feature for spawning parallel Claude instances with isolated contexts.

### When to Use Subagents

Use Subagents for:
- **Parallel workstreams**: Research in one agent, coding in another
- **Context separation**: Keep different tasks isolated
- **Long-running tasks**: Spin off background work
- **Different perspectives**: Have one agent review another's work

### How Subagents Work

```javascript
// In Claude Code
"I need to refactor this codebase. Can you spawn a subagent to:
1. Research best practices for this architecture
2. Document current code structure
While I continue working on the core implementation"
```

Each Subagent:
- Has its own **isolated context** (doesn't pollute main conversation)
- Can access the **same tools and files** as the parent
- Works **in parallel** with parent and other Subagents
- **Reports back** results when complete

### Subagent Example: Parallel Development

**Parent Claude**: "I'm refactoring the authentication system"

**Subagent 1**: Researching OAuth 2.0 best practices
**Subagent 2**: Documenting current auth flow
**Subagent 3**: Writing tests for new implementation

All three work simultaneously, then report findings to parent.

### Limitations

- **Claude Code only**: Not available in Claude apps or API
- **Same capabilities as parent**: Subagents don't get special powers
- **Context isolation**: Can't directly share information between Subagents
- **Resource usage**: Each Subagent counts toward your usage limits

---

## What Are Agents? (Claude Agent SDK)

The [Claude Agent SDK](https://www.anthropic.com/engineering/building-agents-with-the-claude-agent-sdk) is for building **deployable, autonomous agents** with full decision loops.

### Agents vs Skills vs Subagents

| Feature | Skills | Subagents | Agents (SDK) |
|---------|--------|-----------|--------------|
| **Purpose** | Portable tools | Parallel work | Autonomous systems |
| **Where** | Code/Apps/API | Claude Code only | Deployable anywhere |
| **Loop** | No | No | Yes (agentic loop) |
| **Autonomy** | Tool only | Claude-controlled | Fully autonomous |
| **Use Case** | Reusable capabilities | Multi-tasking | Production automation |

### When to Build an Agent

Build an Agent with the SDK when you need:
- **Autonomous decision loops**: Agent decides next steps
- **Production deployment**: Runs independently of Claude Code
- **Long-running tasks**: Operates without human interaction
- **Integration workflows**: Orchestrates multiple systems
- **Proactive actions**: Monitors and responds automatically

### Agent Example: CI/CD Monitor

```python
from anthropic import Anthropic

client = Anthropic()

# Agent with tools
tools = [
    {
        "name": "check_ci_status",
        "description": "Check CI pipeline status",
        "input_schema": {
            "type": "object",
            "properties": {
                "repo": {"type": "string"},
                "branch": {"type": "string"}
            }
        }
    },
    {
        "name": "notify_team",
        "description": "Send notification to team",
        "input_schema": {
            "type": "object",
            "properties": {
                "message": {"type": "string"},
                "channel": {"type": "string"}
            }
        }
    }
]

# Agentic loop
while True:
    response = client.messages.create(
        model="claude-3-5-sonnet-20241022",
        max_tokens=1024,
        tools=tools,
        messages=[{
            "role": "user",
            "content": "Monitor CI/CD pipeline and notify team of issues"
        }]
    )

    # Agent decides: check status, analyze results, notify if needed
    if response.stop_reason == "stop":
        break

    # If tool_use, execute the tools and continue loop
    # (Tool execution logic would go here)
```

This agent runs continuously, makes decisions, and takes actions without human intervention.

### Agent Best Practices

1. **Clear goals**: Define success criteria explicitly
2. **Safety limits**: Max iterations, timeout, budget constraints
3. **Human oversight**: Critical actions require approval
4. **Monitoring**: Log decisions and actions
5. **Error handling**: Graceful degradation

---

## What is MCP (Model Context Protocol)?

[MCP](https://www.anthropic.com/news/model-context-protocol) is the **open protocol** for connecting AI to external systems. Think of it as a universal adapter between LLMs and the tools they need.

### Why MCP Matters

**Before MCP**: Every tool integration was custom
- Twitter integration → custom code
- Database access → custom code
- Slack integration → custom code
- **N tools × M AI systems = N×M integrations**

**With MCP**: Standard protocol
- Tools expose MCP interface
- AI systems speak MCP
- **N tools + M AI systems = N+M implementations**

### MCP Architecture

```
┌─────────────────────────────────────────────────┐
│                Claude Code / Apps                │
│                                                  │
│  ┌──────────────────────────────────────────┐  │
│  │            MCP Client                     │  │
│  └────────────┬──────────────┬───────────────┘  │
│               │              │                   │
└───────────────┼──────────────┼──────────────────┘
                │              │
         ┌──────▼────┐  ┌──────▼────┐
         │ MCP Server│  │ MCP Server│
         │ (GitHub)  │  │ (Postgres)│
         └───────────┘  └───────────┘
```

### MCP Components

1. **MCP Client** (in Claude Code)
   - Discovers available servers
   - Routes requests to appropriate server
   - Handles responses

2. **MCP Server** (for each tool/system)
   - Exposes capabilities (tools, resources, prompts)
   - Handles requests from client
   - Returns structured responses

### MCP Example: Connecting to GitHub

```json
// .mcp.json configuration
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "your_token_here"
      }
    }
  }
}
```

> **Note**: MCP server packages are actively developed. Check [modelcontextprotocol.io](https://modelcontextprotocol.io) for the latest package names and installation instructions.

Now Claude can:
- List repositories
- Create issues
- Read pull requests
- Comment on code
- All through standard MCP protocol

### Available MCP Servers

**Official Anthropic servers:**
- [File system](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem)
- [GitHub](https://github.com/modelcontextprotocol/servers/tree/main/src/github)
- [PostgreSQL](https://github.com/modelcontextprotocol/servers/tree/main/src/postgres)
- [Slack](https://github.com/modelcontextprotocol/servers/tree/main/src/slack)
- [Google Drive](https://github.com/modelcontextprotocol/servers/tree/main/src/gdrive)
- [Puppeteer](https://github.com/modelcontextprotocol/servers/tree/main/src/puppeteer)

**Community servers:**
- Hundreds available on [Model Context Protocol website](https://modelcontextprotocol.io)
- Everything from databases to APIs to custom systems

---

## How They Work Together

These four mechanisms complement each other:

### Example Workflow: Building a CI/CD Dashboard

**1. Use MCP** to connect to:
- GitHub (code and PRs)
- CircleCI (build status)
- Slack (notifications)
- PostgreSQL (metrics database)

**2. Create a Skill** for:
- Analyzing build trends
- Generating status reports
- Calculating deployment metrics

**3. Use Subagents** in Claude Code for:
- Agent 1: Monitor build failures
- Agent 2: Analyze test coverage trends
- Agent 3: Research optimization strategies

**4. Deploy an Agent** (SDK) that:
- Continuously monitors CI/CD pipeline
- Decides when to alert team
- Automatically creates issues for recurring failures
- Runs 24/7 without human intervention

### Decision Framework

**Ask yourself:**

1. **Do I need this portable?**
   - Yes → **Skill**
   - No → Consider other options

2. **Do I need parallel work in Claude Code?**
   - Yes → **Subagent**
   - No → Continue

3. **Do I need autonomous operation?**
   - Yes → **Agent (SDK)**
   - No → Continue

4. **Do I need to connect external systems?**
   - Yes → **MCP**

You can use multiple approaches together!

---

## Getting Started

### Install Your First Skill

**Claude Code:**
```bash
# Register the Skills marketplace
/plugin marketplace add anthropics/skills

# Use a skill in conversation
cd /path/to/git/repo
# Then ask: "use the skill-creator skill to help me build a custom skill"
```

**Claude.ai:**
Go to Settings > Features > Enable Skills (paid plans only)

### Try a Subagent

In Claude Code:
```
"I'm working on authentication. Can you spawn a subagent to research
OAuth 2.0 best practices while I continue coding?"
```

### Connect Your First MCP Server

```json
// Add to .mcp.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
    }
  }
}
```

Restart Claude Code and ask:
```
"List all Python files in the project"
```

### Build Your First Agent

Follow the [Claude Agent SDK guide](https://www.anthropic.com/engineering/building-agents-with-the-claude-agent-sdk) to create an autonomous agent.

---

## Security Considerations

### Skills
- ⚠️ Skills can execute code on your machine
- ✅ Only install from trusted sources
- ✅ Review code before installing
- ✅ Use `claude skills list` to audit installed Skills

### MCP Servers
- ⚠️ MCP servers have access to specified resources
- ✅ Review server permissions carefully
- ✅ Use environment variables for credentials
- ✅ Limit server access scope (read-only when possible)

### Agents
- ⚠️ Agents operate autonomously
- ✅ Implement safety limits (max iterations, budget)
- ✅ Require approval for critical actions
- ✅ Log all decisions and actions
- ✅ Monitor agent behavior

---

## Real-World Examples

### Example 1: Development Team Workflow

**Skills installed:**
- Git commit message generator
- Code review analyzer
- Test coverage reporter

**MCP servers:**
- GitHub (issues, PRs)
- PostgreSQL (metrics)
- Slack (team communication)

**Daily usage:**
- Claude Code with Subagents for parallel development
- Agent (SDK) monitoring CI/CD and creating alerts
- Skills for consistent code quality practices

### Example 2: Content Creator Workflow

**Skills installed:**
- SEO analyzer
- Social media post optimizer
- Image description generator

**MCP servers:**
- WordPress (blog management)
- Twitter API (social posting)
- Google Drive (asset storage)

**Daily usage:**
- Claude apps for brainstorming (Skills work there too!)
- Agent (SDK) for scheduled content posting
- MCP for managing published content

### Example 3: Data Analyst Workflow

**Skills installed:**
- SQL query optimizer
- Data visualization generator
- Report formatter

**MCP servers:**
- PostgreSQL (data warehouse)
- S3 (data files)
- Jupyter (notebooks)

**Daily usage:**
- Claude Code for analysis work
- Subagents for parallel data exploration
- MCP for database access

---

## The Future

This ecosystem is rapidly evolving:

**Skills**: Growing library on [GitHub](https://github.com/anthropics/skills)
**MCP**: Hundreds of servers being built by community
**Agent SDK**: More sophisticated agent patterns emerging
**Subagents**: Potential for more advanced orchestration

The key insight: **These aren't competing approaches** - they're complementary tools for different needs.

---

## Resources

### Official Documentation
- [Skills announcement](https://www.anthropic.com/news/skills)
- [Skills documentation](https://docs.claude.com/en/docs/claude-code/skills)
- [Skills API guide](https://docs.claude.com/en/api/skills-guide)
- [Subagents documentation](https://docs.claude.com/en/docs/claude-code/sub-agents)
- [Agent SDK guide](https://www.anthropic.com/engineering/building-agents-with-the-claude-agent-sdk)
- [MCP documentation](https://docs.claude.com/en/docs/claude-code/mcp)
- [MCP protocol site](https://modelcontextprotocol.io)

### Code & Examples
- [Skills repository](https://github.com/anthropics/skills)
- [MCP servers](https://github.com/modelcontextprotocol/servers)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)

### Engineering Deep Dives
- [Equipping Agents for the Real World](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
- [Building Agents with Claude SDK](https://www.anthropic.com/engineering/building-agents-with-the-claude-agent-sdk)

---

## Conclusion

The Claude Code ecosystem gives you:

- **Skills** for portable, reusable capabilities
- **Subagents** for parallel work and context separation
- **Agents** for autonomous, deployable systems
- **MCP** for connecting to external tools and data

Start simple:
1. Install a Skill from the community
2. Try spawning a Subagent for your next coding session
3. Connect an MCP server to a tool you use daily
4. Build an Agent when you need autonomous operation

The ecosystem is designed to grow with your needs - from simple tools to sophisticated multi-agent systems.

**What will you build first?**

---

*Have questions about Skills, Agents, or MCP? Found this helpful? Let me know on [Twitter/X](https://twitter.com/colinmcnamara) or [LinkedIn](https://linkedin.com/in/colinmcnamara).*