DESIGN.md vs CLAUDE.md and AGENTS.md

Four Markdown files with all-caps names now compete for the root of your repository, and they get mixed up constantly. Here is the comparison first, the details after.

The one-table answer#

The shortest possible version: DESIGN.md is data (a design system agents apply), AGENTS.md and CLAUDE.md are instructions (how agents should work in this repo), and SKILL.md is a capability (a reusable procedure loaded on demand).

What does each file do?#

DESIGN.md: the design system#

DESIGN.md is an open-source file format from Google that stores a complete design system in a single Markdown file: machine-readable design tokens (colors, typography, spacing, components) in YAML frontmatter, plus human-readable rationale in Markdown prose. AI coding agents like Claude Code, Cursor, and Copilot read it to generate UI that consistently matches your brand.

A minimal, spec-valid example:

---
version: alpha
name: Acme
colors:
  primary: "#4F46E5"
  surface: "#FFFFFF"
  on-surface: "#1F2937"
typography:
  body-md:
    fontFamily: Inter
    fontSize: 16px
    lineHeight: 1.5
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.surface}"
    rounded: 8px
---

## Overview

Acme is confident and understated. Prefer whitespace over ornament.

Two things distinguish it from the other three files. First, the frontmatter is normative data, not prose: token maps are flat key-value pairs, values are validated (the CLI ships nine lint rules in v0.3.0), and references like {colors.primary} must resolve. Second, it is tool-agnostic by design: the same file feeds any agent. One honest caveat: Claude Code, Cursor, and Copilot do not discover DESIGN.md automatically; you reference it from AGENTS.md, CLAUDE.md, or .cursor/rules. Start with what DESIGN.md is for the full picture, or the spec guide for every field.

AGENTS.md: the project briefing#

AGENTS.md is an open, cross-vendor format for giving coding agents the context a new contributor would need: how to build, how to test, which conventions apply. It is plain Markdown with no required schema: headings and bullet points, written for machines to follow. The format is documented at agents.md, which is the reference for which tools currently support it.

# AGENTS.md

## Setup
- pnpm install && pnpm dev

## Conventions
- TypeScript strict mode; no default exports
- Run pnpm test before committing

## Design
- For any UI work, read DESIGN.md and use only tokens defined there.
- Never invent hex values or font sizes.

Note the last section: AGENTS.md does not contain the design system, it points to it.

CLAUDE.md: the Claude Code config#

CLAUDE.md plays a similar role to AGENTS.md but for one tool: Claude Code reads it automatically at the start of a session. Teams use it for tool-specific preferences (permissions, workflow habits, model-specific phrasing) that would be noise for other agents. If you use both files, keep CLAUDE.md thin and defer to AGENTS.md:

# CLAUDE.md

- Follow the conventions in AGENTS.md.
- For UI tasks, read DESIGN.md first and use only its tokens.
- Never commit directly to main.

See using DESIGN.md with Claude Code for the full setup.

SKILL.md: the packaged capability#

A SKILL.md file defines an Agent Skill: a named, self-contained procedure that supporting agents load only when a task matches its description. Where AGENTS.md is always-on context, a skill is on-demand. A design-flavored example:

---
name: new-component
description: Scaffold a UI component that follows our design system
---

1. Read DESIGN.md and select tokens for the component.
2. Scaffold the component with tests.
3. Run pnpm lint and pnpm test; fix findings.

Details of the skill format vary by tool version, so treat your agent's documentation as the source of truth.

How do the files work together?#

The pattern that works is a reference chain with a single source of truth. Instructions files point; DESIGN.md holds.

my-app/
├── AGENTS.md          # how to work in this repo → points to DESIGN.md
├── CLAUDE.md          # Claude Code specifics → defers to AGENTS.md
├── DESIGN.md          # the design system: tokens + rules (single source of truth)
├── .claude/
│   └── skills/
│       └── new-component/
│           └── SKILL.md   # reusable procedure → reads DESIGN.md
└── src/

The flow at generation time: the agent starts, loads its instructions file (CLAUDE.md automatically for Claude Code; AGENTS.md for tools that support it), hits the line "for UI work, read DESIGN.md," pulls the file into context, and generates against your actual tokens instead of statistically plausible ones. Because DESIGN.md is the only place design decisions live, updating a brand color is a one-line diff, and the CLI's diff command can even flag regressions between versions.

A concrete walk-through. You ask Claude Code to "add a pricing card to the marketing page." It has already loaded CLAUDE.md, which defers to AGENTS.md for conventions and tells it to read DESIGN.md before touching UI. It opens DESIGN.md, finds colors.primary, typography.body-md, and button-primary, and produces a card that uses #4F46E5 because the file says so, not because that hex happened to be common in its training data. If the same repo is later opened in Cursor, a matching pointer in .cursor/rules produces the same behavior. That is the whole trick: the instructions differ per tool, the design system does not.

One more distinction worth making: DESIGN.md is the only file of the four with a versioned specification and a validating toolchain behind it. The @google/design.md CLI (v0.3.0 as of June 15, 2026) can lint the file, diff two versions, and export tokens to Tailwind or W3C DTCG formats. AGENTS.md, CLAUDE.md, and SKILL.md are free-form by design: useful precisely because nothing constrains them, but nothing checks them either.

Which files do you actually need?#

Work down this list and stop when it matches your project:

1. Solo prototype, one AI tool, has a UI: DESIGN.md plus that tool's config file (CLAUDE.md or .cursor/rules) referencing it. Skip AGENTS.md until a second tool or person arrives.
2. Team repo with a UI, mixed tools: AGENTS.md as the shared briefing, DESIGN.md as the design source of truth, and thin per-tool files (like CLAUDE.md) that defer to AGENTS.md.
3. Backend, CLI, or library, no UI: AGENTS.md (and/or CLAUDE.md) only. A DESIGN.md with nothing to style is dead weight.
4. Recurring specialized workflows (release notes, component scaffolding, audits): add SKILL.md files on top of whichever setup you have.

No project needs all four on day one. Most UI projects end up with two: one instructions file and one DESIGN.md.

What are the common mistakes?#

• Duplicating design rules in CLAUDE.md. The moment tokens exist in two files, they will disagree. Keep hex values, spacing, and typography in DESIGN.md only; instructions files get one pointer line.
• Assuming agents auto-read DESIGN.md. They don't (Stitch reportedly being the exception). Without a reference in AGENTS.md, CLAUDE.md, or .cursor/rules, the file is invisible and the agent free-styles your brand.
• Pasting the whole design system into AGENTS.md. AGENTS.md is loaded for every task, including backend work. In our July 2026 analysis of all 74 files in the awesome-design-md collection, the median DESIGN.md weighs roughly 7,050 tokens, context you should spend only on UI tasks, which is exactly what a conditional pointer ("for UI work, read DESIGN.md") achieves.
• Letting the files contradict each other. If AGENTS.md says "use Tailwind defaults" and DESIGN.md defines a custom scale, the agent's behavior becomes a coin flip. When in doubt, the tokens win: the spec itself states, "The tokens are the normative values; the prose provides context for how to apply them."
• Treating DESIGN.md as prose documentation. Its frontmatter is machine-validated data. Run npx @google/design.md lint DESIGN.md: broken references are errors, missing primary colors and WCAG AA contrast failures are warnings.

Next step: you've seen how DESIGN.md relates to instruction files. The more consequential comparison is architectural. Read DESIGN.md vs MCP to see when a static file beats a live design-system server (and when it doesn't), or work through the DESIGN.md spec guide to write your first file.