# Agent files pack

From https://www.designsystems.one/ai-ready/agent-files

Nine templates for the files coding agents read before they touch your
design system. Every one is a template — fill the `<ANGLE BRACKETS>` and
delete what does not apply.

## Where each file goes

| File in this pack | Destination | Read by |
|---|---|---|
| `AGENTS.md` | `AGENTS.md` | Codex, Cursor, Copilot coding agent, VS Code, Zed, Devin, Windsurf, Jules, and ~15 more |
| `CLAUDE.md` | `CLAUDE.md` | Claude Code, and Copilot natively |
| `design-system.mdc` | `.cursor/rules/design-system.mdc` | Cursor |
| `copilot-instructions.md` | `.github/copilot-instructions.md` | GitHub Copilot |
| `components.instructions.md` | `.github/instructions/components.instructions.md` | Copilot in VS Code, Visual Studio, cloud agent |
| `SKILL.md` | `.claude/skills/design-system/SKILL.md` | Claude Code, Copilot, and the Agent Skills standard |
| `llms.txt` | `public/llms.txt` | Nothing automatically — hand it to an agent |
| `DESIGN.md` | `DESIGN.md` | Tools with no repo access; validated by the designmd CLI |
| `README.md` | `docs/agent-files-README.md` | You |

## Fill them in this order

1. **`AGENTS.md` first.** It is the source of truth and the widest-read file.
   Everything else in this pack points at it rather than restating it.
2. **`CLAUDE.md` second.** It is four lines, and one of them is load-bearing.
3. **The vendor files as needed.** Only ship the ones for tools your team
   actually uses. An unmaintained instruction file is worse than a missing
   one.
4. **`SKILL.md` when `AGENTS.md` gets long.** Anything over ~200 lines, or
   any multi-step procedure, should move here — a skill body costs nothing
   until it is used, where `AGENTS.md` is billed on every turn.
5. **`llms.txt` and `DESIGN.md` last.** These are for reach, not for your own
   team.

## Three things that are easy to get wrong

**Claude Code does not read `AGENTS.md`.** Anthropic's docs say so, and the
Claude Code changelog has never mentioned the file. The `CLAUDE.md` in this
pack bridges that with a bare `@AGENTS.md` import — and it has to be the bare
`@` form. A markdown link is inert text. MUI and Adobe React Spectrum both
ship this bug today.

**`AGENTS.md` and `CLAUDE.md` compose in opposite directions.** AGENTS.md is
nearest-file-wins. CLAUDE.md files are all concatenated, and Anthropic's docs
warn that Claude may pick arbitrarily between contradictions. A monorepo
built on package-level overrides works under one and silently does not under
the other.

**A stale file is an active hallucination source.** 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. Your docs were the
defect. If you take one process change from this pack, make it a CI check
asserting that every symbol named in your agent files is actually exported.

## Keeping them honest

Hand-written agent docs rot. The systems that have solved this generate them:
Mantine, Cloudscape, HeroUI and Astryx all regenerate agent-facing docs from
source. Treat these templates as the shape to generate into, not as files to
maintain by hand forever.

Licence: CC0. Use them however you like, no attribution needed.