Agent Skills, Explained: What SKILL.md Is and How It Differs From MCP

Something unusual happened over the winter. Anthropic published the Agent Skills specification on December 18, 2025, and within 48 hours Microsoft had integrated it into VS Code and OpenAI had added support to both ChatGPT and Codex CLI. By March 2026 some 32 tools from competing companies, including Google's Gemini CLI, JetBrains' Junie, AWS's Kiro, and Block's Goose, all read the same files from the same directory structure. By June the showcase at agentskills.io listed around 40 products. Standards in this industry usually take years to settle. This one took a quarter.

If you're arriving now and wondering what a skill actually is, whether it replaces MCP, and what any of this means for how you build agents, this post is the map.

What a skill actually is

A skill is a folder. At its center sits a file called SKILL.md, which combines YAML frontmatter that machines read with a Markdown body that both humans and models read. The spec requires exactly two frontmatter fields, a name and a description. Everything else, versioning, scripts, resource files, licensing metadata, is optional.

The description matters more than it looks. Agents scan the descriptions of installed skills to decide what's relevant to the task at hand, and only then load the full body. This is the trick that makes skills scale: an agent can have hundreds installed and pay the context cost only for the one or two it actually needs. The industry has taken to calling the pattern progressive disclosure, and it looks like this in practice:

What goes in the body is procedural knowledge. How to run this project's deploy. What a proper code review covers in this repo. The house style for quarterly reports. Which API to call first when reconciling invoices, and what to do when it times out. Anything you would explain to a competent new hire on their first week is a candidate.

That framing explains the adoption speed. Every team running agents had already accumulated this knowledge in scattered prompts, wiki pages, and tribal memory. Skills gave it a portable shape. Write the folder once and Claude Code, Copilot, Cursor, and Gemini CLI can all use it, which also means switching agents no longer means losing your operational knowledge.

Skills vs. tools vs. MCP

The most searched confusion, judging by autocomplete, is how skills relate to MCP and to tools. The clean way to hold it:

A tool is a capability. It's something the agent can do: query a database, send a message, execute code. Tools are functions with schemas.

MCP is connectivity. The Model Context Protocol is the wire standard for exposing tools and data sources to agents across process and network boundaries, with authentication, discovery, and (since the July 2026 revision) a stateless core that enterprises can deploy behind load balancers. MCP answers "how does the agent reach systems."

A skill is knowledge. It doesn't grant the agent any new capability. It tells the agent how and when to use the capabilities it already has, in the specific way your organization needs them used.

The three compose rather than compete. A useful analogy from ordinary work: tools are the software installed on an employee's laptop, MCP is the corporate network and SSO that connect that laptop to real systems, and skills are the onboarding docs and runbooks. Nobody asks which of those replaces the others.

A tool is what an agent can do. MCP is how it reaches things. A skill is knowing how the job is actually done.

So when people search "agent skills vs mcp," the honest answer is that the comparison is a category error, and the practical answer is that you'll use both, usually in the same afternoon.

We ran the numbers on progressive disclosure

Claims about context efficiency are cheap, so we built a small experiment instead of asserting one. We wrote three realistic skills to the spec (an invoice reconciliation procedure with a working helper script, a weekly status report format, and a release checklist), then measured what an agent actually pays in context under the two loading strategies.

A skill in the experiment looks like this, abridged:

---
name: invoice-reconciliation
description: Use when asked to reconcile invoices between the billing
  export and the ledger, investigate invoice discrepancies, or prepare
  a month-end reconciliation report.
---

# Invoice Reconciliation

1. Pull both sources for the same period before comparing anything.
2. Match on invoice_id first, never on amount. Amount-matching produces
   false pairs whenever two invoices share a total.
3. Run scripts/check_totals.py to get the diff set...

The per-skill measurements, with tokens estimated at four characters each:

That gives three loading strategies to compare per task. Eager loading pays index plus every body on every task, 911 tokens, whether or not any skill is relevant. Progressive disclosure pays the 109-token index always and adds one body only on tasks that need it, 447 tokens in the worst case here. On tasks where no skill applies, it pays the index alone.

So even at three skills, eager loading costs 8.4 times the index, and the gap grows linearly with every skill you add. Projected to 100 installed skills of the same average size, the index runs about 3,600 tokens while eager loading would run about 30,000, per task, on every task. That's the whole mechanism in two numbers: description-first discovery is what lets an agent carry a large skill library without paying for it constantly.

The experiment also sharpened something we'd have otherwise said loosely: the description is the routing signal. Ours all start with "Use when" followed by concrete triggers, and that's what makes the index worth its 109 tokens. A vague description forces the agent to load the body just to find out whether the skill applies, which quietly turns progressive disclosure back into eager loading. Skill folder, measurement script, and full results are in our repo's experiments directory if you want to rerun it.

Why this matters more in the enterprise

For individual developers, skills are a convenience. For organizations, they change the economics of agent deployment, and this is the part we care about most.

The expensive thing about rolling agents out across a company was never the model. It was encoding how the company works: the procedures, exceptions, and standards that make output acceptable rather than merely plausible. Before skills, that encoding lived in prompts welded to one vendor's product, which made it unportable and unauditable. As a folder of Markdown under version control, the same knowledge gets code review, history, testing, and reuse across every agent surface the company runs.

It also becomes an asset with a supply chain, which cuts both ways. A skills marketplace is already forming, and importing a third-party skill means importing instructions your agents will follow. Treat skills the way you treat dependencies: pin them, review them, and know who wrote them. The OWASP agentic security work now lists supply chain among its top risks for exactly this reason.

We took a position on this early. Zytherum ships with over 115 enterprise skills covering the procedures that recur across deployments, from reconciliation runbooks to report generation, and treats customer-authored skills as first-class, versioned platform objects with the same evaluation gates as everything else. The spec becoming an open standard validated the bet: knowledge packaged this way outlives any single agent product, including ours.

Getting started, and one warning

Starting is deliberately easy. Make a folder, write a SKILL.md with a name, a description that says precisely when the skill applies, and a body that explains the procedure the way you'd explain it to a person. Install it where your agent looks for skills. The two failure modes we see are descriptions too vague for the agent to know when to load the skill, and bodies that read like marketing rather than instructions. Write both like documentation, because that's what they are.

The warning: skills are instructions, and agents follow them with less skepticism than a human would. A skill that says "always push directly to main" will be obeyed. Review what you install, audit what you write, and keep skills in the same governance loop as the rest of your agent stack. Portable knowledge is a genuine advance. Portable bad knowledge is too.

ArthaVortex builds Zytherum, an agent platform that ships 261 tools across 47 integrations and treats skills as versioned, governed platform objects. Questions about skills strategy? Talk to us.