Written guidance for agents: AGENTS.md and rules files

Docs describe each part of a design system. Guidance decides between them. It says that actions are buttons and navigation is links, that a raw color is never acceptable, that the checker runs before the agent says it is done. Public systems already write this way. Atlassian’s full-text docs tell agents to use only the design tokens listed in them. GitHub Primer ships a guide written for language models inside its package, with rules such as never using raw values. A system without guidance hands an agent the parts and leaves the choices to chance.

• AGENTS.md is an open format, “a README for agents”, in a predictable place at the root of a repository. Its site counts over 60,000 open-source projects using it, and many agents read it, Cursor among them.
• CLAUDE.md is what Claude Code reads at the start of every session. Without one, Claude Code reads the repository’s AGENTS.md instead.
• Cursor rules are .mdc files in .cursor/rules, placed at the start of the model’s context whenever they apply.
• Skills are installable bundles of instructions. shadcn/ui, Chakra UI, Ant Design, Adobe Spectrum and IBM Carbon each publish their own.
• A docs section on AI, such as Atlassian’s “With AI”, Ant Design’s “For Agents” or React Spectrum’s “Working with AI”, holds the same guidance for agents that fetch docs.

The ranking gives 2 Guidance points only to instructions for people building products with the system. Microsoft Fluent 2’s AGENTS.md is about working on Fluent’s own code: its build tools, its versioning and its change files. It helps a contributor and tells a product team’s agent little, so Fluent earns 1 point. Salesforce’s official starter kit has an AGENTS.md aimed at building UI with SLDS, which counts in full. Before you write yours, decide who will read it.

Keep it to the rules an agent would otherwise get wrong. A first version can be this short:

# Building with the Example Design System

## Before you start
- Load the design tokens from tokens/example.tokens.json. Never write a raw color, size or font.
- Look up the component in components.json before you build anything. If it exists, use it.

## Choices
- Actions are Button. Navigation is Link.
- One primary Button per view.
- Forms use Field, so every input has a label and an error message.

## Never
- No new components without asking.
- No inline styles.

## Before you finish
- Run the checker with --json and fix every finding it lists.

Cursor places its rules at the start of the model’s context, and Claude Code reads CLAUDE.md at the start of every session, so every line competes with the task for room. Point to the docs for detail, and keep the file to choices and limits. Write each rule so something could test it, then test it with a set of prompts that measures the agent and acceptance checks on its output. The best AI-ready design systems, ranked shows who already publishes guidance and for whom; Work with Simbolik (opens in a new tab) when your own brand’s rules need writing down.