The skill file: why the best agents are just Markdown and scripts

Here is a pattern worth noticing. Three different teams, working independently, building three different AI agents, arrived at the same answer to the same question — and the answer is almost comically plain.

The question is: where does an agent keep what it can do? Not the model, not the conversation — the specific, learned, reusable competence. How to reconcile two exports. How to file a particular kind of expense. The procedure for checking a flight in. Where does that live?

Nous Research's Hermes Agent writes it as Markdown and Python files on disk. OpenClaw, the personal-assistant agent that reached a quarter of a million GitHub stars in early 2026, ships over a hundred of these files and lets you add your own. And Anthropic took the format its Claude agents use, called it SKILL.md, and published it as an open standard in December 2025. Three teams, no coordination, one shape: a folder, with a Markdown file in it, and maybe a scripts directory next to it.

No vector database. No fine-tune. No proprietary plugin binary. The unit of capability for the strongest agents of this year is a text file you could open in Notepad. That is not a failure of imagination. It is the result everyone backed into once they actually tried to run agents on real work.

What a skill file actually is

Strip away the branding and a skill is a directory. Inside it, one required file — SKILL.md — and some optional company.

The SKILL.md file has two parts. At the top, a short block of YAML metadata: a name, and a description of when the skill applies. Below that, Markdown instructions written in plain language — what to do, when to do it, which tool to reach for. That is the whole required surface. A competent skill can be twenty lines.

Around it, optionally, sit a few folders by convention: a scripts/ directory for executable code the skill calls, a references/ directory for documentation the agent pulls in only when it needs the detail, an assets/ directory for templates and supporting files. The skill body points at them with a relative path. The agent reads the Markdown, and if the task calls for it, runs the script or opens the reference.

The detail that makes this efficient rather than bloated is when it loads. The agent does not hold every skill in its head at once. The short description in the frontmatter is what it scans; the full instructions and the heavy reference files only come into context when the skill is actually relevant. Capability sits dormant on disk for free and wakes up on demand. You can have a thousand skills and pay for the three you use.

The same shape, three times over

What is striking is not that one team chose this. It is that the convergence is nearly exact.

OpenClaw did not invent its own format — it adopted the SKILL.md standard directly. Its skills are the same directory-with-a-Markdown-file, the same YAML frontmatter and Markdown body, the same scripts/ and references/ and assets/ companions. Personal skills live in a folder in your home directory; project skills live in a folder inside the repo itself, version-controlled with the code they serve. The agent watches those folders and picks up changes when you edit the files.

Hermes arrived at the same place from a different direction. Rather than shipping a library for you to install, it writes its own skills — after finishing a task, it extracts what worked and saves it as a Markdown or Python file it can read next time. We wrote about that loop in how Hermes turns experience into skills. The mechanism is different; the storage is identical. A folder of plain files the agent can read, edit, and reuse.

And Anthropic, having used this internally, did the thing that turns a pattern into infrastructure: it published SKILL.md as an open standard, explicitly designed to work across Claude and any other platform that adopts it. The format is no longer one company's convention. It is becoming the shared unit that agents of different makes can read.

When three independent teams converge and then one of them publishes the open spec, you are not looking at a trend. You are looking at a standard forming in real time — the way MCP became the standard way for an agent to reach a tool, the skill file is becoming the standard way for an agent to carry a capability.

Why the boring format won

It would be easy to read "plain Markdown" as the simple option that will get replaced by something cleverer. It is the other way around. The cleverer options were tried, and this is what survived contact with real use. Three properties explain why.

It is inspectable. You can open a skill and read, in plain language, exactly what the agent believes it should do. There is no embedding to decode, no weights to interpret. The agent's competence is legible to a human. When it does the wrong thing, you can find the line that told it to.

It is editable. Because the capability is text, you fix it by editing text. You do not retrain a model or argue with a prompt to talk it out of a habit — you change the file, and the next run behaves differently. The feedback loop between noticing a problem and correcting it collapses to editing a paragraph.

It is version-controllable. This is the one that matters most, and the one the format gets almost for free. A skill library is just a directory of files, so it goes straight into git. You can diff what your agent learned this week. You can review a new skill before it ships, the way you review a pull request. You can roll back a skill that turned out to be harmful. The agent's growing competence becomes a repository — an asset you own, audit, and govern with the exact tools your team already uses for code.

Put those together and you get something a black box can never offer: an agent whose capabilities you can actually reason about. Other formats optimised for the machine. This one optimised for the human who has to live with the machine — and that turned out to be the constraint that mattered.

What this means if you're building on agents

For anyone putting an agent into real work, the skill file changes the question you should be asking.

The old framing was "how capable is this model out of the box." The better framing is "what does this agent accumulate, and can I govern it." An agent built on plain skill files gives you a capability layer that is yours — versioned in your repo, reviewed in your process, portable if you change models or vendors underneath. The model becomes the engine; the skills become the part you actually own. When a better model arrives next quarter, your skill library moves over intact, because it was never tied to the model in the first place.

That portability is quietly the whole game for a business. The thing you invest in — the hard-won, specific procedures for your work — should not evaporate when you switch providers. With skill files, it doesn't. It is a directory. It comes with you.

The honest limit

One caveat, and it is the same one that runs through everything we write about agents: readable is not the same as safe.

A skill file can carry a scripts/ directory, and those scripts run with whatever permissions the agent has. OpenClaw learned this in public — third-party skills were found carrying code that harvested credentials, and the broad access the agent needs to be useful is exactly the access a bad skill abuses. The plain-text format does not prevent any of that. It just means the harmful instruction is sitting there in legible form, available to be caught.

So the inspectability is not a safety feature on its own. It is the precondition for one. A skill library you can read is only safer than a black box if someone actually reads it — reviews new skills before they run, treats an installed skill from a stranger with the same suspicion as a dependency from a stranger, and keeps the script folder under the same scrutiny as the rest of the codebase. The format hands you the ability to govern your agent's capabilities. Whether you use it is on you.

The takeaway

The future of agent capability turned out not to be exotic. It is a folder with a Markdown file and a scripts directory, checked into git, that a human can read and an agent can run. Hermes writes them, OpenClaw ships them, Anthropic standardised them, and the convergence is the point: when independent teams reach the same plain answer, it is usually because the plain answer is correct.

If you are choosing what to build your agents on, treat the skill file as a feature, not a quaint detail. Ask whether the agent's capabilities live somewhere you can open, diff, and review — or somewhere you are asked to trust. The best agents of 2026 are, underneath, just Markdown and scripts. That is not the unglamorous part of the story. It is the part that makes them usable.

---

If you are building on agents and want a senior read on how to structure, review, and govern a skill library so it stays an asset rather than a liability, that is the kind of thing we help with at Think and Form Limited. Get in touch at admin@thinkandform.co.nz.