A team I know spent three weeks last quarter shipping an MCP server that wrapped their internal style guide. JSON-RPC transport, OAuth flow, a small Fly.io instance, a status page, the works. The thing they actually wanted Claude to do was read a markdown file and apply nine rules to a draft. That whole project should have been a SKILL.md and a 40-line Python script in a scripts/ folder. They picked the wrong primitive, and now they own a service.
This is the skill.md vs mcp question most authors get backwards. Anthropic ships both formats, the Model Context Protocol has a registry pushing past 10,000 public servers, and every tutorial on the internet frames the choice from the consumer's side. If you're the one publishing, the calculus runs differently. The default should be a folder. You reach for the protocol only when the folder really can't do the job.
What you're actually shipping in each case
A SKILL.md is a directory. There's a markdown file with YAML frontmatter at the top (name, description, sometimes allowed-tools or disable-model-invocation), the body is instructions in plain English, and you can drop scripts/, references/, and examples/ alongside it. The Claude Code docs describe the load behavior: only the name and description sit in context until the model decides the skill is relevant, then the body loads. Anything inside scripts/ runs in the agent's own environment using whatever shell or Python the agent already has. There is no network listener, no process you maintain, and nothing to rotate.
An MCP server is a process. It speaks JSON-RPC, runs in its own container or on stdio, exposes tools with typed schemas, and the agent connects to it as a client. The MCP spec describes the protocol as "a USB-C port for AI applications," which is accurate as far as it goes. The implication people skip is that USB-C ports require a device on the other end. Someone has to keep that device powered, patched, and reachable. If you publish an MCP server, that someone is you.
ByteByteGo EP213 breaks the comparison cleanly along five axes: integration shape, architecture, invocation style, runtime, and deployment surface. The summary worth memorizing: MCP is client-server with typed tool calls validated against a schema. A skill is a directory the agent reads and acts on. Different categories of thing.
The four differences that decide it
State. A SKILL.md is stateless across invocations. Every time the agent loads it, the markdown is the same text. If your tool needs to remember something between calls (a session token, a cursor into a paginated dataset, the last alert ID it saw), that lives on a server, not in a folder.
Runtime. A skill runs wherever the agent runs. A laptop, a CI runner, a Codex sandbox. An MCP server runs where you put it. If the work needs to happen near the data (a Postgres replica, a private VPC, a GPU), the server has to live in that network and the skill can't reach it directly. If the work is "rewrite this text" or "format this file," there is no network requirement at all and the folder wins.
Credentials. This is the one most authors get wrong. A skill that does gh pr comment uses whatever GitHub token is already in the agent's environment. The agent inherits the user's credentials. An MCP server holds its own credentials and brokers access on behalf of many users. That's a feature when you're a company publishing access to a billing API and you want one audited credential boundary. It's a liability when you're a solo author publishing a way to lint markdown and now you're on the hook for everyone's API keys.
Distribution. Skills install by git clone or by dropping a folder. They have no runtime dependency. MCP servers require the user to add a config entry, run a process, manage updates, and trust the binary. The friction is not symmetric. A skill someone tries on a Tuesday and forgets about costs them nothing. An MCP server they tried and forgot is a process still running on their machine.
A decision tree that actually decides
Walk it top to bottom. First match wins.
Does the work require keeping state between agent invocations that doesn't fit in a file the agent already has access to? MCP server.
Does the work require network access to a private system the agent's machine can't reach directly? MCP server.
Does the work require a shared credential the team uses through a single audited boundary? MCP server.
Does the work require pushing real-time events to the agent (a live Sentry feed, a webhook the agent should react to)? MCP server.
Everything else is a skill. That includes the cases people mistakenly turn into servers: applying a style guide, generating a PR description, formatting a changelog, running a security review, scaffolding a new service, validating a config file, writing a regex you'll forget tomorrow. Folder. Markdown. Done.
The concrete examples are worth holding in your head. GitHub PR comments are a skill because the agent already has gh and a token. A live Sentry alert feed is a server because the data is changing and the agent can't poll. Deploying to Render is both, and that's the interesting case. The render-deploy skill in OpenAI's skills repo is a folder that encodes "here's how we deploy: check the blueprint, validate it, then call these tools." The tools it calls are on Render's MCP server. The skill is the playbook. The server is the hands. A private internal API your team alone uses through one credential? MCP server, run it on your own infrastructure.
Speakeasy made this point more bluntly than most: skills teach the agent how to do things, MCP servers give it the ability to do them. Most production agents end up with both. The mistake authors make is starting with the server when the skill alone would have shipped on a Wednesday afternoon.
A short comparison
| SKILL.md | MCP server | |
|---|---|---|
| Shape | folder with markdown | process speaking JSON-RPC |
| State | stateless | can hold state |
| Runs in | agent's environment | its own container or stdio |
| Credentials | inherits from agent | manages its own |
| Distribution | clone a folder | install + run a process |
| Failure mode if buggy | the agent ignores it | the service goes down |
| Time to ship the first version | an afternoon | a week, plus ops |
You're publishing this wrong if
You wrapped a markdown reference doc in an MCP server. The point of a server is to do something the agent can't do alone. Reading text is not that. Put the reference in a references/ folder inside a skill and let the agent open it on demand.
You wrote a skill that does authenticated calls to a multi-tenant API and you're shipping it for your whole company. Every user who installs the skill needs their own credential, and you have no way to rotate, audit, or revoke. This is the case where the credential boundary of a server actually buys you something. The skill should call your MCP server, and the server should hold the credential.
You shipped an MCP server with one tool that wraps one shell command. There is no state, no shared credential, no real-time data, no private network. You've added a process, a deploy target, and a versioning story to your team. The tool should have been three lines in a skill's scripts/run.sh.
The author's actual calculus
Time to ship. A skill is an afternoon. A server is a week, plus an ops tail that never ends. If you're not sure the thing will be useful, ship the skill, watch what happens, promote it to a server only if state or credential pressure forces your hand.
Blast radius. A buggy skill produces a bad PR description and the user closes the tab. A buggy MCP server returns wrong data, returns it confidently, and the agent acts on it. The cost of being wrong is higher when you ship a server, because the agent trusts schema-validated tool calls more than it trusts a markdown file's suggestions.
Ops burden. Folders don't page you at 2 a.m. Servers do.
Distribution friction. Skills install with git clone and a copy. Servers require config edits, a process, and trust. If you want adoption, the folder wins.
Knack outputs the SKILL.md side of this question. You describe the workflow in plain English through the interview flow, and Knack writes the folder that any Claude or Codex agent can load. The MCP server, when you actually need one, you write in Python or TypeScript like any other service. The two artifacts answer different questions and they compose well.
LlamaIndex's experience running both in production lands on a similar split: MCP for rapidly-changing live state, skills for stable workflows you can write down once. Sumo Logic put it as "skill is packaged judgment, MCP is the access badge." Both framings get to the same place from different angles. The default for publishers is judgment, written down. Reach for the access badge only when judgment alone can't see what it needs to see.
If you're sitting on a thing you want to share with other agents and you don't yet know which one to publish, start with the folder. You can always promote it later. The other direction is a refund.