An AI Skill Is Just a Markdown Folder

An AI agent "Skill" is a folder with one Markdown file in it. That is the whole format. The marketplace it lives in grew from 2,179 skills to 40,285 in twenty days — an 18.5× increase ¹ — and the artifact underneath all that motion is a SKILL.md you could write in any text editor you own.

The number is real and dated. A February 2026 data-driven analysis from Bosch Research and Carnegie Mellon University measured the surge across a single marketplace: 38,106 new skills in twenty days, "an average multiplicative growth rate of about 15.7% per day" ¹. On the steepest day, January 25, "8,857 skills are added in a single day," nearly a quarter of the window's total ².

GitHub kept pace. One flagship open-source skills project reached "over 25,000 stars in a single day at the end of January" ³, and a wall of *-skills repositories rose alongside it.

What everyone thinks a Skill is

Most people meet Agent Skills as the next exotic AI primitive — something adjacent to models, embeddings, and vector stores, requiring a new mental model and probably some code. The trend reads that way from the outside. An 18.5× explosion, a marketplace, a leaderboard of starred repositories, and a vocabulary you have not learned yet.

The framing is understandable. Anything that multiplies sixteen percent a day looks like infrastructure, and the community treated it that way. The same study found "skill publication tends to occur in short bursts that track shifts in community attention" ⁴, the rhythm of a gold rush rather than a quiet utility.

So the expectation going in is complexity. The reality is the opposite.

What a Skill actually is

A skill is a directory with one required file. Anthropic, which introduced the format, defines it plainly: "A skill is a directory containing a SKILL.md file… This file must start with YAML frontmatter that contains some required metadata: name and description" ⁵. The open specification at agentskills.io agrees: "At its core, a skill is a folder containing a SKILL.md file" ⁶.

That is the anticlimax. Strip the marketplace away and you are left with a folder, a Markdown file, and a few lines of front matter naming the thing. The Bosch and CMU analysis measured the size directly: "the median skill contains 1,414 tokens" ⁷ — a page or two of prose, not a megabyte of machinery. A skill can bundle scripts and resources for heavier work, but the load-bearing core is text a human wrote and a human can read.

Here is a complete one. There is no surrounding project, no install step, and nothing hidden:

---
name: changelog-writer
description: Draft a release changelog from a list of merged changes.
---

# Changelog writer

When asked to write a changelog:

1. Group changes into Added, Changed, Fixed, Removed.
2. Write each entry in plain past tense, one line each.
3. Lead with user-facing impact, not the internal mechanism.
4. Omit anything a reader outside the project cannot verify.

## Example

- Added: export any note to a single Markdown file.
- Fixed: long documents no longer drop the last heading on print.

That file is the entire skill. The front matter names it and tells the agent when to reach for it; the body is instructions in ordinary Markdown. There is no build step, no schema to compile, no runtime to install. The format is a discipline you can hold in your head — write the procedure down clearly, in a file, in a folder. You have done harder things in a grocery list.

Why the format is the point

The reason a skill is plain Markdown in a folder is portability — and portability is the entire argument. Skills package procedural knowledge "into portable, version-controlled folders that agents load on demand" ⁸, so you can "Build a skill once and use it across any skills-compatible agent" ⁹. The folder is the unit of reuse precisely because it is dumb, readable text that nothing needs to translate.

Dumb is the feature.

That is why the same format reaches across vendors. Claude Code "skills follow the [Agent Skills] open standard, which works across multiple AI tools" ¹⁰. OpenAI's Codex documents the identical shape: "A skill is a directory with a SKILL.md file plus optional scripts and references" ¹¹. Microsoft's VS Code calls it "an open standard that enables portability across different AI agents" ¹². Four toolmakers, one artifact — a folder of Markdown, not a binary locked to one company's runtime.

A format you can read is also a format you can trust. Anthropic's own guidance warns to use skills only from sources you trust, because a malicious skill can direct an agent to run code. The defense is the same property that makes the format portable. A skill you authored in plain Markdown is one you can open, read line by line, and verify before you run it. Legibility is not a side effect here. It is the security model.

You already write these

If a skill is a folder of Markdown instructions you own and carry between tools, then you have been writing skills for years. You just called them notes. The retrospective procedure you keep, the meeting-summary template you reuse, the deploy checklist you paste — each is procedural knowledge in plain text, stored in a file you can move. The agent era did not invent that artifact. It standardized it.

This is the quiet inversion. For a decade, keeping knowledge in plain text was a minority discipline — a thing PKM hobbyists and Unix holdouts insisted on while the market sold databases and walled apps. Then the agent stack, the most aggressive new layer in software, looked at every available format and converged on the same answer: a folder, a Markdown file, front matter, prose.

Your notes were already in the shape the agents reach for.

Name the limits honestly. The 18.5× figure is a single twenty-day window, and the study itself frames the growth as "bursty," attention-driven, with the flagship project's star count "followed by a gradual decline" after its spike ³. This is not a permanent vertical line. But a fad does not converge four competing toolmakers on one open file format. The hype will cool. The artifact — a readable folder of Markdown you own — is the part that stays.

The agent-standard trio

Three plain-text conventions now carry the 2026 agent stack, and a skill is one of them. They are easy to blur into a single buzzword, so it helps to keep them straight. They are not the same thing, and each is just a file or a folder you could open by hand.

• AGENTS.md is project configuration: one Markdown file at a repository's root that tells an agent how this project works. It is the README an agent reads. (See AGENTS.md: a README for your agents.)
• MCP is the wire: the open protocol an agent uses to reach into your tools and files. It is the transport, not the content. (See the protocol letting AI reach into your files.)
• A Skill is portable capability: a folder of Markdown packaging one procedure the agent can load on demand, reusable across tools.

Configuration, transport, capability. Each layer chose the most boring possible container — a text file in a folder — because boring text is what survives a vendor change.

The same logic runs underneath your own knowledge. Plain Markdown you keep is already AI-ready; the format the tooling settled on is the format you have been using all along (see your notes are already AI-ready).

Frequently asked questions

What is a SKILL.md file?

A SKILL.md is a Markdown file that defines one agent skill. It opens with YAML front matter holding required metadata, at minimum a name and a description, followed by instructions written in ordinary Markdown that tell the agent how to perform a specific task ⁵. It is the agent's instruction sheet for one job, kept in plain text you can read.

Where does a SKILL.md file actually live?

A skill is a folder, and the SKILL.md sits inside it. In Claude Code, personal skills live under ~/.claude/skills/<name>/SKILL.md and project skills under .claude/skills/<name>/SKILL.md. OpenAI's Codex reads them from a .agents/skills directory ¹¹. The location varies by tool; the shape, a named folder with a Markdown file in it, does not.

Do I need to know how to code to make a skill?

No. The required core of a skill is one Markdown file with a short front-matter header and plain-language instructions ⁶. A skill can bundle scripts for heavier tasks, but the format itself is writing, not programming. If you can write a clear how-to in a text editor, you can author a skill.

How is a Skill different from an MCP server or AGENTS.md?

They occupy different layers. AGENTS.md is project configuration, one file telling an agent how a specific project works. MCP is a wire protocol, the transport an agent uses to reach tools and files. A Skill is a portable capability, a folder of Markdown packaging one reusable procedure ¹⁰. Configuration, transport, capability.

Is SKILL.md an open standard?

Yes. The format originated at Anthropic and is published as an open standard, with the specification hosted at agentskills.io ⁶. It is implemented across multiple independent tools, including Claude Code ¹⁰, OpenAI Codex ¹¹, and Microsoft's VS Code, which documents it as "an open standard that enables portability across different AI agents" ¹².

Are skills small?

Mostly, yes. In the Bosch and CMU analysis of 40,285 published skills, "the median skill contains 1,414 tokens (mean: 1,895)" and "90% of skills are no longer than 3,935 tokens" ⁷. A typical skill is a page or two of prose, not a large codebase. Short, readable Markdown by design.

The most durable thing about the agent boom is also the least exotic: a folder of plain Markdown you can read, own, and carry anywhere. That is the format the agents converged on, and it is the format your own notes already live in, kept on your own device in MNMNOTE, where the file outlasts the tool.