Agent skill

Io Figma

by gridaco in gridaco/grida

Guides work on the Figma I/O package (@grida/io-figma, packages/grida-canvas-io-figma/).

Apache-2.0Auto-check: notesBackend & APIs

Install Io Figma

skills CLI
$ npx skills add gridaco/grida --skill io-figma -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install gridaco/grida io-figma --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/gridaco/grida.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/io-figma .claude/skills/io-figma && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
io-figma
GitHub stars
2.7k
Token cost
~2.2k tokens
SKILL.md length
636 words
Files
2 (incl. scripts)
Skills in repo
29
Repo updated
First seen
Licence
Apache-2.0

At a glance

Guides work on the Figma I/O package (@grida/io-figma, packages/grida-canvas-io-figma/).

  • Works in 3 steps: Find the property in fig-kiwi/schema.ts… → Add mapping in lib.ts under the relevant… → Add a test in tests/ against an existing…
  • Adding node type support
  • SKILL.md covers Architecture, fig2grida Input Formats, Key Files and References, plus 4 more sections
  • Runs Python scripts from its folder; calls pnpm, npx and python; needs FIGMA_TOKEN and X_FIGMA_TOKEN

What it does

Io Figma is an agent skill from gridaco/grida. Guides work on the Figma I/O package (@grida/io-figma, packages/grida-canvas-io-figma/). Covers the fig-kiwi binary parser, Kiwi→REST→Grida conversion pipeline, fig2grida CLI, REST API JSON conversion, and testing with clipboard/fig/REST fixtures. Use when adding node type support, fixing conversion bugs, extending fig2grida, working on the fig-kiwi parser, writing tests for Figma import, or debugging clipboard paste failures after a Figma update.

Its SKILL.md is about 2.2k tokens, which your agent loads only when the skill is triggered. The skill folder holds 2 other files, including scripts (for example `scripts/figma_archive.py`).

It sits in Backend & APIs, covering REST APIs. It works with Figma. The licence is Apache-2.0.

When your agent uses it

  • Adding node type support
  • Fixing conversion bugs
  • Extending fig2grida
  • Working on the fig-kiwi parser

Example prompts

  • “Use the io-figma skill to guide work on the Figma I/O package (@grida/io-figma, packages/grida-canvas-io-figma/)”
  • “/io-figma”

Requirements

  • Python 3
  • Node.js
  • A credential in FIGMA_TOKEN
  • A credential in X_FIGMA_TOKEN

Workflow steps

3 steps, taken from the first numbered list in SKILL.md.

  1. Find the property in fig-kiwi/schema.ts (Kiwi) or REST JSON in fixtures/test-figma/.
  2. Add mapping in lib.ts under the relevant iofigma.from* converter.
  3. Add a test in tests/ against an existing fixture.

What it can do on your machine

Read from SKILL.md and the folder at commit 165496f. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 1 file in scripts/ (Python), which the agent can run.

    Shell commands in SKILL.md call:

    • pnpm
    • npx
    • python

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Links to these hosts (documentation or services it may open):

    • github.com

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names these keys or tokens, usually read from environment variables:

    • FIGMA_TOKEN
    • X_FIGMA_TOKEN

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Io Figma loads about 2.2k tokens when it runs. Until then it costs about 115 tokens; SKILL.md has 636 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~115
When it runs · the whole SKILL.md, loaded when a task matches
~2.2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check: notes

The automated check noted patterns worth knowing about, such as sudo or a known installer.

  • NoteMentions a .env fileSKILL.md:112
    The root `.env` file is **not** a standard part of this project — it may
  • NoteMentions a .env fileSKILL.md:113
    ot exist on every machine. **Never read `.env` directly** (for security

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from gridaco/grida at commit 165496f, republished under its Apache-2.0 licence (© gridaco). 636 words, ~2,244 tokens.

Download SKILL.mdSave it as .claude/skills/io-figma/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.
name
io-figma
description
Guides work on the Figma I/O package (@grida/io-figma, packages/grida-canvas-io-figma/). Covers the fig-kiwi binary parser, Kiwi→REST→Grida conversion pipeline, fig2grida CLI, REST API JSON conversion, and testing with clipboard/fig/REST fixtures. Use when adding node type support, fixing conversion bugs, extending fig2grida, working on the fig-kiwi parser, writing tests for Figma import, or debugging clipboard paste failures after a Figma update.

Figma I/O — @grida/io-figma

Package: packages/grida-canvas-io-figma/

Architecture

text
.fig bytes / HTML clipboard
  → fig-kiwi parser       (fig-kiwi/)          low-level, zero-opinion
  → NodeChange[]          (Kiwi schema types)
  → iofigma.fromKiwi*()   (lib.ts)              Kiwi → Grida node

Figma REST API JSON
  → iofigma.fromRest*()   (lib.ts)              REST → Grida node

Orchestration:
  fig2grida-core.ts       — browser-safe: input detection, page loop, pack
  fig2grida.ts            — CLI wrapper (Node.js only, uses fs + process.argv)

Key invariant: The Kiwi path converts to REST format first (Kiwi → REST → Grida). lib.ts is the single source of truth for node conversion; it does not know the input origin.

Output: Grida format (.grida ZIP — FlatBuffers + images). See io-grida skill for format details, Rust loading, and round-trip testing.

fig2grida Input Formats

fig2grida(input) in fig2grida-core.ts auto-detects the input:

InputDetectionPath
.fig bytesZIP without document.json, or raw Kiwifig-kiwi parser
REST archive ZIPZIP containing document.json (+ optional images/)REST JSON path
REST JSON bytesStarts with {REST JSON path
REST JSON objectNon-Uint8Array objectREST JSON path

The REST JSON path (extractCanvases) accepts multiple response shapes:

  • { document: { type: "DOCUMENT", children: [CANVAS, …] } } — full GET /v1/files/:key
  • { document: { type: "CANVAS", children: […] } } — single-page node fetch
  • { nodes: { "id": { document: … }, … } } — GET /v1/files/:key/nodes?ids=…
  • { type: "DOCUMENT", children: … } — document node directly
  • { type: "CANVAS", children: … } — single CANVAS node
  • { children: […] } — bare object with children

Public APIs (both in fig2grida-core.ts):

  • fig2grida(input, options?) → .grida ZIP bytes (Fig2GridaResult)
  • restJsonToGridaDocument(json, options?) → in-memory Document + assets (no ZIP packing)

Key Files

FileRole
lib.tsAll iofigma.from* converters (Kiwi→REST and REST→Grida)
fig2grida-core.tsOrchestrator (.fig, REST JSON, REST ZIP)
fig2grida.tsCLI entry point (Node.js only)
fig-kiwi/index.tsLow-level parser public API
fig-kiwi/blob-parser.tsVector network + commands blob decoding
fig-kiwi/schema.tsKiwi type definitions (NodeChange, Message, …)

References

PathWhat
.ref/figma/Kiwi schema (fig.kiwi, fig.kiwi.d.ts), extraction tool (fig2kiwi.ts), Figma REST & Plugin API typings
docs/wg/feat-fig/glossary/fig.kiwi.mdDeep-dive: node types, vector blob format, GROUP/FRAME detection, text/font mapping
packages/grida-canvas-io-figma/README.mdFeature matrix, limitations, usage

Common Tasks

Add support for a new Figma property
  1. Find the property in fig-kiwi/schema.ts (Kiwi) or REST JSON in fixtures/test-figma/.
  2. Add mapping in lib.ts under the relevant iofigma.from* converter.
  3. Add a test in __tests__/ against an existing fixture.
Debug a clipboard paste failure

Clipboard issues = Figma changed their Kiwi schema.

  1. Save the failing HTML clipboard as a fixture.
  2. Run readHTMLMessage(html) → inspect raw Message.
  3. Diff parsed NodeChange[] against fig-kiwi/schema.ts.
  4. Update schema.ts (field changes) or blob-parser.ts (blob layout changes).
Run fig2grida
sh
pnpm --filter @grida/io-figma fig2grida input.fig
npx tsx packages/grida-canvas-io-figma/fig2grida.ts input.fig --pages 0,2
npx tsx packages/grida-canvas-io-figma/fig2grida.ts input.fig --info
Figma API token

figma_archive.py requires a Figma Personal Access Token. The script checks FIGMA_TOKEN then X_FIGMA_TOKEN env vars, or accepts --x-figma-token on the CLI. It fails fast with a clear error if none is set.

The root .env file is not a standard part of this project — it may not exist on every machine. Never read .env directly (for security reasons). Instead, if a token is needed and not already in the environment, ask the user to provide one and have them export it:

sh
export FIGMA_TOKEN=figd_...
Show full SKILL.md (225 more words)Show less
Create REST API fixtures

Use scripts/figma_archive.py. See the script header for full documentation, output layout, and --export behaviour.

sh
python .agents/skills/io-figma/scripts/figma_archive.py \
  --filekey <KEY> --archive-dir fixtures/test-figma/community/<name>

# With oracle PNGs (nodes must have export presets in Figma)
python .agents/skills/io-figma/scripts/figma_archive.py \
  --filekey <KEY> --archive-dir fixtures/test-figma/rest-api/local/<name> --export
Refig — correctness testing against Figma's renderer

For end-to-end correctness of the Figma import pipeline (does our Grida render of a Figma file match Figma's own render?), use the refig flow: oracle PNGs from Figma's Images API + @grida/reftest (developed in the engine repo: https://github.com/gridaco/nothing/tree/main/packages/grida-reftest) for the diff/score/report. Suites live in the engine repo's gitignored local corpus (fixtures/local/refig/<name>.<filekey>/ — local-only, machine-local by definition). See the engine repo's render-reftest skill, section "Figma — the refig reftest pipeline": https://github.com/gridaco/nothing/blob/main/.agents/skills/render-reftest/SKILL.md.

When debugging a conversion bug with a visible visual symptom, run the refig suite to locate the diverging nodes, then drill into lib.ts for the specific node type or property.

Tests

sh
pnpm --filter @grida/io-figma test                              # all
pnpm --filter @grida/io-figma test -- __tests__/iofigma.kiwi.test.ts  # specific
Test fileCovers
iofigma.kiwi.test.tsKiwi clipboard → Grida
iofigma.kiwi.fig.test.ts.fig file parsing
iofigma.kiwi.vector-network.test.tsVector network blob decoding
iofigma.kiwi.clipboard-overrides.test.tsComponent instance overrides
iofigma.kiwi.clipboard-components.test.tsComponent / instance clipboard
iofigma.kiwi.clipboard-text-overrides.test.tsText style overrides
iofigma.rest-api.no-geometry.test.tsREST API (no geometry)
iofigma.rest-api.vector.test.tsREST API vector paths
fig2grida.test.tsEnd-to-end pipeline
fig-kiwi/__tests__/Low-level parser units

Fixtures: fixtures/test-figma/rest-api/ (committed REST JSON), fixtures/test-figma/community/ (archived files), fixtures/local/ (gitignored, manual testing).

Known Limitations

  • Component sets, FigJam nodes (STICKY, CONNECTOR, TABLE) not supported
  • characterStyleOverrides / styleOverrideTable partially mapped from Kiwi
  • Style/variable bindings not preserved
  • Kiwi is undocumented — can break after Figma updates

Check the README's limitations section before writing new code. If lifting a limitation, update the README.

Verification

sh
pnpm turbo typecheck --filter='./packages/grida-canvas-io-figma'
pnpm turbo test --filter='./packages/grida-canvas-io-figma'

© gridaco, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 1 other file (scripts) in .agents/skills/io-figma of gridaco/grida.

  • SKILL.md
  • scripts/figma_archive.py

Open the folder on GitHubat commit 165496f

Compare with similar skills

Io Figma next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Io Figma compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Io Figma this skillgridaco/grida2.7k—~2.2kAutomated safety check: NotesApache-2.0
Figma Explorebitovi/ai-enablement-prompts121—~1.1kAutomated safety check: NotesMIT
Figma Comment Fix Loophashgraph-online/awesome-codex-plugins1.2k—~4.8kAutomated safety check: PassMIT
Figma To StaticLeoYeAI/openclaw-master-skills2.2k—~7.1kAutomated safety check: PassMIT
RuView CLI, API and WASMruvnet/RuView97k—~1.2kAutomated safety check: NotesMIT
REST API Contract Reviewdecebals/claude-code-java7501 repos~2.8kAutomated safety check: PassMIT

Similar skills

  • Figma Explore

    bitovi/ai-enablement-prompts

    Explore a Figma file to discover all pages, components, and component sets using the Figma REST API.

    121 GitHub stars~1.1k tokensUpdated 26 days ago
    Backend & APIsAuto-check: notes
  • Figma Comment Fix Loop

    hashgraph-online/awesome-codex-plugins

    Comment-to-fix pipeline for Figma. An agent skill from hashgraph-online/awesome-codex-plugins.

    1.2k GitHub stars~4.8k tokensUpdated today
    Backend & APIsAuto-check passed
  • Figma To Static

    LeoYeAI/openclaw-master-skills

    Convert Figma design files to pixel-level mobile-first static HTML/CSS pages.

    2.2k GitHub stars~7.1k tokensUpdated 2 mo ago
    Frontend & DesignAuto-check passed
  • Covers the RuView `wifi-densepose` command line binary, its Axum REST API and the WebAssembly builds for browsers and ESP32, for embedding or scripting RuView.

    97k GitHub stars~1.2k tokensUpdated today
    Backend & APIsAuto-check: notes
  • REST API Contract Review

    decebals/claude-code-java

    Reviews REST API design for correct HTTP verbs, versioning, DTO use, consistent responses and backward compatibility before an API change ships.

    750 GitHub starsUsed in 1 repo~2.8k tokens
    Backend & APIsAuto-check passed
  • Sleek Design Mobile Apps

    sleekdotdesign/agent-skills

    Design mobile app screens with Sleek, edit Sleek projects, and implement their designs in React Native or HTML.

    583 GitHub stars~2.1k tokensUpdated 2 days ago
    MobileAuto-check passed

More from gridaco/grida

All 29 skills in this repo
  • Desktop

    gridaco/grida

    Grida Desktop Electron shell and release-impact work: BrowserWindow, preload, window.grida, menus, protocol/deep links, file associations, Forge, path-scoped bridge security, Electron-only UI bugs…

    2.7k GitHub stars~3.2k tokensUpdated yesterday
    Auto-check: notes
  • Opt Library

    gridaco/grida

    Set up, download, verify, and seed the optional Grida Library developer corpus into local Supabase.

    2.7k GitHub stars~1.4k tokensUpdated yesterday
    Auto-check passed
  • Vision

    gridaco/grida

    Query images with a local Ollama vision model without loading the image into the main agent context.

    2.7k GitHub stars~1.5k tokensUpdated yesterday
    Auto-check passed
  • AI Models

    gridaco/grida

    Research, compare, and update shared AI model JSON for TypeScript, web, and Rust consumers.

    2.7k GitHub stars~5.7k tokensUpdated yesterday
    Auto-check passed
  • Agent System

    gridaco/grida

    Grida AI agent system work: @grida/daemon (DaemonServer, loopback HTTP perimeter, files/workspaces, secrets store, daemon discovery) and @grida/agent (the agent tenant: sessions, providers/BYOK…

    2.7k GitHub stars~3.4k tokensUpdated yesterday
    Auto-check passed
  • Database

    gridaco/grida

    Use BEFORE editing any file in supabase/migrations/ or supabase/schemas/, OR when the user runs a /database subcommand (compact local migration, rls scenarios, align).

    2.7k GitHub stars~3.2k tokensUpdated yesterday
    Auto-check passed

Works with

Questions about Io Figma

What does Io Figma do?

Guides work on the Figma I/O package (@grida/io-figma, packages/grida-canvas-io-figma/). Io Figma is an agent skill from gridaco/grida. Guides work on the Figma I/O package (@grida/io-figma, packages/grida-canvas-io-figma/).

When should I use Io Figma?

Io Figma fits situations like: adding node type support; fixing conversion bugs; extending fig2grida; working on the fig-kiwi parser.

How do I install Io Figma in Claude Code?

Run `npx skills add gridaco/grida --skill io-figma -a claude-code`. Or copy the skill folder (.agents/skills/io-figma in gridaco/grida) into .claude/skills/io-figma in your project. Claude Code loads it when a task matches its description.

How do I install Io Figma in Codex?

Run `npx skills add gridaco/grida --skill io-figma -a codex`. Or copy the skill folder (.agents/skills/io-figma in gridaco/grida) into .agents/skills/io-figma in your project. Codex loads it when a task matches its description.

Can I use Io Figma in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add gridaco/grida --skill io-figma -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/io-figma, .gemini/skills/io-figma, .github/skills/io-figma and .opencode/skills/io-figma in your project.

What does Io Figma need to run?

Going by SKILL.md and its folder, Io Figma needs Python for the scripts in its folder, the command-line tools its instructions call (pnpm, npx and python) and credentials named FIGMA_TOKEN and X_FIGMA_TOKEN. Our summary lists: Python 3; Node.js; A credential in FIGMA_TOKEN; A credential in X_FIGMA_TOKEN.

Does Io Figma access the network?

SKILL.md names 1 domain. As links in the text: github.com. This is read from the text; nothing was executed.

Is Io Figma safe to install?

Our automated static check of SKILL.md found notes only (mentions a .env file), nothing it rates as a warning. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Io Figma use?

Io Figma is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Io Figma use?

About 2.2k tokens (SKILL.md is roughly 9k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Io Figma?

Skills that share tags, products or a category with Io Figma: Figma Explore (bitovi/ai-enablement-prompts, 121 stars), Figma Comment Fix Loop (hashgraph-online/awesome-codex-plugins, 1.2k stars), Figma To Static (LeoYeAI/openclaw-master-skills, 2.2k stars) and RuView CLI, API and WASM (ruvnet/RuView, 97k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Io Figma?

gridaco (a GitHub organization) maintains it in gridaco/grida, which has 2,657 GitHub stars. The repository holds 29 skills in this directory. The repository was last updated on October 6, 2026.

Source: gridaco/grida on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.