Skills vs MCP vs API: when you need each.

Why the confusion exists

The confusion is reasonable. All three sit between an agent and a service, and from the model's seat two of them arrive the same way: text and tool definitions loaded into context. When a PM at Linear said in a widely shared thread that he could not work out how skills differ from MCP, he was not being slow. He was noticing that the marketing for both says roughly "give your agent new powers," which is true and useless for telling them apart.

The distinction that actually holds is by mechanism, not by what they let an agent do. Ask one question per layer:

• API: what can be done over the wire, in the most literal sense? Endpoints and payloads.
• MCP: how does an agent discover and call those capabilities through one standard protocol? Tools and resources.
• Skill: how does an agent know which calls to make, in what order, with what defaults, to do a real job well? Packaged judgment.

Surface, interface, expertise. Hold that order and the rest falls out.

Layer 1: the API is the surface

The API is the ground truth. It is the set of HTTP endpoints a service actually answers, the exact request bodies it accepts, the responses it returns, and the auth it requires. Everything else in this post is a layer over the API; nothing can do more than the API allows.

An API makes no assumptions about who is calling. A human with curl, a backend job, a browser, or an agent all hit the same endpoints. That neutrality is its strength and its limit. The surface is complete, but it is also raw: the caller has to know which endpoint exists, read the schema, assemble the request, carry the token, and handle the errors. For a deterministic backend that is fine. For a language model deciding what to do next, it is a lot of undifferentiated surface area.

The honest version of an API ships a machine-readable contract so callers do not have to guess. That is what an OpenAPI document is: a single file that describes every endpoint, parameter, and response shape. Stacktree publishes one at api.stacktr.ee/openapi.json. Point any OpenAPI-aware client at it and the surface describes itself.

Layer 2: MCP is the interface

The Model Context Protocol is the standard way an agent talks to tools. Instead of teaching every assistant to read your particular API, you expose your capabilities as MCP tools and resources, and any compliant client (Claude Code, Claude.ai, Cursor, Codex, and others) can discover and call them. We covered what an MCP server is and how to build one in MCP servers explained for developers.

MCP is an interface, not a new set of powers. A tool like publish_html is a named, schema-typed front for an underlying API call. The value MCP adds is everything around that call: the agent can list the available tools at runtime, read each tool's input schema, invoke it without you hand-writing an integration, and do the same against any MCP server it meets. One protocol, many servers, every client.

MCP exposes more than actions. Its three primitives are tools (model-controlled actions), resources (application-controlled readable data), and prompts (user-controlled workflows). Which one to reach for is its own decision, worked through in resources vs tools vs prompts. The point for this post: MCP is the connection layer. It makes the API's surface callable in a standard, discoverable way. It does not, on its own, tell the agent what a good outcome looks like.

Layer 3: a skill is the expertise

A skill is packaged know-how. In the Anthropic Skills format it is a folder with a SKILL.md file at its root, optionally bundled with scripts and reference files. When the task is relevant, the agent loads the skill into context and gains not a new endpoint but a way of working: instructions, defaults, sequencing, and judgment about edge cases. A skill is the difference between an agent that can call your tools and an agent that knows how to use them well.

This is the layer people miss, because a tool and a skill both sound like "a capability." They are not the same kind of thing. A tool is a verb. A skill is the experience of having done the job a hundred times, written down. A skill commonly drives MCP tools, but it does not have to: because it is just instructions plus scripts, a skill can call a plain HTTP API directly, which means it works even where no MCP server is wired up.

Concretely, a good skill encodes the things a raw tool list cannot: which default is safe, when to ask before acting, what order to do things in, and how to recover when a step is ambiguous. That is expertise, and it is the layer that turns a pile of correct tool calls into a correct outcome.

Side by side

When you need each

For most agent-facing products the answer is all three, because each covers callers the others miss. But there is an order to reach for them.

• You always need the API. It is the foundation; the other two are layers over it. Ship a clean, documented API with a machine-readable spec and you have a surface everything else can build on, including integrations you never anticipated.
• Add MCP when agents are first-class callers. If you expect assistants to use your product directly, an MCP server is the lowest-friction way to reach all of them at once. No per-client integration, no bespoke tool-call shape, and the tools are discoverable at runtime. This is the interface most agents will meet you through.
• Add a skill when the job needs judgment, or when MCP is not wired up. If using your product well means more than a single call, with defaults, sequencing, and decisions about when to gate or ask, a skill captures that once so every agent inherits it. A skill also reaches agents that read the Skills format but have not connected your MCP server, because it can call your API directly.

The three are not a menu where you pick one. They are a stack, and shipping the whole stack is how you reach the most clients with the least friction on each.

The worked example: Stacktree ships all three

Stacktree is MCP-native private hosting for the HTML agents generate. It is a useful worked example here precisely because it ships all three layers over the same product, so you can see how they relate.

• The API is the surface. The HTTP endpoints that publish a page, replace it in place, gate it, expire it, list, and delete, plus the agentic-payment endpoints, are all described in the OpenAPI document at api.stacktr.ee/openapi.json. Anything that can speak HTTP can drive Stacktree from that contract alone, carrying an stk_live_ bearer token.
• MCP is the interface. The server at api.stacktr.ee/mcp exposes about ten tools over streamable HTTP with OAuth 2.1: publish_html, update_site, get_site, set_password, set_email_gate, set_expiry, set_agentation, list_sites, delete_site, and link_wallet. Any MCP client gets those verbs without a custom integration. The interface is the same whether the client is Claude Code, Claude.ai, Cursor, or Codex.
• The skill is the expertise. The publish skill at github.com/stevysmith/stacktree-skill (install with npx skills@latest add stevysmith/stacktree-skill) is not another copy of the tools. It encodes the judgment on top: publish private by default because agent output usually contains real data, gate or expire when the content warrants it, and use the publish-then-claim flow so an anonymous publish can be claimed and managed later. That is the know-how a raw tool list does not carry, written down so any agent that loads the skill works the way an expert would.

Read top to bottom, the stack reads cleanly. The API says what is possible. MCP makes it callable in a standard, discoverable way. The skill makes the agent good at it. If you are building an agent-facing product, that is the shape to aim for: a clean surface, a standard interface, and your hard-won judgment packaged on top so every agent inherits it.