MCPs vs Agent Skills: Understanding the Difference

“Should I build a skill or an MCP for this?”

I’ve been asked this question a lot since Anthropic announced Agent Skills back in October 2025. And honestly, the confusion makes sense. Both extend Claude Code’s capabilities. Both can connect to external services. Skills can even run scripts, which sounds a lot like what MCPs do.

But once you understand the mental model, the distinction becomes obvious. Let’s break it down.

What MCPs Actually Do

Model Context Protocol is an open standard for connecting AI applications to external systems. It’s the plumbing that connects Claude to the outside world by exposing tools that can read data, execute actions, and interact with external services.

For example, you can add the Linear MCP and give Claude the ability to read and create issues, or add the Sentry MCP so it can query errors. These are capabilities Claude didn’t have before. MCPs extend what Claude can do.

There’s something you need to consider when adding MCPs though: every MCP you add to Claude Code takes up space in your context window just by being available. Not just when it’s used, but constantly. If you’ve read my post on Understanding Claude Code’s Context Window, you know this matters a lot.

The Anatomy of an MCP Tool

Every MCP tool exposes information to the LLM so it knows when and how to use it. Here’s what Claude sees when the Linear MCP is configured:

│ get_issue (linear-server) [read-only]                                        │
│ Tool name: get_issue                                                         │
│ Full name: mcp__linear-server__get_issue                                     │
│                                                                              │
│ Description:                                                                 │
│ Retrieve detailed information about an issue by ID, including attachments   │
│ and git branch name                                                          │
│                                                                              │
│ Parameters:                                                                  │
│   • id (required): string - The issue ID                                     │
│   • includeRelations: boolean - Whether to include blocking, related,        │
│     and duplicate relations in the response                                  │

The description tells the LLM when and why to use the tool. Some descriptions are verbose, which means they consume more tokens on every single message. The parameter schema is typically JSON that defines the tool’s inputs. And the tool name is what the LLM calls to invoke it.

Here’s why this matters: in Build Efficient MCP Servers: Three Design Principles, I showed how a Claude Code session can have 24% or more of the context window consumed by MCP tool definitions before you’ve even started a conversation. Add a few feature-rich MCP servers and you’ve got precious little space left for actual work.

This used to create a hard practical limit. Too many MCPs and the model would get confused, more likely to pick wrong actions. Anthropic addressed this in January 2026 with MCP Tool Search, which dynamically loads MCP tools on-demand when they would consume more than 10% of context. This helps, but the underlying tension remains: MCP tool definitions compete for context space, which is why skills use a different approach entirely.

The Key Characteristics

MCPs are:

Single-purpose tools - Each tool does one specific thing
Autonomous - Claude can call them directly without any instruction from you
Always loaded - Tool descriptions are in context on every message (or dynamically loaded via MCP Tool Search)
Bidirectional - Can read from and write to external systems

When you ask Claude “What’s the status of issue TRA-123?”, it can autonomously decide to call the Linear MCP to fetch that information. No skill needed, no special invocation. The capability is just there.

What Agent Skills Actually Do

Since the original announcement of Agent Skills, Anthropic has released Agent Skills as an open standard, and other tools like GitHub Copilot and Cursor now support them as well.

At first glance, skills look simple. They’re essentially a folder with some markdown files and optionally some scripts:

my-skill/
├── SKILL.md           # Main instructions (required)
├── reference.md       # Detailed docs (loaded as needed)
├── examples.md        # Usage examples (loaded as needed)
└── scripts/
    └── helper.py      # Executable scripts (run, not loaded)

Skills typically live in .claude/skills/ within your project or ~/.claude/skills/ for global availability.

Skills can execute code. But that’s not what makes them special. What makes them special is orchestration. They compose multiple capabilities into a defined workflow.

A tool lets Claude query your database. A skill teaches Claude your company’s specific data model, your naming conventions, your rollback procedures. MCPs are verbs. Skills are playbooks.

The Four Flavors of Skills

In my experience, skills tend to fall into four categories:

Specialized workflows are multi-step procedures for specific domains. Things like a TDD workflow, a PR review process, or a deployment checklist. These are the skills I use most often.

Tool integrations are instructions for working with specific file formats or APIs. Maybe you need Claude to know how to process DOCX files, manipulate PDFs, or query BigQuery a specific way.

Domain expertise captures company-specific knowledge. Your data model, your naming conventions, your rollback procedures. The stuff that lives in tribal knowledge.

Knowledge retrieval bundles reference documentation that Claude can access on demand. API specs, style guides, architectural decision records. Rather than stuffing everything into CLAUDE.md, you package it into a skill that loads only when relevant.

Why Skills Exist: Progressive Disclosure

The key design principle behind skills is progressive disclosure. Unlike MCPs where tool definitions are always present, skills only load their full content when invoked.

The most basic skill is a folder with a SKILL.md file. This file contains YAML frontmatter with metadata (name and description) followed by the actual instructions. For any given skill, only the metadata is persistently available. The description tells the LLM when to invoke the skill, so you need to capture the right semantics for the agent to pick it up appropriately.

Once the skill is invoked, the LLM loads the rest of the SKILL.md file into context and follows its instructions. You can also break skills into separate resource files for different scenarios or workflows. This lets you keep context lean by loading only what’s needed for the current task.

What This Looks Like in Practice

In How I Use Claude Code: My Complete Development Workflow, I described my linear-implement skill that takes a Linear issue and implements a solution following TDD. Here’s how the pieces fit together:

┌──────────────────────────────────────────────────────────────┐
│                        SKILL                                 │
│                 (orchestration layer)                        │
│                                                              │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │ Bundled: scripts/ │ references/ │ assets/               │ │
│  └─────────────────────────────────────────────────────────┘ │
│                                                              │
│    ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐       │
│    │  MCP    │  │  Bash   │  │  File   │  │  Web    │       │
│    │ (Linear)│  │ (tests) │  │ (write) │  │ (fetch) │       │
│    └─────────┘  └─────────┘  └─────────┘  └─────────┘       │
└──────────────────────────────────────────────────────────────┘

The skill sits on top and orchestrates everything. It calls the Linear MCP to fetch issue details. It runs bash commands to execute tests. It writes code files following TDD. It creates PRs via the GitHub CLI.

Without a skill, Claude can do all these things individually. But you have to orchestrate each step manually. Every session, you re-explain the workflow. With a skill, one command triggers the entire workflow. Consistent process every time. Your expertise encoded into Claude’s behavior.

The CLAUDE.md vs Skills Question

A common point of confusion: when should something go in CLAUDE.md versus a skill?

Here’s how I think about it:

CLAUDE.md is for declarative knowledge. What and why. Background context that Claude should just know. “This is Rails 7 with RSpec.” “We use JSON:API format.” “Run tests with bin/rspec.”

Skills are for procedural knowledge. How. Multi-step workflows with defined steps. “When implementing a feature, follow this TDD workflow…” “To deploy, run these 5 steps…”

The analogy that works for me: CLAUDE.md is like an employee handbook (background context). Skills are like training modules (specific procedures).

If you’re copy-pasting the same multi-step instructions into chat repeatedly, that’s a skill waiting to be created. If it’s background context Claude should just know, it belongs in CLAUDE.md.

There’s a practical difference too. CLAUDE.md is always loaded in context, so it should stay lean. Skills use progressive disclosure, so they can be extensive without penalty when not in use.

Putting It Together

Now that we’ve covered what each one does separately, let me show you what it looks like when they work together.

┌─────────────────────────────────────────────────────────────────┐
│  Prompt: "Help me implement Linear TRA-123"                     │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  SKILL activates (context match)                                │
│  → Loads bundled resources, defines workflow                    │
└─────────────────────────────────────────────────────────────────┘
                              │
                    ┌─────────┴─────────┐
                    ▼                   ▼
              ┌──────────┐       ┌──────────┐
              │   MCP    │       │  Native  │
              │ (Linear) │       │  Tools   │
              │          │       │          │
              │ Fetches  │       │ Bash,    │
              │ issue    │       │ File ops │
              │ details  │       │ for TDD  │
              └──────────┘       └──────────┘
                    │                   │
                    └─────────┬─────────┘
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  Result: Feature implemented following TDD workflow             │
└─────────────────────────────────────────────────────────────────┘

The MCP gives access to Linear (the capability). The skill orchestrates the workflow (the recipe). Each has its role.

The Two Questions

You might be thinking: since skills can have scripts, can’t they also connect to external services? Yes, they can. Skills can include scripts that hit APIs, run curl commands, whatever you need. The difference is that these scripts only run in the context of the skill itself. If you need something more general purpose that Claude can call from any context, you want an MCP instead.

When Claude needs to check Linear issues, it can do that anytime, in any context, without any special setup. That’s an MCP’s job. But when you say “implement this feature,” you want a specific sequence of steps followed in a specific order. That’s a skill’s job.

When I need to decide which to use, I ask myself two questions:

Question 1: Should Claude be able to call this capability anytime, across any context?

If yes, you need an MCP.

If only during a specific workflow, a skill with scripts is fine.

Checking Linear issues? That’s something Claude might need to do in many different contexts. MCP makes sense. Deploying to staging? That’s a specific workflow with defined steps. Skill makes sense.

Question 2: Is this a repeatable workflow with defined steps?

If yes, build a skill (with or without MCPs).

If no, you might not need either. Just ask Claude directly.

If you find yourself explaining the same multi-step process to Claude repeatedly, that’s your signal. That’s when you build a skill.

Common Patterns

Here’s how this plays out in practice:

MCP alone: “Check my Linear issues.” Claude decides to call it autonomously.

Skill using MCP: “Implement TRA-123.” The skill orchestrates the workflow, calling the Linear MCP as one step among many.

Skill with scripts: “Deploy to staging.” The workflow runs deploy scripts that hit external services.

Skill without external calls: “Follow our TDD process.” Pure internal workflow, no external systems needed.

The Mental Model

That’s the mental model. MCPs give Claude capabilities. Skills give Claude orchestration. Or to put it another way:

MCPs = The tools in the toolbox Skills = The recipes that coordinate those tools

MCPs are the plumbing connecting Claude to the outside world. Skills are the playbook of procedural knowledge.

MCPs answer “what can Claude access?” Skills answer “how should Claude approach this task?”

Getting Started

If you’re just getting started, here’s my recommendation:

Start with MCPs. Find one that connects to a tool you already use. Linear, Sentry, your database, whatever. Install it and start calling it. Get a feel for how Claude uses capabilities autonomously.

Watch for patterns. When you notice you’re asking Claude the same multi-step sequence over and over, that’s your signal. That’s when you build a skill.

Keep it simple. Your first skill doesn’t need to be complex. Start with a workflow you repeat weekly, document the steps, and let Claude follow them consistently.

If you want to build your own skill from scratch, check out my video Claude Code Tutorial: Build your first skill in 10 minutes where I walk through creating a TDD workflow skill step by step.

For more examples, sign up for my newsletter. You’ll get access to my claude-code-workflows repo on GitHub, which includes several skills I use daily, including the linear-implement workflow that ties everything together.