AGENTS.md vs SKILL.md vs DESIGN.md
29 August 2026 · 5 min read
AGENTS.md, SKILL.md and DESIGN.md are not competitors. They are three layers of the same stack.
AGENTS.md is the project. SKILL.md is behaviour. DESIGN.md is appearance.
Most teams meet all three in one week and try to pick a winner. There is no winner. There is an order.
The table
| Format | What it governs | Who made it | Where it lives | What is required | When the agent loads it | Maturity |
|---|---|---|---|---|---|---|
| AGENTS.md | The project. How to build it, test it, run it, and what the conventions are. | Emerged across OpenAI Codex, Amp, Jules, Cursor and Factory. Now stewarded by the Agentic AI Foundation under the Linux Foundation. | Repo root. Monorepos may nest more, and the closest one takes precedence. | Nothing. Plain markdown, no schema, no required heading. | Every session. Always on. | Most mature. Emerged in 2025, used by over 60,000 projects, counted Aug 2026. |
| SKILL.md | Behaviour. One procedure, followed when a task matches it. | Anthropic. Released as an open standard, spec at agentskills.io. |
A directory named for the skill. Optional scripts/, references/ and assets/ sit beside it. |
name and description in frontmatter. Nothing else. |
On match. Name and description load at startup at roughly 100 tokens. The body, under 5000 tokens, loads only when the skill fires. | Stable spec with a validator. One field, allowed-tools, is still marked experimental. |
| DESIGN.md | Appearance. Tokens in the frontmatter, the reasoning in the body. | Google Labs. Built for the Stitch design tool, then open-sourced. | Not fixed by the spec. In practice, repo root or beside the SKILL.md it serves. | name, and a primary colour palette. The rest can be declared under omitted. |
Not defined. The spec sets no loading model of its own. | version: alpha. A draft, by its own header. |
The three questions
AGENTS.md answers one question. How does this repo work.
SKILL.md answers another. What should the agent do when this kind of task arrives.
DESIGN.md answers a third. What should it look like, and why that.
The questions do not overlap. That is why the files do not fight.
The order
If you only ever write one, write AGENTS.md.
Three reasons, heaviest first.
It costs nothing. No schema, no required field, no frontmatter, no validator. A heading and a build command is a valid AGENTS.md.
It is the layer the other two stand on. An agent that cannot run your tests cannot check the skill it followed. An agent that cannot run your build cannot apply your tokens.
It has the widest reader base by a distance. Over 60,000 open-source projects use it, counted August 2026, and every major coding agent reads it.
Write DESIGN.md last. Not because appearance matters least. Because the spec is alpha and the keys will move.
If you write two, pick the second by what you own. Own a design system, write DESIGN.md. Own a workflow, write SKILL.md.
The overlap
One caution earns its paragraph. AGENTS.md and SKILL.md both describe behaviour, and that is where teams duplicate themselves.
Put always-true rules in AGENTS.md. Put triggered procedures in SKILL.md.
If a rule applies only sometimes, it is a skill. If it applies every session, it belongs at the root.
DESIGN.md does not have this problem. Nothing else in the stack carries tokens.
The pairing
The clearest evidence that these layers are real is that people already ship them together.
github.com/bergside/awesome-design-skills holds 67 skills at 2.6k stars,
counted on 28 Aug 2026. Every entry is a folder with a SKILL.md and a companion
DESIGN.md. One file says what to do. The other says what it should look like.
Nobody argued the split into existence. The folder structure arrived at it on its own.
skill-kit works the same way at a different scale. 577 files across 9 categories, with the visual rules kept apart from the procedures that use them.
The prior art
I am not first to this split. Kento Ikeda published the same three-layer framing on dev.to and the AWS Builder Center.
He arrived at it from spec-driven development. I arrived at it from building a design knowledge graph. The split holds from both directions, which is a decent sign it is real.
Clearer and more current is the whole claim I am making here.
The honest part
Two of the dates I would like to hand you are not in the specs themselves.
The Agent Skills specification page carries no publication date of its own. Anthropic published the open standard on 18 December 2025. That date is corroborated across several reports, but the spec page does not carry it.
The DESIGN.md spec file states no release date and no licence. Google's own blog dates the open-sourcing to 21 April 2026, and the GitHub repository is labelled Apache-2.0. Both come from Google, not from the spec file.
I mark those rather than assert them. A spec that does not date itself is a fact about the spec. Worth knowing before you build on it.
DESIGN.md also says version: alpha in its own header. It is a draft and it
says so. Write one anyway. Expect to rewrite it.
Start here
Write AGENTS.md this week. It is an afternoon of work and it makes every agent in your repo less wrong.
Then read what a skill directory holds in what SKILL.md is. The frontmatter keys are in what DESIGN.md is.
The argument for treating all three as one system is in agent-ready design systems. The rest of what I have published on this sits on /work/.
Write the boring file first. The other two get easier.