Skills vs MCP Servers: Understanding Claude Code's Two Extension Systems

Two Systems, One Agent

If you've spent more than a few hours customizing Claude Code, you've probably encountered both Skills and MCP servers. They both extend what the agent can do. They both involve configuration files. And at first glance, they seem to solve the same problem.

They don't. Understanding the difference — and more importantly, the interaction between them — is the key to building Claude Code setups that actually scale.

What Are Skills?

Skills are prompt injections that activate at tool-call time. When you define a skill, you're writing a block of instructions that gets loaded into the agent's context window at the moment it's relevant — not before, not after.

Think of them as "expertise on demand." A skill doesn't give Claude Code access to a new API or database. It gives Claude Code a specific way of thinking about a problem.

A deploy skill might say: "Before deploying, always check for pending migrations, verify the changelog is updated, and confirm the branch is rebased on main." A code review skill might encode your team's standards: "Flag any function longer than 40 lines, require error boundaries around async operations, enforce the repository's naming conventions."

Skills are defined as Markdown files in .claude/commands/ and are invoked as slash commands. They're version-controlled, shareable, and composable.

# .claude/commands/review.md
Review the staged changes with these criteria:
- No functions exceeding 40 lines
- All async operations wrapped in error boundaries
- Naming follows kebab-case for files, camelCase for functions
- No direct DOM manipulation in React components
- Flag any new dependencies not in the approved list

The critical insight: skills don't add capabilities. They add judgment. Claude Code could already read your staged changes. The skill tells it how to evaluate them.

What Are MCP Servers?

Model Context Protocol servers are the opposite. They add capabilities that Claude Code doesn't have natively.

MCP is an open protocol that lets AI agents connect to external tools, APIs, and data sources through a standardized interface. An MCP server exposes a set of tools — each with a name, description, and input schema — that the agent can call like any other tool.

A Postgres MCP server gives Claude Code the ability to query your database. A Figma MCP server lets it inspect design files. A Slack MCP server enables it to read channels and send messages. A browser MCP server gives it a real browser to navigate and inspect.

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

MCP servers run as separate processes. They have their own dependencies, their own authentication, their own failure modes. The agent communicates with them over stdin/stdout using a JSON-RPC protocol.

The critical insight: MCP servers don't change how Claude Code thinks. They change what it can reach.

When They Overlap

Here's where it gets interesting. Some problems can be solved by either system, and picking the wrong one creates unnecessary complexity.

Example: enforcing a style guide. You could build an MCP server that wraps ESLint, exposing a lint tool the agent can call. Or you could write a skill that tells the agent your style rules directly and lets it apply them using its native code understanding.

The skill is almost always better here. Claude Code already understands code structure. Encoding rules as natural language in a skill is faster, more flexible, and doesn't require maintaining a separate process.

Example: querying a database. You need an MCP server. No amount of prompt engineering gives Claude Code the ability to open a TCP connection to PostgreSQL. This is a capability gap, not a judgment gap.

The rule of thumb: if the problem is "Claude Code doesn't know how to approach this," use a skill. If the problem is "Claude Code can't access this," use an MCP server.

When They Don't Overlap

Some use cases are exclusively one or the other.

Skills only:

• Encoding team conventions and coding standards
• Defining multi-step workflows (deploy checklists, PR review processes)
• Setting decision-making criteria ("prefer composition over inheritance")
• Providing domain context ("this is a healthcare app, all dates must be UTC")

MCP only:

• Connecting to databases, APIs, and external services
• Interacting with design tools (Figma, Excalidraw)
• Sending notifications (Slack, Discord, email)
• Browsing and scraping the web
• Accessing proprietary data sources

The distinction is architectural. Skills operate inside the context window. MCP servers operate outside it, bridging the gap between the language model and the external world.

Practical Examples

A deploy workflow using both:

The skill defines the process:

# .claude/commands/deploy.md
Before deploying:
1. Query the database for pending migrations (use the postgres MCP tool)
2. Check the GitHub PR for approvals (use the github MCP tool)
3. Verify no critical Sentry errors in the last hour (use the sentry MCP tool)
4. If all checks pass, run the deploy script
5. Post a summary to the #deploys Slack channel (use the slack MCP tool)

The MCP servers provide the capabilities: database access, GitHub API, Sentry API, Slack API. The skill provides the orchestration logic — the order of operations, the decision criteria, the conditional flow.

Neither system alone could do this. The skill without MCP has no way to check the database or post to Slack. The MCP servers without the skill have no understanding of when to check what or in what order.

A code review pipeline:

The skill encodes your review standards. An MCP server connects to your test runner. Another connects to your security scanner. The skill says "run the security scan, check the test results, and evaluate against our standards." The MCP servers execute. The skill decides.

The Composability Story

The most effective Claude Code setups treat skills and MCP servers as complementary layers:

• MCP servers form the capability layer — what the agent can interact with
• Skills form the intelligence layer — how the agent makes decisions
• Hooks form the automation layer — what happens before and after tool calls

A well-configured workspace might have 4-6 MCP servers providing access to the tools your team uses daily, and 8-12 skills encoding your team's workflows, standards, and domain knowledge.

The MCP servers rarely change. You set up Postgres, GitHub, Slack, and your monitoring tool once. The skills evolve constantly — every time your team refines a process, the skill gets updated. Every post-mortem produces a new decision criterion. Every new team member's onboarding questions reveal implicit knowledge that should be explicit.

Common Mistakes

Over-engineering with MCP when a skill would suffice. If you're building an MCP server just to wrap a CLI tool that Claude Code could already run via bash, you've added complexity for no gain. A skill saying "use the bash tool to run npm test -- --coverage" is simpler and more maintainable.

Under-specifying skills. A skill that says "review the code carefully" adds nothing. Skills need to encode specific, actionable criteria. The value is in the specifics your team has learned through experience.

Ignoring the security boundary. MCP servers have real access to real systems. A misconfigured database MCP server with write access is a production incident waiting to happen. Skills, by contrast, can only influence what the agent does with the tools it already has — they don't expand the blast radius.

Not versioning skills. Skills in .claude/commands/ should be in version control. They're institutional knowledge in executable form. Treat them like you'd treat runbooks or playbooks — reviewed, iterated, and shared.

The Best Setups Use Both

The teams getting the most out of Claude Code aren't choosing between skills and MCP servers. They're using MCP servers to connect the agent to their infrastructure and skills to encode the wisdom of how that infrastructure should be used.

MCP gives the agent hands. Skills give it judgment.

If you're just getting started: begin with 2-3 skills encoding your most common workflows. Add MCP servers as you hit real capability gaps — when the agent needs to access something it can't reach through its native tools. Grow both layers over time, and you'll end up with an agent that doesn't just write code, but operates with the accumulated knowledge of your team.

That's the difference between an AI assistant and an AI teammate.

---

For more on getting the most out of Claude Code, see our guide to 10 hidden features most developers don't know exist. And if you're ready to move from single-agent setups to coordinated multi-agent workflows, explore how Kyros orchestrates it — see features or view pricing.