AGENTS.md vs DESIGN.md vs SKILL.md: where your design rules go

One long rules file gets ignored. Three files with clear jobs get followed. That's the whole argument.

Your design rules are probably scattered right now: some in a Notion doc, some in a Figma component description, some in someone's head, and a few buried in a rules file so long that Cursor reads the first third and skips the rest. The fix isn't a better single file. It's sorting your rules into three files that each do one job.

This page is a sorting guide. For what DESIGN.md is as a format, read DESIGN.md explained. For installing and running design skills, read Claude Code design skills. For governance above tokens, read designgov.md.

The short version

Ownership is the differentiating column. AGENTS.md belongs to whoever sets the cross-team standards that apply on every task. DESIGN.md belongs to the person who can explain why the system is the way it is, not just what it is. Design skills belong to design.

If ownership isn't clear, the files drift. When files drift, agents build against stale rules, and you're debugging visual inconsistency instead of shipping.

The sorting test

Two questions. Apply them to any design rule.

Does every task need it? If a Cursor session for a data table, a login screen, and an error state all need the same instruction, it goes in AGENTS.md. If it only matters when you're doing a specific kind of work, it doesn't belong there.

Is it a value with a reason, or a procedure? A value with a reason is "primary buttons appear once per view, because visual hierarchy collapses when you have three competing calls to action." That belongs in DESIGN.md. A procedure is "when adding a new component, check the token list, name it in Figma, write the story, add it to the index." That becomes a SKILL.md.

The mistake I see most often: stuffing DESIGN.md rationale into AGENTS.md. The agent reads AGENTS.md on every task. If it's full of system reasoning the agent doesn't need right now, the actual constraints get buried.

Constant constraint: AGENTS.md. Visual value and its reason: DESIGN.md. Repeatable sequence of steps: SKILL.md.

Sorting real design rules

Here are twelve real rules and where each one belongs.

The governance row matters. Some decisions don't belong in any of the three files. They belong in a process document. Don't let the three-file pattern absorb everything.

For component contracts once values exist, component specs for AI is the right depth. When you need to read a live system back out of code, that's reverse-specs.

How the files point at each other

One source of truth. AGENTS.md holds the constants and points to DESIGN.md for the system behind them. Skills read DESIGN.md directly. They never copy values out of it.

A working file tree looks like this:

AGENTS.md
DESIGN.md
skills/
  add-component.md
  visual-review.md
  empty-states-check.md

AGENTS.md says: for all UI work, read DESIGN.md. Each SKILL.md says: values come from DESIGN.md, not from me. No value lives in two places. When DESIGN.md changes, everything that references it picks up the update.

CLAUDE.md and other tool-specific files stay thin. They hold tool-specific configuration and defer to AGENTS.md for design rules. If a rule matters, it lives in AGENTS.md, not scattered across four different tool config files.

For the skill packaging story in the article series, see Claude Code design-system skill. The full series hub is AI-ready design systems.

What the files can't hold

Judgment. That's the gap.

The three files codify what the system is. They can't codify why a particular shade of blue felt right for this product at this stage, or when it's correct to break the spacing grid for a specific layout problem. That judgment lives in DESIGN.md prose, in full sentences, not bullet lists.

Write the reason next to the rule. "We use 8px as the base spacing unit because our components compress poorly at 4px and our layout grid is built on multiples of 8. Don't go below 8px except for internal component padding." That's usable. "Spacing: 8px grid" is not.

The judgment that doesn't fit in prose is taste. I've seen teams write excellent DESIGN.md files that still produce incoherent UI because the agent has no feel for proportion, no sense of when a component is too heavy for its context. That's what Taste Profile addresses. It's how we package a team's accumulated design judgment into a form agents can reference when making visual calls the written rules don't fully cover.

If you want to go deeper on building that layer, see DESIGN.md explained and AI UI brand governance.

Keeping the three files true

Each file needs one owner. One person who merges changes to it and reviews PRs that touch it. Without that, the files drift and agents build against stale rules.

Changes come in via pull request with a preview. If you change the primary color token in DESIGN.md, that PR should include a visual preview. If code and DESIGN.md disagree, fix one in the same PR. Don't let the gap stand. A rule that's wrong in DESIGN.md costs every agent task that runs until it's corrected.

I'd treat these files the same way I treat a component library. They're not documentation. They're active design infrastructure.

For more on reconciling drift between design and code, read when the design system and the code disagree. For approvals and governance above the token list, use designgov.md.

How we run it

We publish an agent guide at /AGENTS.md so visiting agents can load it over HTTP. The open design-system-scaffold skill is a SKILL.md that sets up an AI-ready design system in a repo. It's listed in /.well-known/agent-skills/index.json.

If you want to see what a production design skill looks like in practice, read Claude Code design skills. The website repo keeps a small machine-added block in AGENTS.md for the framework; the published guide is what we point agents at for how we work.

When to do it yourself vs bring in a partner

Do it yourself if you have one product and a clear system. If you can answer "what's the type scale, why, and how should it apply to this component" without looking it up, you can write the files.

Bring in a partner when the system is unclear, when you have several products that need to share rules, or when agent output keeps diverging in ways you can't pin down. When the scope is a full AI-ready system across engineering and design, that's design systems for AI teams.

We offer a Sprint at $3,750: two weeks to set up the system and the files. For ongoing upkeep, Standard is $4,995/mo and Advanced is $7,495/mo. Published prices are on pricing: a Sprint is $3,750 per two weeks, Standard is $4,995 a month, and Advanced is $7,495 a month.

If you want help choosing what's in AGENTS.md versus DESIGN.md before you scale it, book a discovery call. No pitch, just a straight conversation about where you are.