# Making a design system agent-ready > Your design system was written for humans. Agents read it and guess. What agent-ready means, what SKILL.md and DESIGN.md each do, and the real work. Source: https://umairalikhatri.com/work/agent-ready-design-systems/ Author: Umair Ali Khatri Updated: 2026-08-29 --- [← Back to work](https://umairalikhatri.com/work/) agent-ready # Making a design system agent-ready 29 August 2026 ยท 7 min read Your design system was written for humans. Agents read it and guess. That is not a complaint about your design system. It is a description of the reader who turned up after you finished building it. ## The guess An agent does not browse. It reads what fits in its context, then acts. Give it a hex value and no rule about when to use it. It will use it everywhere the value looks right. Your primary purple ends up on a delete button. Purple is the brand colour. The button is on-brand. The button is also wrong. Nothing in your file said destructive actions get their own colour. Everyone in the room already knew. On-brand and wrong is the specific failure mode. It survives a screenshot. It dies in a design review. The second failure is naming. Your system says "use semantic naming" and assumes the reader knows what that means here. An agent has no examples, so it invents them. surface-elevated-2. text-muted-alt. brand-primary-main. Each one plausible. None of them yours. Run the same task tomorrow and you get three different names. The third is composition. Your system documents a card. It does not say a card never contains another card, because nobody on your team would do that. An agent will, on the first task where nesting is the shortest path to the layout. An agent will not tell you it guessed. It returns finished work either way. ## Agent-ready Agent-ready means an agent can act on your design system without asking you a question. Three tests. Every value has a rule attached to it. Every rule is checkable against the output. Every gap is declared instead of left silent. A token table gives you half of the first test and nothing else. That is why a variable export changes nothing. You get the same guessing as before, in a tidier file. ## What it is not Agent-ready is not an MCP server. That is plumbing. It moves data between your tools and the agent. It does not tell the agent what good looks like. It is not a Figma plugin either. A plugin reads the file. An agent needs the rules behind the file. It is not a token export. Variables in JSON give an agent a longer list of values it still has no rules for. Three things your team may already have. None of them closes the gap. ## Two files The ecosystem settled on two formats, and they split cleanly. SKILL.md is behaviour and procedure. What to do, in what order, and when. DESIGN.md is appearance and tokens. What things look like, and why. Keeping them apart matters more than it sounds. A rule about when to run an accessibility check does not belong in the same place as your type scale. One is a procedure. The other is a value. You need both because agents fail in both directions. One agent builds a correct component in the wrong colour. Another picks the right colour and skips the contrast check you run every time. ## The skill file SKILL.md came from Anthropic in December 2025, released as an open standard. A skill is a directory. The minimum is one SKILL.md file. By convention scripts/, references/ and assets/ sit beside it. Two frontmatter fields are required. name must match the directory name, lowercase, hyphens only, 64 characters at most. description says what the skill does and when to use it, in up to 1024 characters. Four optional fields sit alongside them: license, compatibility, metadata, and allowed-tools, which the spec still marks experimental. That description field does more work than anything else in the file. It is the only part loaded at startup, roughly 100 tokens for every installed skill. The agent reads descriptions to decide what to open. A vague description means your skill never activates at all. The body loads only once the skill fires. The spec recommends staying under 5000 tokens and under 500 lines, and pushing anything longer into references/, one level deep. That budget is the forcing function. It is the reason converting a design system is editing work, not export work. ## The design file DESIGN.md came from Google Labs, open-sourced out of Stitch on 21 April 2026 under Apache 2.0. The spec header still reads version: alpha. Treat it as a draft that works rather than a settled standard. The shape is the useful part. YAML frontmatter between --- carries the tokens. The markdown body below carries the reasoning. The spec says it plainly: "The tokens are the normative values; the prose provides context for how to apply them." Values on top, judgment underneath, in one file. A token table has never done the second half. name is the only required key. The minimum content is a defined primary colour palette. Everything else can be left out, but a gap has to be declared in the omitted array. Steal that rule even if you never write a DESIGN.md. A declared gap is a work item. A silent gap is a place where the agent invents something and hands it to you finished. The body runs eight ## sections in a fixed order, ending with Do's and Don'ts. That last section is where most of your real rules will live. The two files travel together now. awesome-design-skills on GitHub holds 67 skills under MIT, 2.6k stars. Every entry is a folder with a SKILL.md and a companion DESIGN.md. ## The work Converting a design system is three passes. None of them is a download. Extract what is already true. Colours, type scale, spacing, radii, components. Mechanical, and the fast part. Write the rule under every value. The slow part. Each token needs the sentence nobody wrote down. When to use it. When not to. What wins when two rules collide. This is where the arguments start. Half your team disagrees about it and has never had to say so out loud. Most of those sentences already exist. They live in review comments, in Slack threads, in the thing you say every time someone gets it wrong. The audit is mostly transcription. Cut everything an agent cannot use. The governance model. The changelog. The contribution guide. The story of the rebrand. Links into Figma files a headless agent cannot open. All real documents. All written for a different reader. ## What survives A rule survives translation if you can check the output against it without asking a person. "Primary buttons use the primary token." Survives. "Destructive actions never use brand colour." Survives. "Use the accent sparingly." Does not. Sparingly is not a quantity. "Follow the spirit of the brand." Does not. That is not a rule, it is a deferral. Most design systems carry more of the second kind than their authors expect. Finding them is a large part of the value. It happens before you write a line of the new file. Then you test it. Hand the file and a real task to the agents your team already uses. Read what comes back. Wrong output tells you which sentence was ambiguous. Fix the sentence, not the output. ## The race The collection race is over. The standards won it for everyone. Anyone can pull 67 skills off a public repo this afternoon. I built a [577-file knowledge graph in one session](https://umairalikhatri.com/work/how-i-built-a-577-file-design-knowledge-graph/), and collecting was the easy half. What does not come out of a repo is the sentence that says when your teal is wrong. That sentence sits in the head of one person on your team. It has never been written down, and it is the only part of this that cannot be downloaded. The scarce assets are curation and judgment. An agent will follow a bad rule perfectly. That is the argument for writing the rule yourself. If your design system needs to work with agents, [there are three ways in](https://umairalikhatri.com/work/). SKILL.md and DESIGN.md are both public standards. Every claim here carries its date. [Back to work](https://umairalikhatri.com/work/)