Skills vs MCP Servers: Which Your Agent Needs

A skill teaches your agent how to do a job: a folder with a SKILL.md file of instructions it follows. An MCP server gives your agent something to call: a running program that exposes tools, data or prompts through the Model Context Protocol. Install a skill when the agent lacks your procedure. Install a server when the agent lacks access to a system. Most useful setups have both, with a skill saying when and how to use the tools a server provides. Checked 31 October 2026.

The short version

What each one is

A skill

Claude Code's docs: "Skills extend what Claude can do. Create a SKILL.md file with instructions, and Claude adds it to its toolkit." Claude uses a skill when it is relevant, or you invoke it directly with /skill-name. The file has two parts: YAML frontmatter that tells Claude when to use the skill, and markdown content with the instructions it follows. The description field is what lets Claude decide to load a skill automatically.

Skills live in folders, which decides who gets them:

Custom commands have been merged into skills: a file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy. A skill folder can also hold supporting files.

Claude Code's skills follow the Agent Skills open standard, which works across multiple AI tools, and Claude Code adds extensions on top: invocation control, subagent execution and dynamic context injection.

An MCP server

The MCP site: "an open-source standard for connecting AI applications to external systems." A host application keeps one client per server over JSON-RPC 2.0. Servers expose tools, resources and prompts. Local servers use the stdio transport; remote ones use Streamable HTTP. In Claude Code you add one with claude mcp add, for example:

claude mcp add --transport http notion https://mcp.notion.com/mcp

A server is a program somebody runs and maintains, locally or remotely. It holds credentials and talks to the service.

Side-by-side facts

What each is good at

Skills: procedure and judgment

A skill is the right tool when the agent can already do the pieces but does not know your way of doing them. The docs' own example is a skill whose description reads: "Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff." The body then says how.

Good skill topics:

• A release checklist with the exact commands for your repo.
• A review rubric for your codebase.
• How to write a migration, a test, a changelog entry.
• Recorded setup recipes. Claude Code's /verify and run-skill generator write what worked into a project skill, so other agents in the repo follow the same steps.

Skills are plain text, so you can read and review them in a pull request before they run.

MCP servers: reach and action

A server is the right tool when the agent needs capabilities that text instructions cannot give: reading a ticket, querying a database, posting to a channel, driving a browser. These need an authenticated connection to something outside the model.

Good server topics:

• Issue trackers, chat, calendars and docs.
• Databases and observability systems.
• Browsers and design tools.
• Your own internal APIs.

Our MCP server directory lists many.

Costs in context

Neither is free, and Claude Code's docs show where.

Skills. Only the short description needs to be visible for Claude to decide; the body loads when the skill is used. The /usage screen attributes usage to skills, subagents, plugins and individual MCP servers, with recommendations for trimming. The context-audit tooling compares unused skills, MCP servers and plugins with their context cost.

MCP servers. Tool definitions are deferred by default, so only tool names and server instructions enter context until Claude uses a specific tool. The cost docs still advise disabling unused servers with /mcp and preferring CLI tools such as gh, aws, gcloud and sentry-cli, which add no per-tool listing.

A practical rule: keep the active set small. Every skill description and every server's tool list competes for the same context window as your code.

Safety

Skills are instructions, so the danger is in what they tell the agent to do. A skill that says "run this script" or "ignore confirmation prompts" is a risk. Read third-party skills before installing, and prefer ones that keep supporting scripts short and visible. Permission rules still apply to what the agent does.

MCP servers are code with credentials. The spec says tools represent arbitrary code execution, that tool descriptions should be considered untrusted unless they come from a trusted server, and that hosts must obtain explicit user consent before invoking any tool. Claude Code's docs tell you to verify you trust each server and warn that servers fetching external content can expose you to prompt injection. A cloned repository cannot approve its own project MCP servers until you trust the workspace.

If the choice is between a skill and a server for the same job, the skill is usually the smaller risk, because it adds no new process or credential. It is only an option when the agent can already reach the system by other means, such as a CLI.

Writing a good skill

The smallest useful skill is one directory and one file.

.claude/skills/changelog/SKILL.md

---
description: Drafts a changelog entry from merged pull requests. Use when the user asks for release notes or a changelog.
---
List merged PRs since the last tag with `gh pr list --state merged`.
Group them as New, Improve, Fix. One sentence each. No ticket ids.

Three habits make skills work. Put the trigger in the description, in plain words, since that is what the agent matches against ("Use when the user asks..."). Keep the body short and concrete, with the exact commands. And test it two ways, as the docs suggest: ask something that matches the description so Claude invokes it, and call it directly with /changelog.

Notice what this skill does not do. It does not connect to GitHub. It uses the gh command the agent can already run, and it tells the agent how to format the result. If gh were not installed, the skill would fail, and no amount of better writing would fix that. That is the line between the two: a skill can only direct access that already exists.

Writing a good MCP integration

If you are adding a server, start from a maintained one. Check the server's tool list before you connect it and ask what it can change. Prefer read-only modes where they exist. Pass the narrowest token that works. Add it at the narrowest scope, for one project and not globally, if only one project needs it. And keep a note of why it is there, so you can remove it when the project ends.

Then write the skill that sits on top, using the real tool names you saw. A skill written before the server works tends to name tools that do not exist.

Using them together

The pattern that works best splits the layers.

1. An MCP server for your tracker gives the agent get_issue and update_issue.
2. A skill called triage says: read the issue, check for a reproduction, label it with these labels, and never close an issue without a comment.
3. The agent uses the skill for the procedure and the server's tools for the actions.

Because skills can be committed in the repo, the whole team gets the same procedure. Servers are configured per user or per project, so each person authenticates for themselves.

The MCP spec itself has a name for the overlap. Its list of notable extensions includes "Skills over MCP: rich, structured instructions for agent workflows, discovered and consumed through MCP." So a server can ship the instructions with the tools. We did not test that extension, and client support will vary.

Subagents can take both. A subagent's definition accepts fields for skills and mcpServers, which lets you hand a worker agent exactly the procedures and tools it needs. See Subagents vs skills.

Choosing

Choose a skill when:

• The agent already has the access it needs.
• You want to encode how your team does something.
• You want it reviewed in a pull request and shared by Git.
• You want zero new processes or credentials.

Choose an MCP server when:

• The agent needs a connection it does not have.
• A maintained server already exists for the service.
• Several AI apps should share the same connection.

Choose both when:

• The job involves a service and a procedure. Write the skill after the server works, using the real tool names.

Choose neither when:

• A few lines in CLAUDE.md cover it, or a CLI does the job.

A short checklist

• Is the gap knowledge (skill) or access (server)?
• Can a CLI already do the job?
• Have you read the skill's instructions and any scripts?
• Do you trust the server's author and its handling of credentials?
• Is the description specific enough that the agent picks the skill at the right time?
• Did you check /usage after a week and remove what is unused?

One job, built three ways

Take a recurring job: every Friday, turn merged pull requests into release notes in your house style.

Here the skill-only route is the right one, because the agent already has access through gh and what it lacks is your style. The server earns its place only when the agent cannot reach the service any other way, or when several AI apps need the same connection. That is the test the page keeps returning to: is the gap knowledge or access?

Reviewing a skill in a pull request

A skill is text, so the review is a reading exercise. Ask these questions of every skill that lands in your repository.

1. Is the description specific? It should say what the skill does and when to use it, in words a person would actually type.
2. Does it tell the agent to run commands? Read each one. A command you would not run by hand should not be in the skill.
3. Does it weaken a safeguard? Phrases such as "skip confirmation" or "do not ask" deserve a hard look.
4. Does it name tools or servers that exist? A skill that mentions a tool you have not installed will fail quietly.
5. Is it short? The body loads when the skill is used, so every extra paragraph costs context each time.
6. Does it overlap with another skill? Two skills with similar descriptions make the agent choose between them.

When the agent ignores your skill

• The description is vague. Rewrite it around the trigger phrase a user would say.
• Two skills compete. Merge them or sharpen each description until the boundary is clear.
• The skill is in the wrong folder. Check whether it sits in your user skills, the repository's .claude/skills folder or a plugin, since each reaches a different audience.
• The skill asks for something the agent cannot do. It may need a tool or server you have not connected.
• You expected a slash command. Skills can also be invoked by name, which is the quickest way to test one.

Questions people ask

Can a skill replace an MCP server? Only if the agent already has another way to reach the service, such as a CLI. A skill adds know-how and cannot add access.

Do skills work outside Claude Code? Claude Code's skills follow the Agent Skills open standard, which works across multiple AI tools, though Claude Code adds its own extensions on top.

Which should a team start with? A skill, since it is reviewed in a pull request, shared through Git and adds no process or credential.

Our take

From the documents, skills and MCP servers are complements. A skill is cheap to write, easy to review and shareable by Git, so start there for anything procedural. An MCP server earns its place when the agent truly cannot reach a system any other way, and then the cost is a process, a credential and some context.

The mistake we would avoid is installing a server to solve a knowledge problem, or writing a skill that pretends to give access. If the agent keeps doing a job the wrong way, write a skill. If it cannot do the job at all, look for a server.

We did not run controlled tests of either for this page. The specifics come from the Claude Code docs and the MCP specification, read on 31 October 2026.

Related

• Skills directory
• MCP servers
• Subagents vs skills
• MCP vs API
• MCP vs RAG
• How we compare