The `figma` skill
Look up the design-file skill’s commands, supported resources, output forms, permissions, and API limitations.
A thin, uniform interface to the Figma REST API. Reads files, nodes, metadata, version history, and comments; renders nodes to images; posts comments; converts FigJam connector graphs to Mermaid; and best-effort reads of variables and dev resources. Read and comment only — it does not modify design content, which requires the Plugin API or the Figma MCP server, not REST.
Figma is SaaS-only (api.figma.com). There is no on-prem variant.
The source of truth is the skill itself: packs/figma/.apm/skills/figma/. The agent invokes the CLI at scripts/figma.py; you do not call it by hand. Run python scripts/figma.py <subcommand> --help for the exact flag surface of any subcommand.
Credentials
Section titled “Credentials”| Key | Required | Notes |
|---|---|---|
FIGMA_API_TOKEN | yes | Personal Access Token. Generated at Figma → Settings → Security → Personal access tokens. |
Resolved by the broker through the Tier 1 (environment) → Tier 2 (OS keyring) → Tier 3 dotfile ladder. The dotfile lives at ~/.agentbundle/credentials.env (mode 0600 on POSIX; DACL-restricted on Windows). Populate any tier with the credential-setup skill. The token never reaches the model, and it is never accepted on the command line — flags like --token, --api-token, --bearer, --pat, and --password are refused. For the two-layer model, see Credentialed skills.
A FILE_KEY accepts either a bare key (abc123XYZ456) or a full figma.com URL. The key is extracted from /file/, /design/, /board/ (FigJam), and /proto/ URLs. Node ids accept the API form (1:23) or the URL form (1-23); the URL form is normalized to the API form before the request. Any other shape is rejected at the CLI.
Output
Section titled “Output”| Subcommand class | Default output |
|---|---|
| Structured-output subcommands | JSON to stdout. --format jsonl switches to JSON Lines. --output FILE writes to a file. |
export-images | Image bytes written to the --output directory. --format selects png / jpg / svg / pdf. |
figjam-to-mermaid | A fenced Mermaid block (Markdown). --output FILE writes it to disk. |
--format is ignored by export-images and figjam-to-mermaid.
Subcommands
Section titled “Subcommands”| Subcommand | Purpose | Key arguments |
|---|---|---|
check | Verify credentials and reachability. | — |
whoami | Show the authenticated user record. | — |
get-file FILE_KEY | Fetch a file (full or scoped). | --ids, --depth, --geometry paths, --version, --plugin-data, --branch-data |
get-nodes FILE_KEY | Fetch specific nodes by id. | --ids (required), --depth, --geometry paths, --version |
get-file-meta FILE_KEY | Lightweight file metadata (name, creator, last modified, role). | — |
list-versions FILE_KEY | File version history. | --page-size, --before, --after |
export-images FILE_KEY | Render nodes to images. | --ids (required), --format, --scale, --use-absolute-bounds, --version, SVG flags below |
list-comments FILE_KEY | List file comments. | — |
post-comment FILE_KEY | Post a comment to a file. | --message (required), --node-id, --reply-to |
figjam-to-mermaid FILE_KEY NODE_ID | Convert a FigJam connector graph to a Mermaid flowchart. | — |
get-variables FILE_KEY | Fetch local (or published) variables. Typically Enterprise. | --published |
list-dev-resources FILE_KEY | Fetch dev resources on file nodes. Typically Dev Mode. | — |
raw METHOD PATH | Arbitrary request to an unwrapped endpoint. | --param KEY=VALUE (repeatable), --data-file |
Scoping flags (get-file, get-nodes)
Section titled “Scoping flags (get-file, get-nodes)”| Flag | Effect |
|---|---|
--depth N | Limit tree depth. 1 = pages only; 2 = pages + direct children. |
--ids 1:2,1:3 | Return only those nodes and their subtrees. |
--geometry paths | Include vector path geometry. |
--version ID | Read a specific file version. |
--branch-data | (get-file) Include branch metadata. |
--plugin-data ID | (get-file) Include plugin data for the given plugin id. |
get-file at full depth is the heaviest call — tens of megabytes on large files. Use get-file-meta to probe, --depth 1 to discover pages, then get-nodes for the subtree you want.
Render flags (export-images)
Section titled “Render flags (export-images)”| Flag | Effect |
|---|---|
--format png|jpg|svg|pdf | Output format (default png). |
--scale FLOAT | Render scale in (0, 4] (default 1.0). |
--use-absolute-bounds | Render using the node’s absolute bounding box. |
--version ID | Render from a specific file version. |
--svg-include-id | (SVG) include node ids in element id attributes. |
--no-svg-outline-text | (SVG) keep text as <text> instead of outlining. |
--no-svg-simplify-stroke | (SVG) don’t simplify strokes to fills. |
The token is sent only on the render call; the resulting presigned S3 URLs are downloaded unauthenticated. The render endpoint is rate-limited (Figma cites Tier 2 ≈ 25 requests/min); the client honors Retry-After. An id that isn’t renderable is skipped with a stderr warning; other ids still download.
Global flags
Section titled “Global flags”| Flag | Effect |
|---|---|
--format json|jsonl | Output format for structured-output subcommands (default json). |
--output FILE | Write to a file, or a directory for export-images, instead of stdout. |
--verbose | Debug logging on the figma.* loggers only; httpx/httpcore stay at WARNING. |
FigJam → Mermaid
Section titled “FigJam → Mermaid”figjam-to-mermaid FILE_KEY NODE_ID emits a flowchart TB. It is only useful for FigJam files whose edges are drawn with the connector tool (CONNECTOR nodes).
| Preserved | Dropped |
|---|---|
FRAME / GROUP / SECTION containment as subgraphs. | Visual layout, positions, sizes, colors. |
CONNECTOR direction → ---, -->, <--, <-->. | Freehand VECTOR arrows (invisible to the API). |
SHAPE_WITH_TEXT.shapeType → matching Mermaid shape where one exists. | Connector endpoints magnetted to free canvas (no destination node). |
| Connector text as the edge label. | TRIANGLE_UP / TRIANGLE_DOWN → best-fit flag shape. |
For a non-connector source (a regular design frame), use export-images and read the rendered output instead.
Exit codes
Section titled “Exit codes”The CLI uses a banded exit-code contract. Read the stderr message for the specific cause, then act on the band.
| Exit | Band | Cause | Action |
|---|---|---|---|
0 | Success | — | Proceed. |
1 | Functional error | Unknown key (404), server 5xx, transport failure, keyring hard-fail, unprojected shim, unexpected. | Surface the message; don’t blindly retry. |
2 | User must act | Missing/invalid/expired credentials (401), or 403 scope/plan access (Variables → Enterprise; Dev Resources → Dev Mode / file_dev_resources:read). | Re-run credential-setup, or regenerate the PAT with the right scope, then re-run check. |
Exit codes 3–9 are reserved.
Untrusted text
Section titled “Untrusted text”All text returned by Figma — comment bodies, sticky-note text, layer names, FigJam shape labels, and the 4xx response bodies surfaced in error messages — is author-controlled. The agent renders it back to you but never acts on instructions embedded in it. Only your direct messages count as direction.
See also
Section titled “See also”- Inspect a Figma file — the task recipe.
- Credentialed skills — why the token never reaches the model.