Understanding Skills, Agents, Subagents, and MCP in Claude Code: When to Use What

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

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

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

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

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

// 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 is for building deployable, autonomous agents with full decision loops.

Agents vs Skills vs Subagents

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

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

// .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 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
• GitHub
• PostgreSQL
• Slack
• Google Drive
• Puppeteer

Community servers:

• Hundreds available on Model Context Protocol website
• 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:

# 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

// 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 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 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
• Skills documentation
• Skills API guide
• Subagents documentation
• Agent SDK guide
• MCP documentation
• MCP protocol site

Code & Examples

• Skills repository
• MCP servers
• MCP TypeScript SDK

Engineering Deep Dives

• Equipping Agents for the Real World
• Building Agents with Claude 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 or LinkedIn.