Claude Skills: The Most Underrated Feature in the Agent Ecosystem
A folder with a markdown file, and somehow it solves the problem every other vendor is still trying to ship around.
Anthropic shipped the cleanest abstraction in the agent ecosystem six months ago, and most teams I talk to still cannot tell me what it does. They have opinions about MCP. They have spreadsheets comparing tool-use latency across vendors. They have a slide deck on “system prompt strategies” that runs to forty pages. Ask them what a Claude Skill is and you get a pause, then a guess that it is some kind of plugin, or maybe a custom tool, or possibly the same thing as an MCP server. It is not. It is a different primitive, and once you see it for what it is, the agent architecture conversation simplifies in a way that is genuinely hard to walk back.
A skill, in the Claude implementation, is a folder. The folder contains a file called SKILL.md with YAML frontmatter on top: a name, a description, and optionally a license or version. Below the frontmatter is the body, which is instructions to the agent about what the skill does and how to use it. The folder may also contain other files: reference documents the skill points to, runnable scripts the agent can execute, templates it can fill in.
That is the whole format. There is no registry, no manifest, no install step. You put the folder somewhere Claude can read it, and the skill exists.
The cleverness is in how the agent loads it. Claude does not pull the full skill body into context at the start of a session. It reads only the name and description from the frontmatter, across every skill available to it, and keeps those in working memory the way a human keeps a mental index of what tools are in the drawer. When the user asks a question that matches a description, the agent reaches into the folder and loads the body. If the body references other files, those load only when the agent actually opens them. This is what Anthropic calls progressive disclosure, and it is the part that makes the abstraction scale. A team can ship fifty skills to an agent without burning context on any of them until the moment one is needed.
This is where the confusion with MCP starts, and it is worth being precise. MCP is a protocol. It connects an agent to a running server that exposes tools and resources over a defined interface. The server is a process; it has uptime; it can be remote; it handles auth and state and concurrency.
A skill is none of those things. A skill is a static folder of text and optional scripts. The skill does not run anywhere until the agent decides to use it. MCP solves “how does the agent reach the running system that does the work.” Skills solve “how does the agent know what work is even possible and how to do it.”
Those are different problems, and the right architecture often uses both. A skill might instruct the agent on a workflow that calls four MCP tools in a specific sequence. The skill is the recipe; the MCP server is the kitchen.
The confusion with tools, in the function-calling sense, is the other failure mode. A tool is a single function with a schema, exposed to the model so it can call it with structured arguments. A skill is a packaged capability that may contain tools, may contain instructions, may contain reference files, may contain runnable scripts, and may contain none of those at the upper bound.
The smallest valid skill is a SKILL.md with a description and three paragraphs of instructions. That is a complete, useful skill. It teaches the agent how to do something it could not do before, with no code, no server, no schema. The largest skill might be a folder of fifty files and a runnable Python script that the agent invokes via a shell tool. Both are skills, both load through the same progressive-disclosure mechanism, and the format does not care.
What makes the abstraction clean is the set of properties it has by default. Skills are discoverable through their descriptions, triggering the same way a tool would by matching intent against metadata. Skills are composable, because they are folders, so a skill can be made of other skills the same way a directory can contain subdirectories. Skills are versionable, because they live in git like any other text. Skills are shareable, because copying a skill across teams is copying a folder. Skills are progressively disclosed, which means the context cost is paid only on use.
None of those properties required a new protocol, a new runtime, or a new format. The abstraction worked because Anthropic resisted the temptation to invent any of those things and shipped a folder with a markdown file.
Where it earns its place is in everything you would otherwise stuff into a system prompt that grows without bound. The skill is the right place for “how this team writes pull request descriptions,” for “the seven steps to onboard a new customer in our billing system,” for “what our internal glossary calls a deal versus an account versus a contract.” Those are not tools. Those are not facts. They are workflows and conventions and the kind of knowledge that lives in a wiki nobody reads. Skills are the agent-shaped expression of that knowledge, and the format is small enough that a domain expert can write one without learning a framework.
The honest limitations matter, and none of them explain why the feature itself is underrated, which is a separate problem with a different cause. Skills are Claude-only today, with no portable spec across vendors, which means a skill you write does not run on GPT or Gemini without translation. The description field is load-bearing in a way that takes a few tries to get right; a description that is too generic gets ignored by the agent, and a description that is too narrow misses the cases you wanted it to handle.
The progressive disclosure model is not free, because a skill that auto-loads on a tangential match still spends tokens on its body before the agent decides it was the wrong choice. The ecosystem for sharing skills across teams and organizations is embryonic, with no real registry or distribution model, which is the gap our team has been filling with the npm-packaged approach the rest of this arc covers. The scripts a skill includes run in the agent’s own environment, which means anything you ship as a skill carries the security posture of the host process, not the sandboxed isolation a remote MCP server would give you.
The reason it is underrated is mostly a marketing accident. Anthropic shipped skills in a docs update that landed between two louder launches, and the community read it as “oh, a way to organize prompts,” then moved on. The MCP announcement got conference talks; skills got a paragraph in a changelog.
Half the engineers I have talked to about this still think a skill is a fancy system prompt. The other half think it is a competitor to MCP. The fact that it is neither, and that the abstraction is small enough to fit in a folder, makes it easy to overlook and hard to evaluate against the noise.
This is the gap the rest of this week’s posts are written to close. The next one argues that the architectural shift is to build skills first and treat the agent as the cheap, replaceable wrapper around them. The day after, I cover the npm-packaging pattern our team has landed on for distributing skills across the org with the same workflow as any other library. Then comes the case for treating agents as code you check in, not SaaS you subscribe to, and the comparison against the hosted tool-registry model that several vendors are trying to sell as the alternative.
The throughline is what yesterday set up. The framework you pick wraps the loop. The skills you ship are the product. Claude Skills are the closest thing to a clean specification of that unit that anyone has put in front of practitioners, and the year ahead is going to be defined by who notices.
If this was useful, forward it to one engineer who needs less noise in their feed.