The AGENTS.md format

The format has no required fields: it is plain Markdown, with whatever headings help. Its site suggests the things a newcomer would need and a README would not hold: an overview, the build and test commands, code style, how to test, security notes, and the rules for commits and pull requests. In a repository with several projects, each can have its own file; an agent reads the nearest one, and the closest takes precedence. Codex, Jules, Aider, Cursor, GitHub Copilot and Gemini CLI are among the agents its site lists.

AGENTS.md shows up in the Guidance column, and there it is often aimed at a reader the ranking does not count. Across the 12:

• Written for teams building with the system: Salesforce Lightning’s starter kits carry an AGENTS.md about building interfaces with SLDS, which helps earn its 2 points. Atlassian gives a snippet to paste into your own.
• Written for contributors only: IBM Carbon, Ant Design, Adobe Spectrum 2, GitHub Primer and Microsoft Fluent 2 have repository files about working on the system itself. The first 4 earn their Guidance points elsewhere, through skills or docs pages; Fluent has nothing else, so it gets 1 point.
• None found: Google Material 3, GOV.UK and the root of shadcn/ui’s repository.

Write it for the person, or agent, building a product with your system. Say which package to import, which components come first, that design tokens come before raw values, which addresses hold the docs and the llms.txt, how to run your checks, and what never to do. Keep it short enough to read whole on every task. Written guidance for agents covers the content in depth.

• It is advice, not a check. An agent reads the file; nothing makes it obey. Pair it with checks on the output, as checking an agent’s output describes.
• Contributors and users need different files. Keep the rules for working on the system apart from the rules for building with it.

The best AI-ready design systems, ranked show which systems earn their Guidance points, and how.