guides / agents-skills-mcp
THE COMPLETE REFERENCE

Agents, Skills & MCP

Claude Code Jan 2026 Architecture Guide

Claude Code extends its capabilities through three mechanisms: Agents, Skills, and MCP servers. They look similar but serve different purposes. This guide explains what each one does, how they differ, and when to use which.

Overview

Think of Claude as the brain. Agents, Skills, and MCPs are different ways to give that brain new capabilities. Here's the quick version:

A

Agents

Autonomous workers

Separate Claude instances that run independently to complete complex tasks. They have their own context and return results when done.

Spawns subprocess Own memory Returns results
S

Skills

Defined workflows

Instruction sets that tell Claude how to perform specific tasks. They run in the current conversation, not as separate processes.

Same context Follows steps User-invokable
M

MCP Servers

External connections

Bridges to external systems—APIs, databases, browsers, services. They give Claude tools to interact with the outside world.

External APIs Provides tools Always available

Agents

Agents are autonomous Claude instances spawned via the Task tool. When you ask Claude to do something complex, it can delegate work to specialized agents that run in parallel or sequence.

How Agents Work

  1. Claude receives a task that would benefit from delegation
  2. It spawns an agent using Task with a specific subagent_type
  3. The agent runs independently with its own context window
  4. When complete, it returns results to the parent Claude
  5. Claude synthesizes the results and continues

Key Characteristics

  • Separate process: Agents don't share memory with the main conversation. They start fresh with only the prompt you give them.
  • Specialized types: Different agent types have access to different tools. An Explore agent can search but can't edit. A Bash agent runs commands.
  • Parallel execution: Multiple agents can run simultaneously. Ask Claude to "research X and Y in parallel" and it spawns two agents.
  • Background mode: Agents can run in the background while you continue working. Check on them later with TaskOutput.
AVAILABLE AGENT TYPES
Explore Search codebases, find files, answer questions about code
Bash Execute terminal commands, git operations
Plan Design implementation strategies, identify critical files
general-purpose Research, multi-step tasks, code search
keyword-research SEO keyword analysis and opportunities
content-strategist Research topics, create content briefs
SPAWNING AN AGENT
// Claude uses the Task tool internally:
Task(
  subagent_type: "Explore",
  prompt: "Find all API endpoints",
  description: "Search for endpoints"
)

Skills

Skills are instruction files that teach Claude how to perform specific tasks. When you invoke a skill (like /commit), Claude reads the skill file and follows its instructions within your current conversation.

How Skills Work

  1. User invokes a skill with /skill-name or Claude detects it should use one
  2. Claude reads the SKILL.md file for that skill
  3. The instructions become part of Claude's current context
  4. Claude follows the defined workflow step by step
  5. Everything happens in your conversation—no separate process

Key Characteristics

  • Same conversation: Skills run in your current context. Claude remembers what you discussed before invoking the skill.
  • Defined workflows: Skills contain step-by-step instructions. They ensure consistent, repeatable processes.
  • User-invokable: Many skills can be triggered with /command. Others activate automatically based on context.
  • Customizable: Skills are just markdown files. You can edit them, create new ones, or override defaults in your project's .claude/skills/ folder.

Skill File Structure

Skills live in .claude/skills/skill-name/SKILL.md. The file contains instructions, examples, and any context Claude needs to execute the workflow.

COMMON SKILLS
/commit Stage changes, write commit message, push
/blog-writer Research and write SEO blog posts
/branded-deck Create branded presentations
/think-harder Spawn critic/research agents for complex tasks
/close End session, capture learnings
/start Resume from last session state
SKILL.MD STRUCTURE
# Skill Name

## Trigger
When user says "/command"

## Steps
1. First, do X
2. Then check Y
3. Finally, output Z

## Examples
...

MCP Servers

MCP (Model Context Protocol) servers are external processes that give Claude access to tools it doesn't have natively. They're bridges to APIs, databases, browsers, and other systems.

How MCP Works

  1. MCP servers run as separate processes alongside Claude Code
  2. They register tools with Claude (like mcp__github__create_issue)
  3. When Claude needs that capability, it calls the MCP tool
  4. The MCP server executes the action and returns results
  5. Claude continues with the response

Key Characteristics

  • External connections: MCPs connect to things Claude can't access directly—GitHub API, Supabase, Slack, browsers, etc.
  • Tool providers: Each MCP exposes specific tools. The GitHub MCP provides tools like create_issue, create_pull_request, etc.
  • Always available: Once configured, MCP tools are available in every conversation. No need to invoke them specially.
  • Requires setup: MCPs need configuration in your settings. They often require API keys or authentication.

Configuration

MCPs are configured in ~/.claude/settings.json or your project's .claude/settings.json. Each server specifies a command to run and any required environment variables.

COMMON MCP SERVERS
GitHub Issues, PRs, repos, code search
Supabase Database queries, migrations, auth
Slack Read/send messages, channels
Browser (Chrome) Navigate, click, fill forms, screenshots
Brevo Email campaigns, contacts, templates
SEO Research Keywords, traffic, backlinks
MCP CONFIG EXAMPLE
// settings.json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_..."
      }
    }
  }
}

Key Differences

The confusion usually comes from the fact that all three "extend" Claude's capabilities. But they do so in fundamentally different ways:

Aspect Agents Skills MCP
What it is Separate Claude instance Instruction file External server process
Runs where New subprocess Current conversation Background process
Memory Fresh context (no history) Shares conversation context Stateless (per-call)
Purpose Delegate complex work Follow defined workflows Connect to external systems
Invocation Claude spawns automatically /command or auto-detected Claude calls when needed
Customization Built-in types only Create/edit SKILL.md files Configure in settings.json
User interaction Returns results at end Interactive (can ask questions) Transparent (tool calls)
Best for Research, parallel work Repeatable processes API/service integration
ANALOGY
Agents are like hiring a contractor. They work independently and report back when done. They don't know your ongoing conversations.
Skills are like following a recipe. You (Claude) follow the steps yourself, in your kitchen (conversation), with all your context.
MCPs are like having a phone. You can call GitHub, Slack, or your database whenever you need to interact with them.

When to Use What

Use an Agent when...

  • The task requires extensive searching or exploration
  • You want work done in the background
  • Multiple independent tasks can run in parallel
  • The task is self-contained and doesn't need conversation history
  • You want to reduce context window usage in main conversation
"Search the codebase for all auth-related files" "Research how the payment system works" "Find and fix all TypeScript errors"

Use a Skill when...

  • You want a consistent, repeatable process
  • The workflow needs access to conversation context
  • User interaction might be needed during execution
  • You want to customize how Claude handles specific tasks
  • The process should follow your team's standards
"/commit" — consistent commit workflow "/blog-writer" — content creation process "/close" — session wrap-up routine

Use MCP when...

  • You need to interact with external APIs or services
  • Claude needs capabilities it doesn't have natively
  • You want persistent connections to tools like GitHub, Slack
  • The integration requires authentication or API keys
  • You're automating across multiple systems
"Create a GitHub issue for this bug" "Query the production database" "Send a Slack message to #engineering"
DECISION FLOWCHART
Does it need external API access? Yes → MCP No ↓
Is it a repeatable workflow you want consistent? Yes → Skill No ↓
Is it complex research or parallel work? Yes → Agent No → Just ask Claude directly

Real-World Examples

Agent

Codebase Exploration

"I need to understand how authentication works in this project"

Claude spawns Explore agent
Agent searches for auth files, reads them
Agent returns summary of auth architecture
Claude presents findings in conversation

Why agent: Extensive file searching would bloat the main conversation. Agent does the work and returns a digest.

Skill

Git Commit Workflow

User types "/commit" after making changes

Skill loads commit workflow instructions
Claude checks git status, stages files
Claude writes commit message following conventions
Claude commits and optionally pushes

Why skill: Consistent process every time. Follows team conventions. Runs in context so Claude knows what was changed.

MCP

GitHub Integration

"Create a GitHub issue for the bug we just discussed"

Claude calls mcp__github__create_issue
MCP server authenticates with GitHub API
Issue is created with title, body, labels
MCP returns issue URL to Claude

Why MCP: Claude can't access GitHub API directly. MCP provides the bridge with proper authentication.

Combined

Blog Post Creation

User types "/blog-writer" to create an SEO article

Skill defines the overall workflow
MCP (SEO Research) gets keyword data
Agent researches competitor articles
Skill guides the writing structure

Why combined: Complex workflows often use all three. Skill orchestrates, MCP provides data, agents do research.

Frequently Asked Questions