Why SKILL.md Became the Portable Primitive Across 20+ Agents

Every format war in software has the same shape: a technically superior option loses to a boring, legible one that's easier to adopt. XML lost to JSON. SOAP lost to REST. And in the emerging skill economy, elaborate schema-driven skill definitions lost to something almost embarrassingly simple — a markdown file with optional scripts attached, named SKILL.md.

That's not an accident of laziness. It's the result of a format having to satisfy two audiences at once that usually pull in opposite directions: the model reading it, and the human writing it. Most technical formats optimize for one or the other. SKILL.md is one of the rare cases where optimizing for readability turned out to also optimize for machine consumption, because the machine reading it is a language model — and language models are, by construction, extremely good at reading prose.

The Format War That Didn't Happen

In 2024 and early 2025, it would have been reasonable to bet that skill definitions would converge on something more structured — a JSON schema, a YAML DSL, something with strict typing and validation, the way API contracts converged on OpenAPI. That's how software categories usually mature: informal conventions get formalized into schemas once enough people are relying on them.

Instead, the opposite happened. The format that won is the one a human can open in a text editor, read top to bottom, and understand without documentation — a title, a description of when to use it, step-by-step guidance, and optionally, scripts the agent can execute along the way. No required schema validation, no build step, no compiler. If you can write a README, you can write a skill.

This matters more than it sounds like it should, because the alternative — a rigid schema — creates a barrier that's invisible to the format's designers and enormous to everyone else. A schema needs tooling. Tooling needs maintenance. Maintenance needs a maintainer with opinions about breaking changes. Every one of those steps filters out contributors. Markdown filters out nobody.

Plain Text Is a Model's Native Language

The deeper reason SKILL.md won is that a large language model doesn't need structured data to act reliably on instructions — it needs clear, well-organized natural language, which is exactly what markdown is designed to produce. A JSON schema has to be parsed, validated, and mapped onto behavior through a rigid interpreter layer that someone has to build and maintain per agent. A markdown file with headers and a numbered procedure can be read directly by the model doing the work, the same way it reads any other document in its context.

This inverts the usual software intuition that structured data is more "reliable" than prose. For deterministic systems, that's true — a config file with a typo fails loudly, while a paragraph with an ambiguous sentence fails silently. But a model reading SKILL.md isn't a deterministic parser; it's a reasoning system that tolerates ambiguity the way a human collaborator would, by inferring intent from context. The format that plays to that strength wins over the format that assumes the reader is a compiler.

The optional scripts are the pragmatic exception, and they prove the same point from the other direction: for the parts of a skill that genuinely need determinism — running a specific command, calling a specific API, transforming a specific file format — you don't ask the model to improvise, you hand it an actual script. SKILL.md's real design insight is knowing which parts of a task should be prose and which parts should be code, and not forcing either one to do the other's job.

Portability Followed Simplicity, Not the Other Way Around

By 2026, skills built to the SKILL.md convention run across more than 20 different agents and tools — Claude Code, Cursor, Codex CLI, Gemini CLI, GitHub Copilot, and OpenClaw among them. That cross-compatibility is usually described as the headline achievement, but it's really a downstream consequence of the format's simplicity, not a separate feat of engineering. A markdown file with a description and a procedure doesn't require an adapter to be useful to a new agent — the new agent just has to be able to read text and follow instructions, which is table stakes for anything calling itself an AI coding agent in 2026.

Contrast this with what portability would have required under a schema-first approach: every agent vendor would need to implement a parser for that specific schema, keep it in sync with schema version bumps, and handle the inevitable divergence where each vendor's parser interprets edge cases slightly differently. That's the exact fragmentation that killed early attempts at "universal" plugin formats in other software categories — everyone claims compatibility, but the fine print differs enough that nothing actually is compatible.

SKILL.md sidesteps that failure mode almost entirely, because there's very little to diverge on. A markdown parser is a solved problem that predates the entire AI agent category by decades. The interesting behavior — how well the agent follows the instructions — lives in the model, not in the parsing layer, so it doesn't fragment the same way schema interpretation does.

The Cost of Winning on Simplicity

None of this is free. A format with no required schema and no validation step also has no gatekeeping — nothing stops a badly written skill from shipping, nothing forces a skill to declare what permissions or side effects it needs before an agent runs its scripts, and nothing structurally prevents a skill from claiming to do one thing while its attached script does another. That gap is exactly why trust and verification, which we cover later in this series, is the unresolved problem sitting underneath the format's success. Portability solved the "will this work everywhere" question. It did nothing for the "should I run this" question, and those are different problems with different fixes.

There's also a subtler cost: because markdown imposes so little structure, skill quality varies enormously in ways a stricter format would have flattened out. Two skills that both claim to help with the same task can differ wildly in how carefully they've been written, how well they handle edge cases, and how honestly their description matches their behavior. That variance is a big part of why discovery — the subject of a later piece in this series — turns out to be harder than skill creation itself. Anyone can write a SKILL.md file in twenty minutes. Writing one that a stranger's agent can trust and reuse reliably takes considerably longer, and the format itself gives you no signal, at a glance, about which kind you're looking at.

Still, weighed against the alternative — a category-wide standard splintered across a dozen incompatible schemas, the way the early web splintered across browser-specific markup — SKILL.md's bet on plain text and portability over structure and validation looks like it made the right trade. It optimized for the one thing that determines whether a format actually gets adopted: how little a stranger has to learn before their first contribution works.

Part of the "The Skill Economy" series on aiskill.market.