Six portable Agent Skills that teach AI coding agents how to audit, understand, and safely edit Figma files — without breaking the design.
Built for Claude Code, the Figma MCP server, Figma Agent / Figma Make custom skills, Codex, and any client that supports the SKILL.md Agent Skills format.
- Why these skills exist
- The skills
- How the skills work together
- Installation
- Usage examples
- Compatibility
- Design principles
- FAQ
- Contributing
- License
AI agents are increasingly asked to read and edit Figma files directly — through the Figma MCP server, the Figma Plugin API, or Figma Agent. In practice they fail for a predictable reason: most Figma files are not written to be machine-readable.
Typical failure modes an agent hits in a real production file:
- It edits
Frame 427instead of the meaningful container, because nothing in the layer name says which is which. - It picks an abandoned exploration frame as the canonical screen.
- It flattens a wrapper frame and silently destroys a border, shadow, or corner radius.
- It converts a frame to Auto Layout and the visual layout drifts.
- It propagates a change to the wrong copy of a repeated UI pattern.
- It selects the wrong component variant because the property vocabulary is inconsistent across the system.
- It misreads hug / fill / fixed sizing and breaks responsive behavior.
These skills encode the guardrails that prevent exactly those mistakes. Three are strictly read-only audits that tell you where a file is dangerous for an agent to touch. Three are preservation-first write skills that change structure without changing the rendered result.
| Skill | Mode | Scope | What it does |
|---|---|---|---|
current-page-audit |
🔍 Read-only | Active page | Audits the current Figma page for AI parsability and edit hazards |
design-file-audit |
🔍 Read-only | Whole file | Audits an entire design file for structural clarity and canonicality |
design-system-audit |
🔍 Read-only | Whole system | Audits a design system for component, property, variant, and token ambiguity |
ds-remediate |
✏️ Write | Accepted scope | Applies approved audit findings without redesigning the system |
safe-auto-layout-conversion |
✏️ Write | Frame | Converts manual positioning to Auto Layout, preserving the visual result |
safe-nesting-cleanup |
✏️ Write | Frame tree | Removes redundant wrapper frames without destroying visual properties |
Audits only the currently active page and surfaces the highest-impact issues that could cause another AI agent to misunderstand the design or make an incorrect edit.
It checks for structural ambiguity, naming problems, layout inconsistency, unclear canonicality, repeated-UI mismatches, and likely accidental errors. It infers the page's own dominant conventions first, then flags deviations from those — it does not impose an external design-system opinion.
The core question it asks of every suspicious case:
If another AI agent encountered this page without tribal knowledge, what could it reasonably misunderstand or edit incorrectly?
Findings that can't be resolved from on-page evidence are labelled NEEDS HUMAN CONFIRMATION rather than guessed at.
File: figma-agent-current-page-audit-for-MCP.md · Cards: what · how · safety
The file-wide counterpart to the page audit. It reviews a full Figma product/design file for the parts that are hard to parse, ambiguous, inconsistent, misleading, structurally obscure, or unnecessarily complex — anything likely to cause an incorrect agent edit or inference.
This is explicitly not a design-system audit. It does not grade the file against preferred conventions; it infers the conventions already dominant in the file and reports meaningful deviations from those.
File: figma-agent-design-file-audit-for-MCP.md · Cards: what · how · safety
A strictly read-only audit of an entire Figma design system, aimed at the parts that are hardest for an AI agent to parse, understand, select, configure, and use reliably. It is not a redesign or a cleanup pass — it produces findings, not changes.
It inspects pages and sections, components, component sets, variants, component properties, exposed nested-instance properties, variables, modes, collections, aliases, bindings, styles, and documentation. Findings are grouped into a structured report:
| Section | Covers |
|---|---|
| Worst Component Offenders | Ranked components that are hardest to use correctly |
| A. Cross-System Inconsistencies | The same idea modelled differently in different places |
| B. Ambiguous Vocabulary | Names that don't distinguish what they refer to |
| C. Property-Schema Mismatches | Equivalent components with divergent property APIs |
| D. Layer-Naming Problems | Names that mislead or carry no signal |
| E. Variable / Token Inconsistencies | Divergent or ad-hoc token usage |
| F. Possible Structural Errors | Likely accidents rather than intent |
| G. Needs Human Confirmation | Ambiguity not resolvable from file evidence |
| H. Recommended Canonical Conventions | The conventions the system already implies |
Every finding carries severity and confidence, and must cite on-file evidence. The read-only contract is enforced down to the API level: when use_figma is needed for inspection, JavaScript may only read and return data — no setters, no creation or deletion calls, no node.set(...), no plugin-data writes. If an inspection can't be done without mutating the file, the skill omits it and states the limitation.
File: figma-agent-design-system-audit-for-MCP.md · Cards: what · how · safety
A preservation-first Figma design system remediation skill. It takes an existing audit (or an explicitly accepted scope) and applies the fixes to components, variants, component properties, Auto Layout structure, variables, styles, and tokens — while preserving the system's visual output, behavior, semantics, supported states, and established conventions.
Use it for: applying an audit, standardizing inconsistent component or property naming, cleaning up redundant component nesting, correcting inconsistent token usage, making component APIs consistent.
Do not use it for: running the initial audit, building a new design system, redesigning components, broad aesthetic cleanup, inventing a new naming or token philosophy, or publishing a library.
Ships in three forms so it works across clients:
| File | For |
|---|---|
SKILL.md |
Portable Agent Skill with routing frontmatter (Claude Code, Codex, MCP clients) |
figma-agent-ds-remediate.md |
Single-file upload for Figma Agent / Figma Make custom skills |
invocation.md |
Invocation resolver, companion-skill rules, prompt examples |
Directory: figma-agent-ds-remediate/ · Cards: what · how · safety
Converts Figma frames from manual positioning (layoutMode: NONE) to Auto Layout while reproducing the original visual result exactly — preserving spacing, indentation, overlays, footer placement, and existing dimensions.
Its governing rule is preserve first, restructure second: never enable Auto Layout and then try to repair the damage. The prescribed order is capture the current visual state → record the geometry that must be preserved → determine the wrapper structure needed to reproduce it → build inside-out → enable Auto Layout → apply sizing rules only after the relevant parent is Auto Layout → compare against the original.
File: figma-agent-safe-auto-layout-conversion.md · Cards: what · how · safety
Also known as the Matryoshka fix. Rules for flattening deep Frame > Frame, Row > Row, or Stack > Stack nesting — and for cleaning up generated Figma hierarchies — without silently destroying borders, backgrounds, shadows, corner radius, or clipping.
It supplies a concrete hasVisualProperties(node) check against strokes, fills, effects, corner radius, clipsContent, blend mode, and opacity, and permits removal only when the wrapper is doing no visual work. When a wrapper does carry visual properties, three strategies are offered: keep it, transfer the properties down to the single child, or transfer them up to the parent.
A frame with a border is the border — removing it removes the border.
File: figma-agent-safe-nesting-cleanup.md · Cards: what · how · safety
┌───────────────────────────────────┐
READ-ONLY │ current-page-audit │ active page
(find problems) │ design-file-audit │ whole file
│ design-system-audit │ whole system
└────────────────┬──────────────────┘
│ findings reviewed
│ & accepted by a human
▼
┌───────────────────────────────────┐
WRITE │ ds-remediate │ applies the scope
(fix them safely) └────────────────┬──────────────────┘
│ delegates to
┌──────────────┴──────────────┐
▼ ▼
safe-nesting-cleanup safe-auto-layout-conversion
(wrapper flattening) (Auto Layout conversion)
Audit first, get the findings accepted, then remediate. ds-remediate deliberately refuses to invent scope for itself.
Clone into your personal or project skills directory:
git clone https://github.com/albertogloder/figma-agent-skills.git ~/.claude/skills/figma-agent-skillsSkills with SKILL.md frontmatter are discovered automatically. Restart Claude Code, then invoke by name.
Figma custom skills are single-file uploads with explicit invocation. Upload the single-file variant of the skill you want and confirm its name — for example:
- Upload
figma-agent-ds-remediate/figma-agent-ds-remediate.md - Set the name to
ds-remediate→ invoke with/ds-remediate
Include the audit context or accepted scope in the same prompt, since Figma Agent does not auto-chain custom skills.
Place the skill directory in your client's supported skills location, keeping SKILL.md at the skill-directory root. The frontmatter description on each skill is written as a routing rule so compatible clients can select it automatically.
For destructive or write-heavy work, explicit invocation is preferable to model-driven routing.
Audit the current Figma page for anything an AI agent could misread or break.
Run a read-only audit of this Figma file and tell me which frames are unsafe to edit programmatically.
Audit our design system for AI readability. Rank the worst component offenders
and show me the property-schema mismatches.
/ds-remediate Apply findings 3, 7, and 11 from the audit — the inconsistent
component property names on Button and the redundant nesting in Card.
Convert this frame to Auto Layout without changing how it looks. Screenshot before and after.
Flatten the nested Row wrappers in this component, but keep every border and shadow intact.
| Requirement | Notes |
|---|---|
| Figma read access | Required by all three audit skills |
| Figma write access | Required by ds-remediate and the two safe-edit skills |
figma-use companion skill |
Mandatory before every use_figma / Figma Plugin API call |
| Figma MCP server | Recommended transport for MCP-based clients |
When calling use_figma, load figma-use first and pass both the active skill and figma-use in the skillNames parameter. If skills were loaded through MCP resources, use the resource: prefix that figma-use requires.
These are the invariants shared across every skill in this repository.
- Read-only means read-only. The audit skills never rename, move, restructure, resize, restyle, detach, swap, or delete anything — enforced down to forbidding setter calls in inspection JavaScript.
- Preserve first, restructure second. Never make a destructive change and then try to repair the visual result.
- Infer local conventions before judging. The file's own dominant patterns are the baseline — not an external design-system opinion.
- Say "I don't know." Anything not determinable from on-file evidence is escalated as NEEDS HUMAN CONFIRMATION instead of guessed.
- Cite evidence. Findings reference the actual nodes, properties, and values they're based on, with severity and confidence attached.
- Optimize for the next agent. The target reader is an AI agent with no tribal knowledge about the file.
- Scope comes from humans. Write skills act on accepted findings, never on self-generated scope.
What is an Agent Skill?
A Markdown file with YAML frontmatter (SKILL.md) that gives an AI agent procedural instructions for a specific task. The agent loads it on demand instead of carrying the instructions in every prompt.
Do I need the Figma MCP server? For MCP-based clients like Claude Code, yes — that is how the agent reaches your Figma file. For Figma Agent / Figma Make, the skills run inside Figma and no MCP server is needed.
Will the audit skills modify my Figma file? No. All three audits are strictly read-only by design and state that constraint as non-negotiable in their own instructions.
What is the difference between the three audits?
Scope. current-page-audit inspects only the active page. design-file-audit covers an entire product/design file. design-system-audit covers a component library — components, variants, properties, variables, and tokens — and asks whether an agent could pick and configure the right one.
Is ds-remediate a design-system audit tool?
No — it is the remediation half. Run design-system-audit first, have a human accept the findings, then hand that scope to ds-remediate.
Why do these skills require English (US) layer names? So that equivalent structures across a file can be matched reliably. Mixed terminology or mixed languages in structural names is a leading cause of an agent failing to recognize two things as the same pattern. The requirement covers structural names (pages, sections, frames, groups, screens, states) — not visible product copy.
Can I use these with Cursor, Codex, or another agent?
Yes. The skills are plain Markdown with standard Agent Skills frontmatter. Anything that can load a SKILL.md, or simply be handed the Markdown as context, can use them.
Issues and pull requests are welcome — especially additional failure modes observed when an AI agent edits a real Figma file.
When adding a skill, keep the house style: explicit non-negotiable constraints, a stated read-only or write mode, ordered procedures rather than prose advice, evidence-cited findings, and an escape hatch for ambiguity.
MIT — see LICENSE.
Topics: figma · figma-mcp · figma-plugin-api · agent-skills · claude-code · claude-skills · ai-agents · mcp · model-context-protocol · design-system · design-system-audit · design-tokens · auto-layout · design-to-code · figma-make · llm-tools