MCP vs skill.md — what’s the difference and why you need both

AI agents don’t browse your docs the way humans do. They execute workflows, call APIs, and take actions inside your product, often without a human in the loop. And while things are still moving fast, two emerging standards now define how agents interact with your system: Model Context Protocol (MCP) and skill.md.

Teams often treat these as competing options. They aren’t. MCP and skill.md solve different problems at different layers of the stack. MCP is the connection layer, handling how agents retrieve data from your system. skill.md is the instruction layer, defining what agents should do with your product once they’re connected.

This article breaks down what each standard does, where they diverge, and why shipping both gives your product the best coverage for the AI agent ecosystem.

Quick overview

What each standard does

MCP (Model Context Protocol) is an open standard for connecting AI agents to external data sources and tools. It standardizes the transport, so any compatible agent can plug into your system without a custom integration.

skill.md is a structured Markdown file that tells agents how to behave when using your product. It defines workflows, boundaries, decision rules, and guardrails in a format any LLM can read.

Here’s a quick shorthand to make it easier to remember the difference: MCP = transport, while skill.md = behavior.

Snapshot comparison

What is MCP?

MCP (Model Context Protocol) is an open standard that gives AI agents a single, consistent way to connect to external data sources and tools. It replaces the custom integrations that teams previously had to build one by one for every application-to-system pair.

You can think of it as a universal port, like USB-C: with one MCP server for your data source, any MCP-compatible agent can plug in.

MCP servers expose three capability types:

• Resources – data the AI can read, like documents or API responses

• Tools – functions the agent can execute, like searching a codebase or fetching metrics

• Prompts – reusable templates that guide how the agent approaches specific tasks

These three primitives cover most of what an agent needs in order to retrieve and act on external data.

Adoption has moved quickly since the protocol launched in November 2024. Claude, ChatGPT, Cursor, and VS Code (in agent mode) all support MCP. In fact, according to the 2025 AI Agent Index, 20 of 30 leading AI agents now support the protocol for tool integration, meaning two-thirds of the field converged on MCP within roughly one year of launch.

For a deeper look at how MCP works and what it means for documentation, see our full MCP explainer.

What is skill.md?

A skill.md file is a structured Markdown document that gives AI agents behavioral guidance for your product, solving the problem of agents that can connect to your system but don’t know how to act on it correctly.

Without that guidance, agents guess at task ordering, permissions, and constraints, and those guesses often produce unreliable results. If a user asks an agent to “set up a new workspace and invite the team,” the agent needs to know which operations to run, in what order, and under what conditions.

A well-written skill.md covers

• Boundaries – when and where the skill applies

• Workflows – step-by-step task instructions with explicit sequencing),

• Decision rules – ’if/then’ guidance for choosing between paths

• Guardrails – unsupported actions, known failure modes, environment constraints

The file is plain Markdown with no special tooling, no SDK, and no framework dependency. It lives in your documentation site, version-controlled and updated alongside product releases. And it works with any agent capable of reading context, whether that agent connects via MCP, browses your docs, or ingests files during a RAG pipeline.

To see a real-world example, GitBook publishes its own skill.md inside its documentation, serving as both a production implementation and a reference example for teams building their own docs using AI tools.

For a full breakdown of what to include and how to structure the file, see the complete skill.md guide.

Key differences: MCP vs skill.md

The clearest distinction

MCP answers one question: “How does the agent get data from my system?” skill.md answers a different one: “What should the agent do with my product once it’s connected?”

MCP is infrastructure, while skill.md is knowledge.

For a more hands-on analogy, you can think of MCP servers as the wrench, drill, and saw in your toolbox. Skills are the instructions on how to use them. A toolbox without instructions or context would leave someone guessing which tool to use. Instructions without tools leave you reading about a drill you can’t operate.

Why you need both

MCP without skill.md

An MCP server gives agents access to your data, but no guidance on how to act on it. The agent can retrieve the right documentation page, but might execute the wrong workflow because it has no behavioral context. That’s great for users who just want to find information from your docs, but not ideal if you want an agent to take an action in your product.

Alon Nisser identified a common MCP shortfall: models must “learn” tool behavior from scratch each time they interact with a server. Without persistent behavioral instructions, every session starts cold, with no framework to help the agent decide what to do next.

skill.md without MCP

A skill.md file gives agents behavioral instructions but no live connection to your data. The agent works from whatever it has in its training data or context window, which could include outdated information.

For static or low-change products, skill.md alone can be a valid starting point. But for more dynamic, API-driven products with frequent documentation updates, the lack of live retrieval creates a gap between what the agent knows and what’s currently true about your system.

Together: a complete agent stack

MCP handles transport, allowing the agent to connect and retrieve current data. skill.md handles behavior, teaching the agent what to do with that data. By combining them, your agent can provide grounded answers, and execute tasks reliably.

GitBook’s own experience validates the pattern: “The MCP was using the docs to explain how things worked, but it couldn’t produce a coherent system on its own. When I introduced the skill file, Claude could overcome the problems it had found using the MCP alone.”

Data retrieval got the agent into the ballpark, and behavioral guidance got it to the right seat.

Documentation quality is the foundation of both

A perfectly implemented MCP server with clean auth and fast response times still produces bad agent output if the underlying documentation is incomplete or poorly structured. Likewise, an incomplete skill.md leaves agents guessing at edge cases no matter how well-written the rest of the file is.

Both standards depend on high-quality, well-maintained documentation. In other words, the protocol and the behavioral layer are only as good as the content they surface and encode.

How to implement both

Setting up MCP

Build an MCP server that exposes your documentation as Resources, search as Tools, and common task patterns as Prompts. The technical implementation varies by language and framework, but the principle stays constant: your MCP server is only as good as the data it surfaces.

Before writing server code, audit your documentation. Is it complete? Is it current? Is it structured in a way that returns useful results when an agent queries for a specific topic? If the answer to any of those is no, fix the docs first. A fast MCP server returning stale content doesn’t help anyone.

Some documentation platforms automatically create an MCP server based on your docs — saving engineering time and encouraging user adoption.

Writing a skill.md file

Start with boundaries. Define the scope clearly so agents know when to apply (and when not to apply) the skill. Then provide a structural overview of your product’s core objects and entry points before describing any workflows.

Document workflows as step-by-step task instructions with explicit sequencing. Add “if/then” decision rules wherever users face choices between multiple paths. Finish with guardrails: unsupported actions, known failure modes, and environment constraints.

Resist the urge to describe features. Instead, describe tasks. An agent doesn’t need to know that your product “supports webhook configuration.” It needs to know: create the endpoint first, set the retry policy second, test with a sample payload third.

Where to host skill.md

Your documentation site is the right home. It’s already the product’s source of truth, it’s version-controlled, and it updates alongside product releases. Create a dedicated page with a stable, discoverable URL that agents (and agent-building developers) can find reliably — ideally example.com/docs/skill.md

GitBook hosts its own skill.md inside its documentation, serving as a reference implementation. Because GitBook’s platform is built to serve both human readers and AI agents, the skill.md file sits naturally alongside the rest of the product docs.

Frequently asked questions

Are MCP and skill.md competing standards?

No. MCP is a connection protocol, while skill.md is a behavioral guide. They operate at different layers with no overlap in function. Most agent-ready products will benefit from implementing both.

Do I need MCP to use skill.md?

You don’t. skill.md works with any agent that reads context files, regardless of how that agent connects to your system. MCP adds live data retrieval on top of behavioral guidance. skill.md alone is a valid starting point for products with stable documentation.

Does skill.md replace my existing documentation?

No. skill.md is a focused layer on top of full technical docs. Your existing documentation remains the source of truth for human readers. skill.md translates that content into machine-actionable instructions with explicit sequencing, decision rules, and guardrails.

How does MCP handle documentation that changes frequently?

An MCP server retrieves current documentation at the time the query is made rather than relying on training data. That means agents always get the latest version of your docs when they query through MCP. The live retrieval model reduces hallucination risk from outdated training data.

What AI tools currently support MCP?

Claude, ChatGPT, VS Code (in agent mode with extensions), and Cursor all support MCP. Per the 2025 AI Agent Index, 20 of 30 leading AI agents support MCP, which represents two-thirds of the field converging on the protocol within one year of its launch — and that number may be higher today.

Who maintains each standard?

MCP is maintained by Anthropic and the open-source community via modelcontextprotocol.io. skill.md is an emerging community standard with no single governing body. Both are framework-agnostic and designed for broad adoption.

Final verdict

Summary table

When to start with skill.md

Your product has stable workflows that agents need to execute correctly. You don’t yet have MCP server infrastructure in place. You want to make your documentation machine-readable quickly, and a Markdown file is the fastest path to get there.

When to implement MCP

Your documentation changes frequently and agents need current data. You want agents to search and retrieve specific content at query time. You’re building for MCP-compatible IDEs and AI assistants like VS Code, Cursor, and Claude.

The combined case

skill.md alone gives you behavioral guidance with no live data connection. MCP alone gives you live data retrieval with no behavioral guidance. Both together give you agents that retrieve current data and know exactly what to do with it.

Documentation quality remains the foundation, because both standards depend on accurate, well-structured, regularly maintained content. The protocol and the behavioral layer simply amplify good docs and expose bad ones.

GitBook supports both MCP and skill.md, and its documentation platform is built to serve human readers and AI agents from the same source of truth. You can explore how MCP works with documentation and how to write a skill.md file, or start for free to see how the pieces fit together.

→ What we learned building a complete docs site using Claude, MCP and skill.md

→ skill.md explained: How to structure your product for AI agents

→ MCP explained: What is an MCP server and why it matters for documentation