The Language Nobody Planned Is the Language Everything Is Becoming

Markdown was supposed to be a shortcut to HTML. It turned into the file format we use to talk to machines.

This post is a Markdown file. So is the file that tells my coding agent what it’s allowed to touch. Ten years ago those two things had nothing to do with each other. Now they’re the same file type, and that’s the whole post.

I’m typing this in a text editor. No compiler, no runtime, no package manager, no build step. The format is older than most of the tools that depend on it. And the file is still, in a real sense, a program. It’s instructions. Not for a browser — for a reader, and more and more, for a machine that reads like one. That used to be a meaningful distinction. It gets less meaningful every month.

Markdown didn’t beat anything. It just never broke, so nobody had a reason to swap it out.

The HTML That Ate Its Own Children#

Nobody writes HTML by hand anymore. Instead we spent fifteen years inventing new ways to not write it, and every one of them had to be learned from scratch.

Ruby on Rails peaked around 2011 and 2012, and suddenly everyone was re-learning HTML because of HAML. HAML was HTML with the HTML removed, which sounded like a joke and was not one. Then the Node world gave us Jade, which became Pug — a genuinely excellent rename, and as someone who owns two pugs, I consider this one of the few unambiguously correct decisions in our industry’s history. Then JSX, which I maintain is a client-side PHP wrapper in disguise, the angle brackets wearing a fake mustache. Then HTMX, which looked at the whole churn and said: what if the HTML just… stayed, and we added a few attributes.

If you want the body count, the awesome-template-engine list on GitHub has it — Mustache, Handlebars, EJS, Nunjucks, Liquid, Marko, doT, Eta, and their cousins in every language that ever rendered a page. Dozens of engines. Hundreds if you count the dead ones. EJS still pulls around 25 million weekly downloads, Handlebars 12 million, Pug 6 million.¹ They keep shipping. The churn keeps churning.

Every one of these was a bet that HTML gets easier if you turn it into something else. Every something else had to be learned, forgotten, and re-learned. The template engine is the only software category where the documentation is a memoir.

Markdown was never in this fight. It never tried to make HTML easier to write. It tried to make writing easier to write. Different problem, which is why it’s still here and the engines are a list.

The Format That Agents Chose#

Then LLMs showed up and needed a config file. Not a prompt — a standing set of rules: here’s how the repo builds, here’s what you can touch, here’s how we run tests, here’s the weird thing we do on purpose.

That file was Markdown.

Nobody held a meeting about it. Every repo already had a README, every model had eaten a few billion of them in training, and a .md file needs zero tooling to read — no schema, no parser package, no version pin. When you need something a human will maintain and a machine will consume, Markdown is the only option that has never once asked you to install anything. So it was Markdown by default.

The facts, flat: AGENTS.md — a Markdown file at the repo root that tells coding agents how to build, test, and behave — is now a Linux Foundation project under the Agentic AI Foundation, with reports of 60,000-plus open-source repos using it and thirty-plus agents reading it.² Claude Code reads CLAUDE.md. Cursor has rules files. Copilot has copilot-instructions.md. Four tools, four filenames, one format.

Then there’s SKILL.md: a Markdown file with a bit of YAML on top that describes something an agent can do on demand. A skill is a directory. The directory is a Markdown file and some scripts. The agent reads the frontmatter, decides whether it cares, loads the rest if it does.

So the hot new programming surface isn’t a language. It isn’t a framework with a logo. It’s a Markdown file with decent headings. Agent config is a document. Agent capability is a document. Nobody designed that. We backed into it, which is how most real standards get made.

A Skeptical Interruption#

Fair question: does any of this actually work?

Not clearly, yet. A 2026 study of repo-level context files found that LLM-generated ones made things worse — lower task success, more agent steps, inference costs up over twenty percent.³ Human-written files did better, but mostly by making agents more thorough, not more correct. More tests, more poking around, more steps.

So no, the file isn’t magic. A bad AGENTS.md is a bad doc with a fancier filename. Markdown didn’t solve what to tell the machine. It solved getting anything to the machine at all — cheap, portable, no ceremony.

That’s still a real win. The template engines never even did that. They just moved the problem to a new syntax every three years. Markdown moved it toward less. Less is the only direction that scales.

The Recursive Part#

I said this post is a Markdown file. At the top that was a fact about the medium. Now it’s a fact about the argument: a post about Markdown eating everything is itself Markdown eating something.

That’s happening everywhere. A SKILL.md describes a capability in the same format the capability’s docs use. An AGENTS.md is written in the same format as the README it’s half-replacing. The agent reads both in one pass because they’re the same kind of thing. “Docs for humans” and “instructions for machines” used to be two piles. They’re becoming one pile, and the pile is a format with no version number.

Here’s the actual inversion. HTML added marks to text so a machine could render it. Markdown went the other way — strip everything until the machine can just read what you typed. The angle brackets were always a translation layer. Markdown deleted it. The file I edit and the file the model reads are the same file. That has never been true before, in any stack, ever.

The template engines all tried to make the translation layer nicer. Markdown removed it. That’s why they’re a list on GitHub and it’s a foundation spec.

The Consequence#

The engineers who’ll do well with agents aren’t the ones who learn the most frameworks. They’re the ones who can write a clear README. The CLAUDE.md you maintain, the SKILL.md you write, the README you keep honest — those aren’t doc chores anymore. They’re config. They’re code, in the old sense: instructions something executes. The thing executing them just happens to read prose instead of syntax.

So stop treating .md files as the soft part of the repo. They’re turning into the hardest interface in the stack. A badly named function fails a test. A badly written AGENTS.md fails silently, in production, every session, and you pay for it in tokens and trust. The template-engine years taught us to obsess over how we generate HTML. The agent years will pay the people who obsess over what they write in plain text.

This post is a Markdown file. Your agent’s instructions are a Markdown file. That’s the whole argument.