What agents actually read
before they touch your system.
Which files land in the context window, in what order, and what each one costs you per turn. Then 9 templates you can fill in and ship.
- 8
- instruction formats tracked
- 1.3M
- public repos carrying one
- 2 of 20
- design systems ship Code Connect
- 9
- templates in the pack, CC0
01 · The context window
Not everything you write gets read, and not everything read is free.
Agent context comes in tiers, and teams routinely put things in the wrong one. The top tier is loaded on every single turn of every session.
The middle tiers are the ones most teams under-use. A skill body, a path-scoped rule, an MCP call: indexed cheaply, expanded only when relevant.
Carbon writes down its own token budget
AGENTS.md · CLAUDE.mdLoaded on every turn of every session. A 3,500-word file is 3,500 words you pay for when someone asks to rename a variable.
SKILL.md · paths: · applyToIndexed cheaply, expanded only when relevant. This is the tier most teams under-use.
MCP tool callQueried during the session, so it cannot go stale between releases. Bounded cost per call.
llms.txt · DESIGN.mdNothing fetches these on its own. They work when you point an agent at them directly.
Cost rises with how often a tier is loaded, not with how much it contains. The cheapest place to put a 2,000-line component catalogue is the tier that only opens it when a component is actually being written.
02 · The landscape
8 formats, 2 of which are actually specified.
They are usually discussed as if interchangeable. They differ in who governs them, how multiple files combine, whether they can be scoped, and how strictly they are defined. Counts are GitHub code-search estimates taken on 2026-08-26 — order-of-magnitude figures for comparing formats, not exact totals.
Public repos carrying each format · thousands
The narrative that AGENTS.md has displaced CLAUDE.md is not supported by file counts — CLAUDE.md is ahead. And llms.txt, the format that gets written about most, is an order of magnitude behind every instruction file here.
| File | Owner | Rigour | Multiple files | Scoping | Public repos |
|---|---|---|---|---|---|
| AGENTS.mdRepo root, plus nested copies in subdirectories | Agentic AI Foundation (Linux Foundation) | Naming convention | Nearest file wins | Directory nesting only | ~459,776 |
| CLAUDE.mdRepo root or .claude/, plus user and managed-policy levels | Anthropic | Vendor convention | All of them, concatenated | .claude/rules/ with paths: frontmatter globs | ~534,528 |
| .cursor/rules/*.mdc.cursor/rules/, nestable; ~/.cursor/rules for personal rules | Cursor | Vendor convention | Nearest file wins | globs, plus description for model-decided loading | ~92,928 |
| .github/copilot-instructions.md.github/ | GitHub | Vendor convention | All of them, concatenated | None at this level — the file is repo-wide | ~147,456 |
| .github/instructions/*.instructions.md.github/instructions/ | GitHub | Vendor convention | All of them, concatenated | applyTo glob in YAML frontmatter | ~67,072 |
| SKILL.md.claude/skills/<name>/, .github/skills/<name>/, .agents/skills/<name>/ | Agent Skills open standard | Published spec | Loaded only when needed | Matched on description; Claude adds path scoping | — |
| llms.txtSite root, or any documentation subpath | Answer.AI (Jeremy Howard) | Proposal | Most specific path wins | More specific paths take precedence | ~19,456 |
| DESIGN.mdRepo root | Google Labs | Published spec | Most specific path wins | None | — |
The thing people get wrong about each one
Cross-vendor, governed since December 2025
It has governance but almost no specification — no required fields, no schema, no frontmatter, no conformance test. Its own FAQ says to use any headings you like. Two of the tools listed as compatible, Aider and Gemini CLI, do not read it until you configure them to.
Single-vendor, the best-documented behaviour of any format here
Files do not override each other, they stack. A package-level rule that overrides a root rule works under AGENTS.md semantics and silently does not here — both end up in context, and the docs warn that Claude may pick between contradictions arbitrarily.
Widely adopted, proprietary, direction unclear
The four rule types are not declared, they emerge from which of the three frontmatter fields you set. A plain .md file in that folder has no frontmatter and is reportedly ignored entirely. Real repos ship auto-attached rules with an empty description, which quietly disables model-requested loading.
Stable, and the most structured of the instruction formats
Copilot also reads CLAUDE.md natively and looks for skills in .claude/skills/. The interop runs one way: Copilot reads Anthropic's files, Anthropic does not read the neutral one.
Stable on VS Code and the cloud agent; thinner elsewhere
When several files match, all of them apply and no specific order is guaranteed. Do not write rules that depend on one file being read after another.
Cross-vendor spec, adopted fast through 2026
Only six frontmatter fields are portable — name, description, license, compatibility, metadata, allowed-tools. Everything else is a vendor extension and hard-fails on upload elsewhere. The payoff is progressive disclosure: only the name and description sit in context until the skill is actually used.
A proposal, revised August 2026; not adopted by the crawlers it targets
Nobody crawls it. Google has compared it to the keywords meta tag, and server logs show AI crawlers do not request it. It still works for the thing it is actually good at: being an index you hand an agent. Anthropic publishes one for its own docs and links it from every page.
Apache-2.0, alpha, under active development
The only format here with a typed schema and a real linter — designmd lint, diff and export, including export to W3C DTCG. It is also the most expensive way to give an agent context: measured alone it cost about 92% more tokens with roughly 2.7x the run-to-run variance.
03 · Real examples
What nine major design systems actually ship.
Every cell below was checked against the repo on 2026-08-26, not inferred from a blog post. A tilde means the file exists but only points at another one — which, for CLAUDE.md, usually means it does not work.
| Design system | AGENTS.md | CLAUDE.md | .cursor/rules | Copilot | Skills | MCP |
|---|---|---|---|---|---|---|
| GitHub Primerprimer/react | not shipped | not shipped | not shipped | ships | ships | ships |
| IBM Carboncarbon-design-system/carbon | ships | not shipped | not shipped | not shipped | ships | ships |
| shadcn/uishadcn-ui/ui | ~stub only | not shipped | not shipped | not shipped | ships | ships |
| Ant Designant-design/ant-design | ships | not shipped | not shipped | ships | ships | ships |
| Adobe React Spectrumadobe/react-spectrum | ships | ~stub only | not shipped | not shipped | ships | not shipped |
| MUImui/material-ui | ships | ~stub only | not shipped | not shipped | not shipped | not shipped |
| Ark UIchakra-ui/ark | not shipped | ships | ships | not shipped | not shipped | not shipped |
| Radix Primitivesradix-ui/primitives | ships | not shipped | not shipped | not shipped | not shipped | not shipped |
| Chakra UIchakra-ui/chakra-ui | not shipped | ships | not shipped | not shipped | not shipped | ships |
| Ships it, of 9 | 5 | 2 | 1 | 2 | 5 | 5 |
GitHub Primer
The most complete stack anywhere: 14 skills, an MCP server, and path-scoped Copilot instructions that cross-reference the skills by filename. They decomposed their own architecture doctrine into on-demand skills, including an explicit accessibility contract.
IBM Carbon
Opens its AGENTS.md with a note to itself — “This file should be as short as possible. More tokens used.” — then routes everything substantial to docs and ADRs. One of only two systems here shipping real Code Connect mappings.
shadcn/ui
Ships the skill with an evals/ directory that regression-tests its own rules — almost nobody else tests their agent instructions. Its registry MCP is zero-config, and registry authors can supply error messages written for LLMs.
Ant Design
The honest counterexample to “keep it short”: ~3,500 words, bilingual, covering 84+ components. Its Copilot instructions carry an export allow-list specifically so models stop inventing Box, Stack and Container.
Adobe React Spectrum
AGENTS.md describes the stack bottom-up and delegates depth to five contributing guides. Its CLAUDE.md is the pointer-stub bug: a markdown link where an @-import was needed.
MUI
Same pointer-stub bug as Spectrum. Four lines of prose where one character would have imported the real instructions.
2 / 20
ship Figma Code Connect
Carbon has roughly 86 mapping files and Primer 52. Everyone else writes the Figma-to-code mapping down in prose and hopes. This is the widest gap between how the category talks and what it has built, and it is the signal this site's own Index is weakest at scoring. Source
04 · Three traps
All three are shipping right now, in systems you have heard of.
01
Claude Code does not read AGENTS.md.
This is the most common wrong assumption in the category. Anthropic's memory documentation says so in as many words, and a search for the filename across all 376 published Claude Code releases returns nothing. If your instructions live in AGENTS.md and you have not bridged the gap, Claude Code is working without them.
FixAdd a CLAUDE.md whose first line is a bare @AGENTS.md import.
02
A markdown link is not an import.
MUI and Adobe React Spectrum both had the right instinct — keep AGENTS.md as the source of truth, reduce CLAUDE.md to a pointer. Both point with a markdown link. That is inert text. Only the bare @ form expands the file into context at launch, so as written, Claude Code loads four lines of prose and has to decide to go and read the real thing.
FixOne character: the @ instead of the brackets.
03
Your stale docs are the hallucination.
Meta's Astryx documented a component under a name its package does not export. The agents read the README, used the name, and produced a build failure. Nobody hallucinated anything — the model faithfully reproduced the documentation. The same night's run also caught a prop-signature mismatch and a colors-for-color slip.
FixA CI check asserting every symbol named in your agent files is actually exported.
Trap 02, as it appears on disk
Both files below are complete and valid markdown. Only one of them puts your instructions in front of the agent.
# CLAUDE.md See [AGENTS.md](./AGENTS.md) for codebase documentation.
A markdown link is text. Claude Code loads these four lines and nothing else, then has to decide for itself to go and read the real file. This is what MUI and Adobe React Spectrum ship today.
# CLAUDE.md @AGENTS.md
The bare @ form expands the file into context before the first turn. Imports resolve up to four hops deep. Backticks around it would keep it literal, so do not quote it.
The composition difference above is the one that bites monorepos. Under AGENTS.md the closest file wins, so a package-level file genuinely overrides the root. Under CLAUDE.md there is no overriding at all: every discovered file is concatenated, and Anthropic's own docs warn that when two rules contradict, Claude may pick one arbitrarily. Teams rename the file and assume the semantics came along. They did not.
05 · Does any of this work?
Meta built the most instrumented agent-ready design system in existence, and it is losing to shadcn/ui.
Astryx runs a nightly benchmark against a plain baseline — same prompts, a fresh sub-agent per target with no prior context, the expected component list withheld so there is no answer leakage. Results are published as a GitHub issue every night, wins and losses alike. The baseline wins most nights.
87
Astryx overall score
vs 94 for the plain baseline
95%
compliance, registry context
vs 84% for injected style guides
1.8
a11y failures per generated UI
all of them pass axe-core
25–38%
deprecated-API usage rate
structural, not a model defect
That does not mean machine interfaces are worthless. It means the honest version of this subject has error bars, and almost nobody else is publishing theirs. The nightly issue
Everything this page asserts, with its source
This subject is unusually prone to confident nonsense, so each claim carries how it was established. Where we could not open a source from our own network it says “relayed”, and you should treat the exact figure as unverified.
Meta's agent-ready design system loses to a plain shadcn/ui baseline on Meta's own nightly benchmark
Baseline 8 wins vs Astryx 2, on the night of 2026-06-24
The most important number in this whole subject, and it is a negative result published voluntarily. Astryx is React 19 + StyleX, refined for eight years across roughly 13,000 internal apps, and it ships a CLI, an MCP server and generated agent files. It still scores 87 overall against the baseline's 94. Every vendor claim that a machine interface fixes agent output has to survive this datapoint, and most are not tested nearly as honestly.
Stale documentation is an active hallucination source, not a passive one
XDSTheme not exported from @astryxdesign/core/theme
The agents did not invent this name. They read it in the README, which documented a component under a name the package does not export. The maintainers say so in their own write-up. The same run shows a prop-signature mismatch and a colors/color slip. This reframes the problem: your agent files are not just failing to help, they can be the defect.
Shipping runnable component source beats describing components in context
95% compliance (registry) vs 84% (context-injected style guides)
Three strategies across six real-world UIs. Instruction-based — the whole style guide in the system prompt — came last, which is precisely what most teams do first. Context-based was fastest at 5.5 minutes but 11 points less compliant. We could not open the paper from this network, so treat the exact percentages as reported rather than verified.
Semantic accessibility failures in generated UIs are invisible to existing linters
541 issues across 300 generated interfaces — about 1.8 per UI
Generic button labels 27%, vague link text 26%, poor alt text 20%, ARIA 14%, generic form labels 12%. Every one of these passes axe-core, because they are semantic rather than structural. A green accessibility check on agent-generated UI is currently close to meaningless.
Shipping a machine interface is now table stakes among maintained design systems
17 of 20 surveyed systems ship an official MCP server
Open data, link-verified per claim, MIT/CC BY 4.0 — the only real census of this space. The three without one are Cloudscape, Nord and USWDS, and Cloudscape compensates with a docs pipeline that regenerates llms.txt daily. The argument has moved on from whether to ship a machine interface to how to keep it from rotting.
Design-to-code grounding is claimed far more often than it is shipped
2 of 20 surveyed systems actually ship Figma Code Connect
Carbon has roughly 86 mapping files and Primer 52. Everyone else writes the Figma-to-code mapping down in prose and hopes. This is the widest gap between how the category talks and what it has built, and it is the signal this site's own Index is weakest at scoring.
A well-routed MCP server measurably beats no machine interface
−11% errors, 34% faster, −16% tokens, −26% tool calls
Published by the team that built the thing, measured on their own system, and we could not open the page from this network. The direction is consistent with the CHI result and with the census; the magnitudes are marketing until someone reproduces them. The accuracy gain they report is +4.9%, which is notably smaller than the efficiency gains.
Portable context is not just costlier than a tool call — it is less predictable
About +92% tokens and roughly 2.7x the run-to-run variance
The variance figure is the one nobody else reports and the one that should shape policy: a file you paste into context makes cost unpredictable, where a tool call makes it bounded. Their conclusion — ship the portable file for reach, route real work through the server — is the only published cost-based routing policy we found.
Claude Code does not read AGENTS.md
Zero references across 376 releases of the changelog
The docs state it outright. We checked it the other way too: a case-insensitive search for agents.md across the full published changelog returns nothing. This is the single most common wrong assumption about the format landscape, and it is why the pack below ships a CLAUDE.md that imports rather than a CLAUDE.md that duplicates.
Two major design systems ship a CLAUDE.md that does not do what they intend
A markdown link where an @-import was needed
Both keep AGENTS.md as the source of truth and reduce CLAUDE.md to a pointer — correct instinct. But both point with [AGENTS.md](./AGENTS.md). A markdown link is inert text; only the bare @AGENTS.md form expands the file into context at launch. As written, Claude Code loads four lines of prose and has to decide to go and read the real file. One character fixes it.
Agents reach for deprecated APIs at a structural rate
25–38% deprecated-usage prediction across seven evaluated models
The mechanism is not a model defect. Old code outnumbers new code in nearly every repository, so the first plausible match is usually the deprecated one. That makes it a retrieval problem: the fix is a machine-readable deprecated flag with a replacement pointer, not another line of prose asking nicely.
Teams want agent-delivered documentation far more than they have it
12% doing it, 57% wish they were
A 45-point gap between want and have, and the largest single appetite signal in the category. The same survey finds teams want AI kept away from design generation. Self-reported, vendor-run, and blocked from this network — read it as appetite, not measurement.
06 · The pack
9 files, filled in with the patterns above.
Templates, not examples — angle-bracket placeholders where your system goes, and inline comments explaining why each section is shaped the way it is. The CLAUDE.md imports rather than duplicates. The Cursor rule says which of the four activation modes it uses and why. The skill uses only the six portable frontmatter fields.
CC0 · no email · unpacks straight into a repo root
- AGENTS.md
The source of truth. Every other file in the pack points here rather than restating it.
AGENTS.md - CLAUDE.md
Imports AGENTS.md with @, because Claude Code does not read that file on its own.
CLAUDE.md - .cursor/rules/design-system.mdc
Always-applied Cursor rule with the non-negotiables, and a glob-scoped companion pattern.
design-system.mdc - .github/copilot-instructions.md
Repo-wide Copilot instructions, written to survive being concatenated in an unknown order.
copilot-instructions.md - .github/instructions/components.instructions.md
Path-scoped component rules with an applyTo glob, so they load only when relevant.
components.instructions.md - .claude/skills/design-system/SKILL.md
Portable six-field frontmatter only. The long reference material that costs nothing until used.
SKILL.md - public/llms.txt
An index to hand an agent, not a crawler signal. Structured per the proposal.
llms.txt - DESIGN.md
Portable visual context with typed frontmatter, for tools that have no access to your repo.
DESIGN.md - docs/agent-files-README.md
What each file is, what reads it, and the order to fill them in.
README.md
Fill them in this order
- 01
AGENTS.md first
widest reachThe source of truth, and the file the most tools read. Everything else points at it rather than restating it — duplicated instructions drift apart, and then the agent has two contradictory sources and no way to arbitrate.
- 02
CLAUDE.md second
four linesOne of them load-bearing. A bare @AGENTS.md import, not a markdown link.
- 03
Name the hallucination
the highest-leverage editNot “follow our conventions”. Ant Design ships an export allow-list specifically so models stop inventing Box, Stack and Container. A prohibition that names the mistake is something a model can pattern-match against.
- 04
Then move things out
past ~200 linesLong reference material belongs in a skill; file-specific rules belong in path-scoped rules. Both are free until used, where AGENTS.md is billed on every turn.
- 05
Then generate rather than maintain
the only durable fixMantine, Cloudscape, HeroUI and Astryx all regenerate agent-facing docs from source. Hand-written agent docs rot, and a rotted file is not neutral — it is an instruction to use an API that no longer exists.
Write one file well
Before you write eight badly. An unmaintained instruction file is worse than a missing one: it is a confident, wrong answer that the agent has no reason to doubt. Only ship the files for tools your team actually uses.
The pack is CC0. No attribution, no email, no gate.