Claude Skills · MCP · Developer Guide
How to Combine Claude Skills with MCP (Model Context Protocol): A Developer's Guide
One teaches Claude a method. The other connects it to tools and data. Here's how they actually fit together.
If you've spent any time building on Claude lately, you've hit two features that sound like they overlap: Claude Skills (officially, Agent Skills) and the Model Context Protocol (MCP). Both "extend Claude." Both get bundled into agent setups. So a fair question — and one we get a lot — is: do I use Skills or MCP? Are they competitors?
They're not. They're two different layers of the same stack, and the interesting work happens when you combine them. This guide explains what each one actually is, how they fit together, and the practical pattern for building an agent that uses both — with the real-world constraints that trip people up.
The one-sentence mental model
Skills teach Claude how to do something. MCP gives Claude the tools and data to do it. Claude is the orchestrator that combines the two.
Hold onto that and everything below falls into place.
What Claude Skills actually are
A Claude Skill is a folder of procedural knowledge that Claude loads on demand. At minimum it's a SKILL.md file with YAML frontmatter (a name and a description) plus instructions; it can also bundle reference files, templates and scripts.
The clever part is progressive disclosure — Skills load in stages so they don't burn your context window:
- Level 1 — metadata (always loaded): just the name and description, roughly a hundred tokens. This is what Claude matches your request against to decide whether the Skill is relevant.
- Level 2 — instructions (loaded on trigger): the body of SKILL.md, read only when the Skill fires.
- Level 3 — resources and code (loaded as needed): extra files or scripts, pulled in only when the task calls for them. Scripts run and return their output without their source code ever entering context.
Two consequences matter for architecture. First, the description is the trigger — it must say what the Skill does and when to use it, or Claude won't invoke it. Second, you can install a lot of Skills cheaply, because idle Skills cost only their metadata.
Skills are model-invoked: Claude decides when to use one based on the description, not you calling it explicitly. Think of a Skill as an onboarding guide you'd hand a new team member — the method, the standards, the checklist — not a live API.
What MCP actually is
The Model Context Protocol is an open standard for connecting an AI model to the outside world. You run (or connect to) an MCP server, and it exposes a set of tools (actions Claude can call), resources (data Claude can read) and prompts — over a common protocol, so any MCP-compatible client can use them.
Where a Skill is static know-how, MCP is a live wire: a GitHub server that can open issues, a database server that can run queries, a Slack server that can post messages, a search server that can fetch today's data. MCP is how Claude reaches systems and acts on them.
Claude Skills vs MCP, side by side
| Claude Skills | MCP | |
|---|---|---|
| Job | Procedural knowledge — the method | Connectivity — tools & data |
| Answers | “How should I do this?” | “What can I reach and act on?” |
| Form | SKILL.md + resources on a filesystem | A server exposing tools/resources |
| Invocation | Model-invoked by description match | Called as tools during the task |
| State | Static instructions, loaded on demand | Live connection to external systems |
| Analogy | The playbook | The hands and the phone line |
They're not alternatives. A playbook with no tools can't act; tools with no playbook have no judgment about when or how to use them. Put them together and you get a specialist that both knows the method and can execute it.
How they work together
Because Claude is the orchestrator, the integration point is Claude itself. A Skill's instructions can name the MCP tools Claude should use, and at which step. The Skill supplies the workflow and the judgment; MCP supplies the live capability the workflow calls out to.
Concretely, inside a SKILL.md you can write instructions like:
---
name: release-notes-writer
description: Turn a repo's merged pull requests into customer-facing release notes. Use when someone asks for release notes, a changelog write-up, or "what shipped."
---
# Release Notes Writer
## Method
1. Pull the merged PRs since the last release. Use the connected GitHub MCP
tools to list them — do not ask the user to paste them.
2. Group changes by user impact (New / Improved / Fixed), not by commit.
3. Rewrite each in plain, user-facing language. No internal jargon,
no invented changes — only what the PRs actually contain.
4. Draft in the house voice (see references/voice.md).Here the Skill is the method — how to group, how to write, what never to do — and the GitHub MCP server is what makes step 1 real. Claude reads the Skill, sees it should fetch live PRs, and calls the MCP tool to get them. Neither could do the job alone: the Skill has no data, the MCP server has no editorial standard.
That's the whole pattern. Keep the "how" in the Skill and the "what it connects to" in MCP. It's a clean separation of concerns: your method is portable and reviewable, your connectivity is swappable.
Where this works — and the constraint that catches people out
Skills and MCP are both available across Claude's surfaces, but the runtime differs, and one difference matters a lot for combining them.
| Surface | Skills | MCP | Notes for combining |
|---|---|---|---|
| Claude Code | Filesystem Skills in ~/.claude/skills/ or .claude/skills/ | Configure MCP servers directly | Full network access — the most flexible place to build and test both together |
| Claude API | Custom Skills via the code execution tool (skill_id in the container) | The MCP connector at the request level | See the constraint below |
| claude.ai | Upload custom Skills as a zip in Settings → Features (paid plans, code execution on) | Connectors | Great for power users; each user manages their own |
The constraint: on the Claude API, Skills run in a sandboxed container with no network access. So a Skill's own bundled script cannot call out to the internet or an MCP server. That sounds like it breaks the integration — but it doesn't, because the two connect at the orchestration level, not inside the sandbox. Claude (the model) holds the Skill's instructions and has the MCP tools available via the connector; Claude calls the MCP tools, then works with the results using the Skill's method. In other words: the Skill's code is sandboxed, but Claude the agent is not — and Claude is the one wiring them together.
In Claude Code, Skills have full network access, so you have more freedom (a Skill's script could even talk to a service directly) — but the cleaner design is still to let MCP own the connections and keep the Skill focused on method.
At a high level, an API request that uses both looks like this (conceptual — check the current docs for exact parameters):
messages: [ ...your request... ]
tools: [ code execution tool → references your skill_id ]
mcp_servers: [ your remote MCP server(s) via the MCP connector ]Claude then has the method (Skill) and the tools (MCP) in the same turn, and orchestrates across them.
A build checklist
- 01
Split the problem. Decide what's method (goes in the Skill) and what's connection (goes to an MCP server). If you're hardcoding live data into a prompt, that's a sign it belongs in MCP.
- 02
Write a trigger-worthy description. The Skill only fires if its description clearly states what it does and when to use it. This is the highest-leverage line in the file.
- 03
Reference MCP tools by stable name in the Skill's instructions, at the step where they're needed. Tell Claude to use the tool rather than ask the user.
- 04
Keep secrets in the MCP server, never in the Skill. Credentials live with the connection, not the method.
- 05
Lean on progressive disclosure. Keep SKILL.md tight; push deep reference material into separate files that load only when required.
- 06
Test in Claude Code first (full network, fast iteration), then move to the API or claude.ai with the sandbox constraint in mind.
Security — trust both layers
Skills and MCP each widen what Claude can do, so each is a trust decision.
Skills can direct Claude to run code and call tools. Only install Skills you wrote or obtained from a source you trust, and audit third-party ones — every bundled file, especially anything that fetches from external URLs. A malicious Skill can misuse whatever tools Claude has, including your MCP servers.
MCP servers can read data and take real actions. Connect only servers you trust, scope their permissions tightly, and remember that a compromised server is a compromised set of hands.
The rule of thumb: treat adding a Skill or an MCP server like installing software with access to your systems — because that's exactly what it is.
The takeaway
Stop thinking "Skills or MCP." Think method plus connectivity. Skills make Claude a specialist that knows how; MCP gives that specialist live tools and data; Claude orchestrates the two. Design with that separation and you get agents that are both knowledgeable and capable — and far easier to maintain, because the "how" and the "what it connects to" evolve independently.
New to the method layer? Start with our guide to the best Claude Skills for designers, builders and founders.
FAQ
Want a head start on the "method" layer?
ai-skills.space is a set of 45 designer-built Claude Skills — each one written to encode real expertise and to compose cleanly with the tools you connect via MCP. Start free with .