Agent Skills are just folders of Markdown — and after a year of MCP hype, that's the point
After a year of everyone — me included — wiring up MCP servers to give coding agents new powers, the most useful agent feature I've adopted lately is almost embarrassingly low-tech: a folder with a Markdown file in it. Anthropic calls them Skills, and the longer I use them the more they read as a quiet correction to the MCP hype: a lot of "give the agent a capability" turns out to be "give the agent the right paragraph at the right moment."
What a Skill actually is
A Skill is a folder containing a SKILL.md — instructions in Markdown — plus optional scripts and resource files the agent can use when a task calls for them. Anthropic's own definition is refreshingly plain: "Skills are folders that include instructions, scripts, and resources that Claude can load when needed." They were announced in October 2025 and, more interestingly, promoted to an open standard in December 2025 with org-wide management — the move from "our feature" to "a format anyone can implement" is the part that matters.
The mechanic that makes them work is progressive disclosure. The agent doesn't load every skill into context all the time; it reads just the short front-matter description of each, and only pulls the full instructions and scripts into context when the task actually matches. It's a token-budget play dressed as a capability system — the agent keeps a table of contents in its head and opens the chapter only when it needs it. And the same format works across the Claude apps, Claude Code (drop them in ~/.claude/skills or pull from a marketplace), and the API. Build once, use everywhere.
Why this is the honest counterweight to MCP
I've written about MCP a fair bit, so let me be fair to both. MCP and Skills aren't rivals — MCP is about live connections and data (talk to my database, hit this API in real time), Skills are about know-how and procedure (here's how we do a release, here's the house style for a migration). But the marketing blurs them, and the blur hides a genuinely useful realization: a huge fraction of what people stand up an MCP server for is not "the agent needs a live connection," it's "the agent needs to be told the steps." And for that, a running daemon with a transport and an auth handshake is wild overkill next to a text file.
Half the time you don't need to give the agent a new tool. You need to give it the paragraph it was missing. Skills are that paragraph, versioned in git, with none of the plumbing.
That's the part I love as a self-hoster. A SKILL.md is something I can read in a text editor, diff in a pull request, and reason about completely. An MCP server is a process I have to run, patch, and babysit. For encoding procedure — the shape of a deploy, the conventions of a codebase, the checklist for a tricky refactor — the folder of Markdown wins on every axis I care about.
The caveat I'd put in bold
"It's just a folder of Markdown" is the pitch and also the risk. A Skill isn't only instructions; it can carry scripts, and the agent will execute them. It's unsandboxed know-how plus code, loaded on demand — which means a skill you installed from a marketplace or copied from a repo is a supply-chain surface, the same way a dependency is. I've already written about a worm that planted payloads in agent config files that run when you so much as open a project; a malicious SKILL.md with a helpful-looking setup script is the same category of problem in a friendlier wrapper. So treat skills like dependencies: read them before you install them, prefer ones you or people you trust wrote, and don't paste a stranger's skill into ~/.claude/skills any more casually than you'd npm install their package.
With that caveat honored, Skills are the rare agent feature that's less than it sounds, in the good way. No protocol, no server, no handshake — just the right instructions, disclosed when relevant, versioned like code. A year into the MCP era, the most practical upgrade to my agent workflow was remembering that most of the time, the missing piece was never a tool. It was a paragraph.