A Claude Agent Skill is a folder - SKILL.md plus optional scripts and resources - that Claude Code, Claude.ai, or the Claude API load automatically when a task matches the skill’s description. We packaged our own scan, coverage and contrast audit, DTCG export, and code sync workflow into exactly that kind of skill.
This is not a list of skills to install. It documents the actual Agent Skills feature Anthropic shipped - the SKILL.md format, how Claude discovers and loads a skill, and how we wrote one around the Primitives → Atoms token architecture we already govern in Figma.
Related reading: the design tokens guide for the token hierarchy this skill assumes, coverage audit vs untokenized values and contrast audit for the checks the skill enforces, and code sync for the DTCG-to-repo pipeline it verifies.
What a Claude Agent Skill actually is
Agent Skills are Anthropic’s own feature, not a community convention: a folder that Claude loads dynamically to get better at a specialized, repeatable task, published as an open pattern in the anthropics/skills repository. Each skill is self-contained - a SKILL.md file plus whatever scripts or reference files it needs - and Claude decides on its own when to use one, the same way it decides whether to call a tool.
This sits at a different layer than the Markdown rule packs we cover in AI Skills for Designers - those are UX-writing and accessibility tone rules that Claude Code or Cursor load every session. An Agent Skill is procedural: it is not loaded by default, it is discovered by its description and invoked for one task, and it can carry executable scripts alongside its instructions. Ours does not tell Claude how to write copy - it tells Claude the order of operations for touching a tokenized component.
SKILL.md format: name, description, and progressive disclosure
Every skill needs exactly one required file: SKILL.md, opening with YAML frontmatter. Two fields are mandatory - name (64 characters max) and description (200 characters max) - and the description is the whole game: it is what Claude reads to decide whether your skill applies to the task in front of it. Get the description too vague and Claude never invokes the skill; get it too broad and Claude invokes it for the wrong task.
---
name: my-skill-name
description: A clear description of what this skill does and when to use it
---
# My Skill Name
[Add your instructions here that Claude will follow when this skill is active]
## Examples
- Example usage 1
- Example usage 2
## Guidelines
- Guideline 1
- Guideline 2That two-tier structure is deliberate. Anthropic calls it progressive disclosure: at session start, Claude only holds each skill’s name and description in context - a few dozen tokens - and reads the full Markdown body only once a task matches. If the body then points to a resource file or a script, Claude loads that third tier only when it actually needs it. A skill with a long body costs nothing until the moment it is relevant.
The four-step workflow we packaged as a skill
Before we wrote a line of SKILL.md, we had the workflow. We scan Figma files for untokenized values, run a coverage audit and a contrast audit to confirm the file is clean, export the result as W3C DTCG JSON, and sync it to code. Packaging that as a skill did not change the steps - it changed who enforces the order.
- Scan for untokenized values - find fills, strokes, spacing, and typography still holding raw hex or pixel values instead of a bound Figma Variable.
- Run the coverage audit and contrast audit - confirm what percentage of properties are bound to variables, and that every text/background pair still clears WCAG contrast, before export.
- Export DTCG JSON - the W3C-standard token format that Style Dictionary and comparable pipelines consume without a custom parser.
- Sync to code - generate CSS custom properties, SCSS, TypeScript constants, or Tailwind presets, and push the update through two-way sync into the repository.
Writing SKILL.md for design-token governance
The instinct is to write the skill’s body as a copy of the four steps above. That is necessary but not sufficient - those steps already happen in Figma, inside a plugin, on a schedule the design team controls. What Claude Code needs from the skill is not a how-to for running an audit; it is a gate: what to check in the repository before generating or editing a component, and what to refuse to do if that check fails.
---
name: design-token-governance
description: Verify exported DTCG tokens and tokens.css are current before generating or editing components. Use before any change that touches colors, spacing, radii, or typography.
---
# Design Token Governance
## When to use this skill
Invoke before writing or editing UI code that references design tokens, and before opening a PR that touches component styling.
## Steps
1. Read `tokens/tokens.json` (DTCG) and confirm it was regenerated after the last Figma coverage and contrast audit - check the export timestamp in the file header against the latest entry in `tokens/CHANGELOG.md`.
2. Run `scripts/check-dtcg-freshness.sh` and stop if it reports a stale export.
3. Cross-reference any new color, spacing, or radius literal in the diff against `tokens/tokens.css`. If a token already covers that value, use the token - do not introduce a new literal.
4. If no token covers the value, flag it in the PR description instead of inventing a one-off `var(--*)` name.
## Guidelines
- Never invent a token name that is not present in `tokens/tokens.css`.
- Treat a stale DTCG export as a blocker, not a warning.
- Prefer semantic tokens (`color-surface-elevated`) over primitives (`gray-950`) in component code.The script stays intentionally small - a shell check comparing the DTCG file’s modified time against the last audit note in git, not a reimplementation of our plugin’s scanning logic. We keep it in a scripts/ folder next to SKILL.md. Anthropic’s packaging guidance is to zip the skill with the folder name matching the skill’s name, and the folder itself as the ZIP root, not a subfolder:
design-token-governance/
├── SKILL.md
├── scripts/
│ └── check-dtcg-freshness.sh
└── resources/
└── token-naming-conventions.mdtoken-naming-conventions.md is the third tier - a reference file the skill body points to but Claude only opens for an edge case (an alias chain, a deprecated primitive name) that would otherwise bloat the main instructions. Test invocation before trusting any of this in a real PR: try prompts that should trigger the skill, read Claude’s reasoning to confirm it actually loaded, and tighten the description if it didn’t.
Agent Skills vs AGENTS.md rule packs vs one-off prompts
Design system teams already juggle three ways to steer an AI coding assistant, and it is easy to reach for the wrong one. The table below is the distinction that matters before you package anything.
Agent Skills vs AGENTS.md rule packs vs one-off prompts
| Agent Skill (SKILL.md) | AGENTS.md + rule packs | One-off prompt | |
|---|---|---|---|
| What it is | A folder Claude discovers and invokes for a specific task | Root-level repo contract plus versioned Markdown discipline rules | Instructions typed into a single chat |
| Discovery | name + description read at session start; full body loaded only when relevant | Loaded every session automatically | Not persisted past the conversation |
| Best for | A repeatable, ordered procedure - scan, audit, export, sync | Whole-repo policy - token paths, naming, banned patterns | A task you will not repeat |
| Can run code | Yes - scripts packaged alongside the instructions | No - text only | No |
| Where it lives | .claude/skills/, Claude.ai Skills, or a Claude Code plugin marketplace | .cursor/rules/ or root AGENTS.md | Nowhere after the session ends |
The three layers are not competitors. AGENTS.md still owns repo-wide policy - token paths, naming, what a PR must never do - the same ground we cover in AI Skills for Designers. An Agent Skill sits above that as a procedure Claude invokes for one recurring job; a prompt is what you write when the job will not happen twice.
Where the skill fits in the token pipeline
A skill is only as reliable as what it is checking. If the Figma file behind tokens.json still has untokenized fills, the skill can confirm the export is fresh and still wave through a component that references a color nobody bound to a Variable - the DTCG export was accurate, the Figma file was not. Governance in Figma has to happen before the skill has anything trustworthy to check.
Figma Variables (Primitives → semantic → component)
↓ scan for untokenized values + coverage / contrast audit
DTCG JSON + tokens.css (git)
↓
design-token-governance/SKILL.md (name, description, scripts/check-dtcg-freshness.sh)
↓
Claude Code (invokes the skill before touching tokenized components)
↳ optional: Figma Dev Mode MCP for live selection contextRead the diagram as a dependency chain, not a checklist to run once. Every time the Figma library changes, the export needs to run again before the skill’s freshness check means anything - which is exactly why the skill checks a timestamp instead of trusting that someone remembered.
Mistakes to avoid when packaging a workflow as a skill
- Writing a description so generic Claude never invokes it - “helps with design tokens” matches nothing; “verify exported DTCG tokens are current before editing styled components” matches an actual moment in a PR.
- Shipping a script that assumes paths your repo does not have - test the skill against the real
tokens.jsonlocation before you rely on it. - Skipping the coverage and contrast audit in Figma and expecting the skill to catch drift it cannot see - a skill reads what is in git, not what is unbound in the canvas.
- Building one giant skill that tries to cover scanning, exporting, and code review together - narrower skills that compose are easier for Claude to pick correctly than one that tries to do everything.
- Never testing invocation - try several prompts that should trigger the skill, read Claude’s reasoning to confirm it loaded, then iterate on the description if it did not.
Final verdict - Claude Skill for design tokens
A Claude Agent Skill will not fix a Figma file where colors are still typed in as hex - nothing invoked after the fact undoes governance you skipped upstream. What it does well is turn a workflow your team already runs by habit - scan, audit, export, sync - into something Claude Code checks every time, without a teammate having to remember to ask. Write the description precisely, keep the skill to one job, and test invocation before you trust it in a real PR.
FAQ
For the token architecture this skill assumes, start with the design tokens guide. For the governance steps it checks, see coverage audit vs untokenized values and contrast audit. For the rule-pack layer that governs how Claude writes code day to day, see AI Skills for Designers. Have general questions? See the Atomize FAQ.
