DESIGN.md vs SKILL.md vs tokens.json: What Should AI Agents Read?

There are five common ways to give a coding agent a design: a project rules file, a Cursor rule, an Agent Skill, a DESIGN.md and a design tokens file. They differ in when the agent reads them and what they're built to hold.

• CLAUDE.md: Claude Code's project instructions. Claude reads it "at the start of every session", from the project, your home folder or your organisation.
• AGENTS.md: the same idea as an open format, described as "a simple, open format for guiding coding agents" and read by Codex, Cursor, Gemini CLI, GitHub Copilot's coding agent, Windsurf and many others.
• Cursor rules: .mdc files in .cursor/rules with a short header that says when each rule applies.
• An Agent Skill: a folder with a SKILL.md file and any other files it needs, loaded only when a task matches its description.
• DESIGN.md and tokens.json: files that describe the design itself. DESIGN.md mixes tokens and prose; tokens.json holds values only.

The first three are about how the agent should work. The last three can hold the design. Picking well means putting each piece of information where it costs the least context and gets read at the right moment.

The main difference is loading: rules files are read in full at the start of every session, while a skill costs only its name and description until a task needs it.

Claude Code's docs say CLAUDE.md and AGENTS.md overlap: Claude reads AGENTS.md only when there's no CLAUDE.md in the working folder or above it. If you keep both, import one from the other with a line such as @AGENTS.md in CLAUDE.md.

Yes, there is now a named format, though many teams also use "DESIGN.md" loosely for any design doc in the repo. Google Labs publishes DESIGN.md as "a format specification for describing a visual identity to coding agents", with its specification hosted in the docs for Google's Stitch design tool.

Its repository (google-labs-code/design.md) describes a file in two layers: YAML design tokens (colours, typography, rounded corners, spacing and components) and Markdown prose that explains them. In its words, "Tokens give agents exact values. Prose tells them why those values exist and how to apply them." Sections are optional, but those present follow a set order:

1. 1Overview
2. 2Colors
3. 3Typography
4. 4Layout
5. 5Elevation & Depth
6. 6Shapes
7. 7Components
8. 8Do's and Don'ts

The format is Apache-2.0 licensed and at version "alpha", so the schema may still change. A command-line tool, @google/design.md, lints a file (broken token references, WCAG contrast), compares two versions and exports the tokens as a Tailwind v3 theme, a Tailwind v4 @theme block or DTCG tokens.json.

Neither Claude Code's memory docs nor Cursor's rules docs list DESIGN.md as a file they load on their own. Point to it from CLAUDE.md, AGENTS.md or a rule, or wrap it in a skill.

Put the full design system in a skill, and keep only a few lines in the always-on rules file. A design system is large and only matters when the agent touches the interface, which is exactly what skills are built for.

The official size guidance points the same way. Claude Code's docs say to "target under 200 lines per CLAUDE.md file" because longer files "consume more context and reduce adherence", and note that imports don't reduce the cost, since imported files load with the file that imports them. Cursor's docs say "Keep rules under 500 lines." A palette for two themes, a type scale, spacing, components and motion will crowd those budgets on every request, including ones that have nothing to do with UI.

A skill pays for itself differently. The Agent Skills specification describes three stages: metadata (about 100 tokens) loaded at startup for every skill, the SKILL.md body (under 5,000 tokens recommended) when the skill activates, and other files "only when required". Your tokens.json, rules and component notes can be as detailed as they need to be, because the agent opens each one only when its step needs it.

## Design
Our design system is the skill in .claude/skills/our-design.
- Never hard-code a colour, size or radius; use the tokens.
- One accent per screen, on the primary action.
- Ask before restyling more than one area at a time.

A tokens file is the exact-values layer: it is the most reliable way to pass colours and sizes, but it carries no reasons, so pair it with rules. The standard format comes from the W3C Design Tokens Community Group (DTCG).

The Design Tokens Format Module 2025.10, published on 28 October 2025, says it "is considered stable". Its core rule is simple: "An object with a $value property is a token." Tokens can carry a $type and a $description, and the spec recommends the .tokens or .tokens.json extension and the application/design-tokens+json media type. Its types include colour, dimension, font family, font weight, duration, cubic Bézier and number, plus composites such as shadow, typography, border and transition.

{
  "color": {
    "$type": "color",
    "accent": {
      "$value": { "colorSpace": "srgb", "components": [0.051, 0.447, 0.408], "hex": "#0d7268" },
      "$description": "The one action you want taken on each screen."
    }
  }
}

A $description helps, but a token file still can't say "use the accent once per screen" or "depth comes from hairlines, never shadows". Those rules belong in Markdown next to it, in a skill, a DESIGN.md or a rules file.

Start with the skill, then add one pointer per agent you use. The same folder works across tools, because skills follow an open format.

1. 1Create a skill folder (for example .claude/skills/our-design) with a SKILL.md whose description says when to use it: "Apply our design system. Use when building or restyling UI."
2. 2Add the data files next to it: tokens.json for values, rules.md for principles and a Never list, components.md for buttons, inputs, cards and navigation.
3. 3In SKILL.md, tell the agent which file to read at each step, and to audit and ask before editing.
4. 4Add two or three lines to CLAUDE.md or AGENTS.md that name the non-negotiables and the skill's path. For Cursor, use a short always-apply rule instead.
5. 5If you prefer one file, write a DESIGN.md and point to it from the same places; its CLI can export DTCG tokens if you need them.

A Livery kit is the skill layer, already written. Livery renders a public website at desktop, tablet and phone widths, measures its colours, type, spacing, radii, components and motion, and writes SKILL.md, tokens.json (colours by role, the type scale, spacing and radii), rules.md and notes on components, layout and motion. No AI model writes it; it comes from the measurements.

In Claude Code, a kit installs under .claude/skills with one pasted prompt that checks its sha256 hash. For Codex, unzip it into the project and add one line to AGENTS.md; for Cursor, ask the agent to read the kit's SKILL.md and save that sentence as a project rule. The kit's SKILL.md asks the agent to audit your project, report the gap and apply one area at a time, after you approve.