The DESIGN.md Agent Skill

A DESIGN.md only helps when the agent knows what to do with it. Most agents do not discover the file on their own, and when they write one they guess at the schema. The skill closes both gaps with instructions the agent loads whenever a task involves DESIGN.md or UI work in a repository that has one.

What the skill teaches#

• Read before building. Open DESIGN.md before writing UI, use only its tokens, and treat its Do's and Don'ts as rules rather than suggestions.
• Write valid files. The nine top-level keys, the seven typography properties, the eight component sub-tokens, reference syntax, nesting, the omitted key, and the canonical order of the eight Markdown sections.
• Lint and fix. Run npx @google/design.md lint, read the JSON report, and fix each finding with the rule table in the skill, errors first.
• Export. Generate a Tailwind v4 @theme block, CSS custom properties, W3C DTCG tokens, or a Tailwind v3 theme from the same file.
• Wire up other agents. Add the one-line instruction that points AGENTS.md or CLAUDE.md at DESIGN.md.

The skill includes a complete example file that passes the linter with zero warnings, so the agent starts from a correct pattern instead of a plausible one.

Install it in Claude Code#

For a project, so everyone who clones the repository gets it:

mkdir -p .claude/skills/design-md
curl -fsSL https://www.md-design.io/skills/design-md/SKILL.md \
  -o .claude/skills/design-md/SKILL.md

Commit the .claude/skills/design-md folder. For yourself across every project, use ~/.claude/skills/design-md instead.

Claude Code reads the skill's description and loads the instructions when a task matches it, for example "create a DESIGN.md for this app" or "lint our DESIGN.md and fix the warnings". You can also ask for it by name.

Other agents#

Agents that support the open Agent Skills format read the same folder structure: a design-md folder containing SKILL.md. Check your agent's documentation for where it looks for skills.

For an agent without skill support, save the file in your repository (for example as docs/design-md-skill.md) and add one line to AGENTS.md:

When working on DESIGN.md or on UI, follow docs/design-md-skill.md.

Read it before you install it#

The skill is plain Markdown and short enough to review in a few minutes. Open SKILL.md to read or download it. It covers:

1. What to do before generating UI in a project with a DESIGN.md
2. Writing the frontmatter, with value rules and a lint-clean example
3. The Markdown body and its section order
4. Validating with the linter, including a fix for every rule
5. Exporting tokens
6. Reviewing the result in the viewer
7. Pointing other agents at the file

Check that it works#

Two quick tests after installing:

• Ask the agent to lint your DESIGN.md and fix what it finds. It should run npx @google/design.md lint DESIGN.md, fix errors before warnings, and explain each change by rule.
• Ask for a new component, such as a pricing card. Every color, size, and radius in the result should trace back to a token in your file. If the agent invents a value, it is not reading DESIGN.md; check that the file sits at the repository root.

How the skill stays current#

The skill follows @google/design.md 0.4.0. Each time the site moves to a new release, automated checks fail until the skill matches it: its example must still lint with zero warnings, and its rule table must cover every rule the linter can report. See the changelog for what changed in each release, and the CLI and lint rules reference for every rule in depth.

For tool-specific setup without a skill, see DESIGN.md with Claude Code and DESIGN.md with Cursor.