Guide · Agent skill
How to use the understand-figma agent skill: Figma design graph
Updated · written with AI from the project's own documentation and checked against our catalogue data
The understand-figma skill lets an AI agent read a Figma file through Figma's official REST API and turn it into a structured map of pages, screens, components, component sets, instances and design tokens. It then opens an interactive dashboard so you can browse how the design fits together. This guide explains what an agent skill is, how to install this one, how to trigger it, and what it needs and sends over the network.
Figma Design Knowledge GraphEgonex-AI/Understand-Anything · MIT Download the skill Quick start
- 1Create a Figma token. Go to figma.com/settings and create a personal access token.
- 2Set FIGMA_TOKEN. Export the token as the FIGMA_TOKEN environment variable in the terminal where your agent runs.
- 3Check Node and pnpm. Confirm Node.js 22 or newer and pnpm 10 or newer are installed.
- 4Install the skill. Unzip the downloaded ZIP into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
- 5Ask for the analysis. Send a request with the Figma file URL or file key and, optionally, a language.
- 6Open the dashboard. Review the summary the agent prints, then use the dashboard it launches to browse the graph.
What is an agent skill and what does this one do?
An agent skill is a folder containing a SKILL.md instruction file and optional scripts that an AI agent can load when a request matches the skill's purpose. This one is named understand-figma and its SKILL.md describes an analysis pipeline for a single Figma file.
When it runs, the agent fetches the file through the Figma REST API, a deterministic scan script writes a manifest of the nodes, the agent adds short explanations in batches, and a merge script produces knowledge-graph.json and meta.json. The result is a design knowledge graph with a kind:"design" dashboard.
- Maps pages, screens, components, component sets, instances and design tokens
- Adds an explanation to each part of the design through the agent
- Saves the graph to your project's data folder as knowledge-graph.json
- Launches the dashboard automatically when the build finishes
Install the understand-figma skill
Download the ZIP of the skill from this page. Then choose one of two routes depending on how you work.
For Claude Code, unzip the download into ~/.claude/skills/ to make it available in every project, or into a project's .claude/skills/ folder to limit it to that project. For the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.
- Personal install: unzip into ~/.claude/skills/
- Project install: unzip into your project's .claude/skills/
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Set up your Figma token and prerequisites
The skill reads a Figma personal access token from the FIGMA_TOKEN environment variable. Create a token at figma.com/settings, then export it in the terminal where you run the agent. The skill stops and asks you to set the token if it is missing.
You also need Node.js 22 or newer and pnpm 10 or newer. The skill's source expects the understand-anything core package to be built in the plugin folder. If the file packages/core/dist/figma/index.js is missing, the skill runs a pnpm install and a core build for you.
- Create a personal access token at figma.com/settings
- Run export FIGMA_TOKEN=<token> in your shell
- Confirm Node.js 22+ and pnpm 10+ are installed
- Make sure your machine can reach api.figma.com
export FIGMA_TOKEN=<token>How do you trigger the skill with a natural request?
Ask in plain language and include the Figma file URL or its file key. The skill's argument hint is a Figma file URL or key, with an optional --language flag to set the language of the output. You can also use the slash form /understand-figma with the same argument.
Give the skill a specific file and a clear goal, such as auditing the component structure or listing the design tokens. Public and private files work as long as your token has access to them.
- "Map the components and design tokens in this Figma file: https://www.figma.com/file/<key>"
- "Build a design graph for file key <key> in French using --language fr"
- "Show me how the screens and component sets in this Figma file are organised"
/understand-figma <figma-file-url-or-key> [--language <lang>]What happens during a run?
The run has four phases. First the scan script fetches the file and writes a scan-manifest.json with node counts, which the agent reports back. Next the agent analyses the nodes in batches of about 15, grouped by page where possible, running up to five batches at a time. If a batch fails the run logs a warning and continues.
Then a merge script combines the manifest with the batch results, validates the graph and writes knowledge-graph.json and meta.json. Intermediate files are removed, leaving the scan manifest, and the dashboard opens. If the file has not changed since the last build, the scan reports that the graph is already up to date.
- Phase 1: deterministic fetch and parse
- Phase 2: agent enrichment in batches
- Phase 3: merge and validate
- Phase 4: clean up, summarise and launch the dashboard
- To force a full rebuild, set UNDERSTAND_FIGMA_FORCE=1 before running
UNDERSTAND_FIGMA_FORCE=1Safety notes: scripts, network and your token
This skill runs scripts (figma-scan.mjs and figma-merge.mjs) and makes outbound requests to api.figma.com. Unlike the code-focused version of the tool, it is not fully offline. The token is read only from the environment and is sent only in the X-Figma-Token request header. The skill is written so the token is never written to the graph, meta.json, logs or intermediate files.
The graph is stored in your project folder. If the Figma file is confidential or unreleased, treat the output folder as sensitive and avoid sharing it carelessly.
- Use a token you are comfortable giving this tool access to
- Review the scripts before installing if your organisation requires it
- Do not commit the output folder to a shared repository by accident
- Remember that the skill sends requests to Figma's servers
What people use it for
- Auditing how a large Figma file is organised into pages and screens
- Listing which components, component sets and instances a design system uses
- Reviewing design tokens such as colours and type styles before a front-end build
- Onboarding a new team member to an unfamiliar Figma file
Frequently asked questions
Is the understand-figma skill free?
The source material for this page does not state pricing or licence terms beyond the listed MIT licence of the repository. Check the repository's licence file for the terms that apply, and note that you need your own Figma personal access token.
What do I need to install understand-figma?
You need Node.js 22 or newer, pnpm 10 or newer, a FIGMA_TOKEN environment variable holding a Figma personal access token, and network access to api.figma.com. The understand-anything core package must also be built in the plugin folder.
Where do I get a Figma access token?
Create a personal access token at figma.com/settings, then export it as FIGMA_TOKEN in your shell before running the skill.
Where do I install the skill?
Unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. In the Claude apps, upload the ZIP under Settings → Capabilities → Skills.
Does this skill send my Figma data anywhere?
The skill makes outbound requests to api.figma.com to read the file. The source says the token is only sent in the X-Figma-Token header and is not written to the graph, logs or intermediate files. The graph itself is stored in your project folder.
How is this different from the code-focused understand skill?
The understand-figma skill reads a Figma file through the network, while the code-focused version is fully offline. It produces a kind:"design" dashboard for pages, components and tokens rather than a code graph.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you are a designer, design lead or front-end developer who needs a structured map of a large Figma file and has a Figma personal access token and the required Node and pnpm versions. Skip it for quick questions about one frame, for confidential files you cannot keep in a project folder, or if you need a fully offline tool.
Download the skill