Written guidance for agents: AGENTS.md, rules files and skills

The AGENTS.md is the most common mix-up in this part of the comparison. Plenty of design system repositories hold one, and most of them are written for contributors. They say how to run the build or write a change file, which is useful to someone fixing the design system and useless to someone building a product with it. Microsoft Fluent’s is that kind, so Fluent rates Partly on guidance. IBM Carbon’s repository AGENTS.md is for contributors too; Carbon’s Yes rests on the carbon-builder skill its MCP setup page installs.

When you judge a system, or write guidance for your own, ask one question: does this tell an agent how to build a product with the system?

• An AGENTS.md in the repository, in standard Markdown, with no required fields. In a repository with several packages, each package can have its own, and the nearest one to the code wins.
• Skills, packaged instructions an agent installs. Ant Design, Chakra UI, shadcn/ui, Adobe React Spectrum and IBM Carbon publish them.
• A ready prompt. Ant Design’s For Agents page gives one to paste, which warns the agent that its training data may be out of date and tells it what to read first.
• Guides shipped in the package. GitHub Primer ships a design tokens guide written for language models inside @primer/primitives, with rules such as never using raw values.

Short, firm and checkable. A skeleton to start from:

# Building UI with [design system]

## Always
- Use components from [package]. Look up a component's props before using it.
- Take every color, space, size and font from a design token.

## Never
- Two primary buttons on one screen: it marks the one action that matters.
- A component rebuilt by hand when the system has one.

## Before you hand work back
- Run [the checker] and fix every finding.
- Name any component you needed and could not find, instead of inventing one.

Two habits make it work. Write each rule so a check can catch it breaking; a rule nobody can test is a wish. And keep the reason beside the rule, as the primary button line does. An agent that knows why a rule exists can handle the case it did not name.

The three parts do different jobs. Docs say what each part is; a design system MCP server answers questions while the agent works; guidance says how to work. An agent with docs and no guidance knows the parts and still improvises the page. Writing that guidance from a brand’s own taste, and the checks that hold it, is the core of Work with Simbolik (opens in a new tab).