Skills, Tools, and Docs: Sorting Out Where Agent Context Actually Belongs

Every team building agents eventually hits the same wall: the system prompt gets huge, tool definitions pile up, and the agent starts missing things it should know. Skills are a new answer to that problem. They are not a replacement for MCP or RAG. They are a third primitive, and knowing which one to reach for matters more than picking a favorite.

What a Skill actually is

A Skill is a directory with a SKILL.md file at the root. That file starts with YAML frontmatter, and the frontmatter requires two fields: a name and a description. At startup, the agent preloads only the name and description of every installed Skill into its system prompt. The full instructions inside SKILL.md, along with any bundled scripts or reference docs, only get read when the agent decides the task actually needs them.

That last part is the whole point. You are not stuffing every possible instruction into context up front. You are giving the agent a table of contents and trusting it to go fetch the chapter it needs.

Progressive disclosure is the design principle, not a feature

The pattern behind Skills has a name: progressive disclosure. Think of a manual that starts with a table of contents, narrows to a specific chapter, and only then drops into a detailed appendix. An agent with filesystem access and code execution doesn't need the entire Skill loaded to work on one task. It reads the name and description, decides relevance, then pulls in the rest on demand.

You're not loading everything up front and hoping the model ignores what's irrelevant. You're letting it ask for more only when it needs more.

This is the same instinct behind retrieval-augmented generation, but applied to instructions instead of documents. RAG solves 'what does the agent know.' Skills solve 'what does the agent know how to do,' loaded the same lazy way.

Skills package procedural knowledge, not API access

A Skill can bundle scripts and reference files alongside its instructions. A PDF-filling Skill, for example, can point to two additional files it only reads when the task calls for them, keeping the core SKILL.md short. The mental model is closer to handing a new hire a runbook than wiring up an integration. It captures how something gets done, including edge cases and gotchas, in a form that's reusable across agents instead of rebuilt per use case.

That distinction matters when you're deciding where a piece of context belongs:

• MCP tool: the agent needs to call something remote right now and get a structured result back
• Skill: the agent needs multi-step instructions, scripts, or reference material, loaded only when relevant
• RAG retrieval: the agent needs unstructured knowledge that changes often and doesn't fit a fixed instruction set

The live argument: Skills vs. MCP

This is genuinely unsettled among practitioners, not a solved best practice. MCP's strength is distribution. It's a standard protocol, agents connect to a server and get instant remote tool access, and nothing needs to be pre-downloaded. Skills have no concept of remote tool access. They're distributed as zip files and live on a local filesystem.

But MCP's weakness is exactly what progressive disclosure fixes. An MCP server that exposes a large number of tools loads all of those tool definitions into context at initialization, whether the current task needs them or not. Teams building MCP servers that expose too much surface area are running into the same failure mode: context gets eaten up before the actual task starts, and accuracy drops. Skills sidestep that by loading almost nothing until the agent asks for it.

The honest answer right now is that these are complementary, not competing. Use MCP when you need standardized, machine-callable access to something remote. Use a Skill when you need to hand the agent a playbook it should consult selectively.

The protocol is moving too

It's worth noting MCP itself isn't standing still. A recent spec revision added enhanced authorization server discovery with OpenID Connect Discovery support, icon metadata for tools and resources, and groundwork for async support so servers can kick off long-running tasks while clients check back later for results. That's the protocol layer maturing at the same time the instruction-packaging layer gains a new primitive. Two different problems, evolving in parallel.

A practical framework for deciding

When you're architecting an agent's context, ask three questions in order. Does this capability need to reach a remote system in real time? That's MCP. Is this a repeatable, multi-step procedure with instructions, scripts, or reference docs that don't change per request? That's a Skill. Is this a large, frequently updated body of unstructured knowledge the agent needs to search rather than follow step by step? That's RAG.

Most production agents will end up using all three. The mistake to avoid is defaulting to one primitive for everything, whether that's cramming procedural knowledge into a bloated system prompt, exposing too many MCP tools at once, or trying to force step-by-step instructions through a retrieval pipeline built for documents. The primitives exist because the problems are different. Treating them as interchangeable is how context windows get expensive and agents get unreliable.