10 skills that keep an agent
inside your design system.
Portable SKILL.md files for Claude, Figma Make and Copilot. Each one targets a failure that has actually been measured, not a principle that sounds right. Every file is checked against the Agent Skills spec in CI.
- 10
- skills, spec-validated in CI
- 6
- practitioner personas covered
- 3
- frontmatter keys — fully portable
- 4.7k
- words, none loaded until used
Free, CC0, no email. Every skill is a plain static file an agent can fetch directly.
01 · Why a skill and not a rule
A skill is the tier where reference material stops costing you anything.
Only a skill's name and description sit in context. The body loads when the skill is actually selected, which is what makes a 500-word component catalogue affordable — it costs nothing on the turns that do not need it.
That inverts the usual advice. Rules that apply to every task belong in an always-on file and should be short. Everything else — procedures, catalogues, migration tables — belongs here.
The description is the whole selection surface
AGENTS.md · Guidelines.mdBilled on every turn. Only the rules that apply to every task belong here.
SKILL.mdName and description sit in context; the body loads only when the skill is selected. This is where reference material belongs.
MCP tool callQueried during the session, so it cannot go stale between releases.
Three of these skills are verification passes — run them after generation rather than before. None of them are merge gates: the blocking check should stay deterministic, with no model in the enforcement path.
02 · The pack
Each one targets a failure someone measured.
The descriptions below are read from the files themselves at build time, so what you see is what the agent sees at selection time — not a paraphrase of it.
Generating UI in Figma Make
456w.claude/skills/generating-ui-in-figma-make/SKILL.md
Prevents
Make can inspect the packages but does not know what to reach for, so output is plausible and off-system.
Evidence
Figma's own guidance: a guidelines folder read before generation, Guidelines.md first, and prescriptive rules — 'Do not use small text for anything except captions' over 'use small text sparingly'. Source
The description the agent selects on
Produces on-system UI in Figma Make and the Figma agent by writing and using the guidelines folder correctly, binding raw values to variables, and preferring library components over generated ones. Use when generating a screen, prototype or component in Figma Make, when authoring the guidelines folder for a Make file, when Make output does not match the design system, or when the user mentions Figma Make, the Figma agent, guidelines.md, or design system packages in Figma. Applies before the first generation in any Make file.
Writing agent-facing docs
612w.claude/skills/writing-agent-facing-docs/SKILL.md
Prevents
Instruction files never trigger, cost more than they return, or describe a system that has since changed.
Evidence
Meta's Astryx shipped a README naming an export its package does not have. The agents read it, used the name, and produced a build failure. Source
The description the agent selects on
Writes and maintains the instruction files agents read — AGENTS.md, CLAUDE.md, cursor rules, Copilot instructions and skills — so they trigger reliably, cost little, and do not rot. Use when creating or editing any agent instruction file, when setting up a repo for AI coding agents, when a skill is not triggering, when instruction files contradict each other, or when the user mentions AGENTS.md, CLAUDE.md, SKILL.md, agent context or AI onboarding. Applies before adding any new instruction file to a repository.
Using design system components
506w.claude/skills/using-design-system-components/SKILL.md
Prevents
Agents invent components — Box, Stack, Container — because other libraries have them, and re-implement components that already ship.
Evidence
Ant Design, Carbon and SLDS each ship an export allow-list specifically to make invention provable rather than merely discouraged. Source
The description the agent selects on
Builds UI from an existing design system instead of inventing components. Enforces search-before-generate, an existence allow-list, verbatim import paths, and composition rules. Use when writing or editing any UI code in a repo that has a component library, when the user mentions a design system, component library, or asks to build a screen, page, form, dialog, table or any interface. Applies whenever a component is about to be created — check this skill before writing a new component file.
Applying design tokens
465w.claude/skills/applying-design-tokens/SKILL.md
Prevents
Literal hex and pixel values instead of tokens. Correct in light mode, wrong in dark, wrong again after a rebrand.
Evidence
One reported component pipeline saw token hallucination in 27 of 27 cases at v0.2 and zero from v0.3, after the retrieval layer changed. Source
The description the agent selects on
Applies design tokens correctly instead of hardcoding colours, spacing, radii or type sizes. Covers semantic-over-primitive selection, dark mode safety, and the token resolution order. Use when styling any component, choosing a colour or spacing value, writing CSS or Tailwind classes, converting a design to code, or when the user mentions tokens, theming, dark mode, or a rebrand. Applies before writing any literal hex, px, or rem value in UI code.
Specifying component contracts
550w.claude/skills/specifying-component-contracts/SKILL.md
Prevents
Prop hallucination. An open prop type lets the agent invent values, and each one that survives review becomes a sample the next generation copies.
Evidence
Four independent formalisations — Atlassian's TS schemas, Storybook manifests, Astryx's CLI, Code Connect — converge on the same field set with zero interoperability. Source
The description the agent selects on
Defines the per-component metadata an agent needs to use a component correctly — props with defaults, exhaustive variant enums, verbatim imports, composition rules, accessibility preconditions and deprecation pointers. Use when authoring a new component, documenting an existing one, designing a component API, building a component manifest or registry, or when the user asks what agents need to know about a component. Applies when prop hallucination or invented variants are the problem being solved.
Migrating deprecated APIs
399w.claude/skills/migrating-deprecated-apis/SKILL.md
Prevents
Agents reach for deprecated APIs at a structural rate, because old code outnumbers new code in the corpus.
Evidence
25–38% deprecated-usage prediction across seven evaluated models. A retrieval-layer fix, not a prompting one. Source
The description the agent selects on
Detects and replaces deprecated design system APIs, using a machine-readable deprecation table with replacement pointers rather than relying on the model's training data. Use when upgrading a design system version, when a build warns about deprecated usage, when writing code against a library that has had a major release, or when the user mentions migration, upgrade, breaking changes, or a codemod. Applies whenever code is written against a library whose old API outnumbers its new API in public code.
Connecting Figma to code
443w.claude/skills/connecting-figma-to-code/SKILL.md
Prevents
The design-to-code mapping lives in prose, so the agent builds a layout that looks correct out of the wrong components.
Evidence
Only 2 of 20 surveyed design systems ship Figma Code Connect — Carbon with ~86 mapping files and Primer with 52. Source
The description the agent selects on
Maps Figma components to their real code counterparts so agents generate the right import and props from a design, using Code Connect where it exists and an explicit mapping table where it does not. Use when implementing a Figma design in code, when setting up or maintaining Figma Code Connect, when an agent generates markup that looks right but uses the wrong components, or when the user mentions design handoff, design-to-code, Figma MCP, or component mapping. Applies whenever a design file is the input to code generation.
Auditing conformance
387w.claude/skills/auditing-design-system-conformance/SKILL.md
Prevents
Generation is trusted. The teams doing this well check mechanically and make the agent fix what fails.
Evidence
SLDS ships a validate skill, Polaris a bundled validate.mjs the agent must run, shadcn an evals directory that regression-tests its own rules. Source
The description the agent selects on
Audits generated or edited UI against a design system and reports what drifted — components invented rather than imported, literal values where tokens exist, deprecated APIs, and unmet accessibility preconditions. Use after generating UI, before opening a pull request, when reviewing a diff that touches components or styles, or when the user asks whether code follows the design system. Applies as the verification step for any UI generation task.
Checking semantic accessibility
476w.claude/skills/checking-semantic-accessibility/SKILL.md
Prevents
Semantic accessibility failures are invisible to linters. The element is present, labelled and focusable; the label just means nothing.
Evidence
541 issues across 300 generated interfaces — about 1.8 each. Generic button labels 27%, vague link text 26%. All pass axe-core. Source
The description the agent selects on
Finds accessibility failures that automated linters pass — generic button labels, vague link text, unhelpful alt text, wrong ARIA, and unlabelled form fields. Use after generating any UI, when reviewing components or a diff for accessibility, when axe or eslint-plugin-jsx-a11y reports clean but the interface has not been read, or when the user mentions accessibility, a11y, WCAG, screen readers or assistive technology. Applies to every generated interface, because these failures are invisible to structural tooling.
Reviewing UI for drift
438w.claude/skills/reviewing-ui-for-drift/SKILL.md
Prevents
Reviewers read for correctness rather than membership. Code can be entirely correct and still be drift.
Evidence
No shipped tool answers 'does something like this already exist?' before generation, or 'this is 85% a Card' after it.
The description the agent selects on
Reviews a pull request or diff for design system drift and reports findings with file and line, covering invented components, literal values, duplicated functionality, deprecated APIs and unmet accessibility requirements. Use when reviewing a PR that touches UI, when asked to review code as a design system maintainer, before merging generated UI, or when the user mentions design review, code review, drift, or system compliance. Applies to review of any diff containing components or styles, especially agent-authored ones.
03 · Validation
Six people have to get value, or it is a library of good intentions.
Each persona below is a real seat with a real failure. The coverage counts are derived from the manifest, so a skill cannot claim a persona it does not serve.
Design system maintainer
7 skillsKeep the library coherent while other people's agents write against it at volume.
Drift arrives as thirty reasonable-looking PRs, not one bad one. By the time it is visible in the codebase it is a quarter of work to undo.
Installs in
The design system repo — committed alongside the components.
- Using design system components
- Specifying component contracts
- Auditing conformance
- Migrating deprecated APIs
- Connecting Figma to code
- Reviewing UI for drift
- Writing agent-facing docs
Product engineer
5 skillsShip features fast using the design system, without reading its documentation end to end.
The agent invents components that do not exist, hardcodes hex values, and reaches for deprecated APIs because old code outnumbers new code.
Installs in
Their product repo, next to the code the agent is editing.
- Using design system components
- Applying design tokens
- Auditing conformance
- Checking semantic accessibility
- Migrating deprecated APIs
Product designer
5 skillsGenerate real screens in Figma Make that come out on-system rather than approximately on-brand.
Make can see the packages but does not know what to reach for, so output looks right and is built from the wrong parts.
Installs in
The guidelines folder of a Make file, and uploaded skills in the Figma agent.
- Using design system components
- Applying design tokens
- Checking semantic accessibility
- Generating UI in Figma Make
- Connecting Figma to code
Design engineer
5 skillsHold the Figma and code halves of the system in agreement, and own the token pipeline.
The design-to-code mapping lives in prose. Only two of twenty surveyed systems ship Code Connect; everyone else hopes layer names match export names.
Installs in
Both repos, plus Code Connect files and the token source.
- Applying design tokens
- Specifying component contracts
- Generating UI in Figma Make
- Connecting Figma to code
- Writing agent-facing docs
Accessibility specialist
4 skillsMake sure generated interfaces are usable, not merely lint-clean.
Generated UI passes axe and still fails people. The failures are semantic — a real label that means nothing — and no structural tool sees them.
Installs in
CI, review, and the agent's own verification step.
- Specifying component contracts
- Auditing conformance
- Checking semantic accessibility
- Reviewing UI for drift
Staff engineer or EM
4 skillsRun migrations and reviews across many teams without becoming the bottleneck.
Reviewers read for correctness, not for membership in the system, so drift passes review. Migrations stall half-finished.
Installs in
Review tooling and the shared repo template.
- Auditing conformance
- Migrating deprecated APIs
- Reviewing UI for drift
- Writing agent-facing docs
04 · Install
One file format, three places it works.
Claude Code
.claude/skills/{name}/SKILL.md
Unzip at the repo root. The folder name must match the skill's name field exactly or it silently will not load.
Figma Make and the Figma agent
Skills → Add skill → upload
Upload the Markdown file in the prompt box. For Make, the guidelines folder is read first — the Figma Make skill explains how to structure it.
GitHub Copilot
.github/skills/{name}/SKILL.md
Copilot also reads .claude/skills/, so if you already unzipped for Claude Code there is nothing more to do.
CC0 · no email · unpacks to .claude/skills/
- .claude/skills/using-design-system-components/Using design system componentsLoaded when relevant · 506w
- .claude/skills/applying-design-tokens/Applying design tokensLoaded when relevant · 465w
- .claude/skills/specifying-component-contracts/Specifying component contractsLoaded when relevant · 550w
- .claude/skills/auditing-design-system-conformance/Auditing conformanceRun after generation · 387w
- .claude/skills/checking-semantic-accessibility/Checking semantic accessibilityRun after generation · 476w
- .claude/skills/migrating-deprecated-apis/Migrating deprecated APIsLoaded when relevant · 399w
- .claude/skills/generating-ui-in-figma-make/Generating UI in Figma MakeLoaded every turn · 456w
- .claude/skills/connecting-figma-to-code/Connecting Figma to codeLoaded when relevant · 443w
- .claude/skills/reviewing-ui-for-drift/Reviewing UI for driftRun after generation · 438w
- .claude/skills/writing-agent-facing-docs/Writing agent-facing docsLoaded every turn · 612w
05 · How these were checked
Checked by a script, not by whoever wrote them.
scripts/check-skills.mjs runs in this repo's lint step and fails the build on any violation. It caught two of these files during authoring, and one of its own rules was wrong and had to be loosened.
It also cross-checks the manifest against the folder set, so the page cannot describe a skill that does not exist.
What the validator enforces
- Frontmatter starts at byte 0 — a leading blank line and the skill never loads.
- Only the six portable keys. Anything else hard-fails outside Claude Code.
- name equals the folder name, lowercase and hyphenated, 64 chars max.
- description under 1024 chars, third person, and states when to fire.
- No angle brackets in frontmatter — they can inject instructions into the system prompt.
- Every progressive-disclosure link resolves to a file that exists.
What this pack does not do
These are templates with placeholders, not a drop-in configuration — the value comes from filling in your components, tokens and deprecations. They are also unevaluated: nobody has measured whether they improve agent output on your system, and the one public benchmark in this space shows a heavily instrumented design system losing to a plain baseline most nights. Treat them as a starting structure with evidence behind each rule, not as a guarantee.