Figma Maxxing

Agent skills for real Figma files. Your agent checks the file before it writes, reads back what it changed, and flags what the handoff is missing.

8 skills · 90 gotchas · a handoff gate with 17 checks

Leia em português · Quick start · Install · Skills · Gotchas

Quick start

Install the skills:

npx skills add thiagoxikota/figma-maxxing

Connect your agent to Figma through Figma's official MCP server or figma-console-mcp (setup). Then paste a frame link and ask: "Is this frame ready for handoff?"

You need a coding agent that loads skills (Claude Code, Codex, Cursor, Copilot CLI or Gemini CLI) and Node.js for npx. Installing into the Claude desktop or web app has not been tested. In those apps, or with no coding agent at all, paste a prompt into the chat and get a checklist instead.

If a rule caught something in your file, a star helps other designers find this.

Before and after

Blind test on Figma's official MCP server, 2026-10-05: 10 of 10 planted defects found, 0 missed. One agent built a demo screen with 10 planted defects and an answer key. A second agent, without the key, ran figma-slop-check and figma-handoff-gate. A third compared the audit with the key. The audit also flagged 14 problems nobody planted. After one fix pass, figma-slop-check went from 16 findings to 6, but neither check passes yet. There is also a 9-second animation.

The markers, how the test ran, and its limits

The markers point at the first 8 items of the figma-slop-check punch list, in the run's own words:

1. WCAG: upsell card body below the contrast and size floor
2. NAMING: default Figma name on the upsell card
3. NAMING: default Figma name on a divider
4. NAMING: default Figma names on the meta icon
5. INSTANCE: detached copy of ListItem
6. TOKEN: title raw hex
7. ICON: hand-drawn person icon instead of Icon/User
8. RADIUS: summary card radius off the scale

I wanted to know if the checks find real problems, so I set up a blind test. One agent built a demo screen with 10 planted defects and wrote an answer key. A second agent, who never saw the key, ran figma-slop-check and figma-handoff-gate through Figma's official MCP server. Its prompt also told it what to inspect: bound variables, instances versus frames, spacing, radius, names and text bounds. A third agent, the judge, compared the punch list with the key.

10 of 10 planted defects found, 0 partial, 0 missed. The punch list had 27 items: 16 from figma-slop-check and 11 from figma-handoff-gate. Of those, 13 match a planted defect (some defects show up in more than one item). The other 14 are problems nobody planted. None of them contradicted the key or the screenshots, though 2 could not be checked without opening the file, and the judge did not open it. One of the 14 is a contrast failure the answer key itself missed.

Then a fourth agent ran figma-preflight, fixed the screen and read back every property it changed. Both checks ran again, and neither passes yet:

• figma-slop-check: 16 findings down to 6, 1 of them critical (no focus state anywhere). Of the 6 left, 2 carry over from the first audit, 2 were already on the screen but the first audit did not report them, and 2 came from the fix itself.
• figma-handoff-gate: 11 issues up to 13 (8 blockers), mostly flows and states the fix pass did not draw.

Real screenshots from the official Figma MCP, 2026-10-05, on a demo file built for the test. The agent that planted the defects had read these skills, and the auditor's prompt pointed at the properties where most of them sat. So the test shows the checks fire on a real file, not that they catch everything. works-with.md lists the tool calls and what the official server could not do.

Paste this into your AI

No install needed. Copy this into the AI you use (Claude, ChatGPT, Gemini, Cursor) and fill in the brackets.

Read and use this file as reference:
https://raw.githubusercontent.com/thiagoxikota/figma-maxxing/main/llms.txt
If you cannot open it, tell me and do
not guess.
I am a designer. I [do / do not] have
an AI agent connected to Figma.
My context: [Figma plan, whether my
files have a design system, solo or
team].
Pick at most five rules for my work.
For each one, give me one check I can
do in Figma today. Then tell me
whether any skill is worth installing
for me.

What goes wrong, and what catches it

• The agent draws an icon your library already has → figma-preflight searches first.
• "Done," says the agent, and nothing changed → read-back rules in figma-preflight.
• Raw hex, default layer names, a detached row → figma-slop-check.
• The handoff shows "add" and never "remove" → figma-handoff-gate.
• You work through the comments one by one, by hand → figma-comment-fix-loop.
• The bridge dropped again → figma-bridge-doctor.

The skills

• figma-canon · The rules and the gotchas. Loaded piece by piece, only what the task needs.
• figma-preflight · Before every write. Approves the write or returns a fix list, and never touches the canvas.
• figma-orient · First contact with a file. Maps pages, components and variables, and saves the map.
• figma-slop-check · After a write. Finds machine-made tells and values that drift off your scales and tokens.
• figma-handoff-gate · Before a handoff. Every action needs a destination and a way back.
• figma-comment-fix-loop · When feedback arrives. Turns open comments into fixes, with evidence for each one.
• figma-click-flow · "Turn this into a flow." Draws arrows from tappable elements to their screens.
• figma-bridge-doctor · The figma-console bridge dropped. Diagnoses and repairs it (macOS scripts).

How they fit together

A few gotchas

• Writes under a locked parent fail in silence. The layer says locked: false, the editor refuses anyway, and nothing throws.
• instance.resize() leaves the icon at full size inside a small box. Use rescale().
• New sections come out black, though their fill is bound to a color variable. A section renders the base color you passed when binding, not the variable. Resolve the variable first, then bind.
• setTimeout never fires in the plugin sandbox. A timeout guard built on it guards nothing.
• Changing action on a prototype reaction does nothing. Figma reads actions, and the call still returns success.

Every gotcha, indexed by symptom, in the words a designer would use, plus a list by error message.

Why this, if Figma has official skills

Figma's own skills help an agent create things in Figma. The skills here check the agent's work before and after each write, and again at handoff. Use both. landscape.md maps the servers and skill sets around Figma, with dates.

• figma-console bridge: all 8 skills, in my own production work.
• Official Figma MCP: figma-preflight, figma-slop-check and figma-handoff-gate ran there once, in the blind test above. figma-orient, figma-comment-fix-loop and figma-click-flow describe that path and have not run on it yet. figma-bridge-doctor does not apply.

Skill by skill: works-with.md.

Install for your agent

npx skills add thiagoxikota/figma-maxxing covers most agents. The skills CLI is a third-party tool that sends anonymous install counts; DISABLE_TELEMETRY=1 turns that off.

Every route below, except Cursor's plugin folder, ran on 2026-10-05 from a local copy of this release in a clean test folder, and each one installed the 8 skills. I ran them before publishing this release, so I installed from a local path, not from the GitHub paths shown here.

Claude Code

/plugin marketplace add thiagoxikota/figma-maxxing
/plugin install figma-maxxing@figma-maxxing-skills

Skills show up as /figma-maxxing:figma-preflight and so on. The plugin ships skills only: no hooks, no MCP server. The skill descriptions cost about 1,200 tokens in every session (claude plugin details, Claude Code 2.1.289).

Codex

codex plugin marketplace add thiagoxikota/figma-maxxing
codex plugin add figma-maxxing@figma-maxxing-skills

Ran with codex-cli 0.156.1.

GitHub Copilot CLI

copilot plugin marketplace add thiagoxikota/figma-maxxing
copilot plugin install figma-maxxing@figma-maxxing-skills

Ran with Copilot CLI 1.0.61.

Gemini CLI

gemini extensions install https://github.com/thiagoxikota/figma-maxxing

Ran from a local path with Gemini CLI 0.43.0, which asks you to trust the folder first.

Cursor (not tested)

I do not have Cursor installed, so this route has not run. According to its docs, Cursor reads .cursor-plugin/plugin.json. To try it, copy the repository to ~/.cursor/plugins/local/figma-maxxing and reload the window. Or use the skills CLI:

npx skills add thiagoxikota/figma-maxxing -a cursor

OpenCode, Windsurf and other agents

npx skills add thiagoxikota/figma-maxxing -a opencode
npx skills add thiagoxikota/figma-maxxing -a windsurf

-a also takes codex, cursor, gemini-cli, github-copilot and claude-code. Add -g to install in your home folder. In a test, the CLI wrote the 8 skills to .agents/skills (.windsurf/skills for Windsurf, .claude/skills for claude-code). The agents themselves were not run.

Manual copy

git clone https://github.com/thiagoxikota/figma-maxxing.git
cd figma-maxxing
python3 install.py --scope user --dry-run

--dry-run shows what would be copied. Then run one of these two lines, not both:

• python3 install.py --scope user installs for Claude Code in ~/.claude/skills.
• python3 install.py --target agents --scope user installs in ~/.agents/skills, for Codex, Cursor, Gemini CLI and others.

The installer copies folders and refuses to overwrite a skill that already exists.

What you need

The skills need an agent that loads Agent Skills and a connection to Figma. There are two ways to connect.

Figma's official MCP server. The simpler one to set up. In Claude Code:

claude mcp add --transport http figma https://mcp.figma.com/mcp

For other agents, see Figma's guide. Writes through use_figma need a Full seat, except in your own drafts, where Figma's MCP server FAQ also lets a Dev seat write. On a Starter plan the call budget is small (field note). Using it means agreeing to the Figma Developer Terms.

figma-console-mcp by Southleft (MIT). The route I use in my own work, and the one these skills were built on. It runs on your machine and reaches Figma Desktop (macOS or Windows) through its Desktop Bridge plugin. You need Node.js 18 or newer and a Figma personal access token. Last checked against v1.40.8. In Claude Code:

claude mcp add figma-console -s user \
  -e FIGMA_ACCESS_TOKEN=figd_YOUR_TOKEN_HERE \
  -e ENABLE_MCP_APPS=true \
  -- npx -y figma-console-mcp@latest

1. Restart Claude Code. The first start creates the plugin manifest.
2. In Figma Desktop, open a file and go to Plugins, Development, Import plugin from manifest. Pick ~/.figma-console-mcp/plugin/manifest.json (~ is your home folder).
3. Run the Figma Desktop Bridge plugin in the file you want to work on.
4. Ask your agent: "check the Figma connection". It should call figma_get_status.

That command writes the token in plain text to your agent's config, and the command itself, token included, may stay in your shell history. Treat the config and the history as secrets, and never commit either. For other agents, follow the upstream guide.

For the comment workflow, on either server: a personal access token with File content (read), File versions (read), Variables (read) and Comments (read and write). figma-comment-fix-loop reads comments through the REST API.

The skills are plain Markdown and run wherever your agent runs. The bridge recovery scripts are macOS only. This repository and figma-console-mcp are free; your agent and your Figma plan are not.

The optional hook

hooks/figma-canon-precheck.py reads the script your agent is about to run in Figma and warns about 13 known problem patterns before the call reaches Figma. It is never installed automatically. To turn it on in Claude Code, add this to your settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__figma-console__figma_execute(_across_files)?",
        "hooks": [
          {
            "type": "command",
            "command": "python3 /path/to/figma-maxxing/hooks/figma-canon-precheck.py",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

By default it only warns. With FIGMA_PRECHECK_MODE=block it refuses the 5 patterns marked BLOCK, the ones that break the call. The matcher above fires only on the figma-console bridge; the hook has not been tried on the official server's use_figma.

Safe on a team library

• Read-only. figma-canon, figma-preflight and figma-orient never change the canvas. figma-orient saves its map in your project, not in the file.
• Report first. figma-slop-check and figma-handoff-gate change nothing until you approve each fix.
• Comments are data. figma-comment-fix-loop shows the comments it will act on and waits for your yes. It never follows instructions written in a comment.
• Draft first. figma-canon tells the agent to work in a draft or a branch until you approve, unless you say otherwise. It is an instruction, not a check: nothing blocks a write to a shared library, so tell the agent which draft to use.
• One file, several agents. Before a write, figma-preflight claims an advisory file lock, so two sessions do not write to the same file at once. Sessions agree on the lock; Figma does not enforce it.
• Nothing in the background. The plugin ships no hooks and no MCP server. The bridge watchdog and the mcp-direct daemon start only when you say so.
• No telemetry. The repository collects nothing: PRIVACY.md. Security notes and private reports: SECURITY.md.

How this is verified

Every push runs test.yml:

• Unit tests for the lock, the hook, the installer, links and privacy patterns, on Ubuntu and macOS with Python 3.10 and 3.13.
• Every Plugin API name the skills cite, checked against @figma/plugin-typings 1.140.0: 0 errors today. On the tree before commit 1dca321 (the annotations fix), the same check fails with 3.
• Every skill, gotcha and check count the docs cite, recounted from the files.
• The Agent Skills reference validator and the Claude Code plugin validator.
• Every link, anchors included (lychee).
• The full git history scanned for secrets (gitleaks), the workflows linted (actionlint), every action pinned to a commit SHA.

Every week, drift.yml runs the API check against the newest typings and opens an issue when a name breaks. scorecard.yml runs OpenSSF Scorecard.

A release (release.yml) builds one zip per skill and a plugin bundle from the tagged commit, builds them twice, fails if the bytes differ, and attaches a build provenance attestation. To check a download:

gh attestation verify figma-preflight-1.1.0.zip \
  --repo thiagoxikota/figma-maxxing

Outside this repository, the M8ven Trust Index scores it independently. New projects there are capped at C until adoption grows; the code itself scored 100 out of 100 on 2026-10-05.

How far this has been tested

As of 2026-10-05:

• My own work. I built these skills in Claude Code on macOS with figma-console-mcp, on real files. This public edition is a rewrite of that set: in English, generalized, with every client detail removed. It has not yet run end to end on a second machine.
• Official Figma MCP. The blind test above, on one demo screen. The audit took 12 Figma MCP calls, the fix pass 13, the second audit 13. Some steps had no tool or hit a limit there: no selection, no screenshot above 1x through get_screenshot, no bridge status, and a 20 KB cap on each call. The agents used read-only use_figma workarounds and logged each one in works-with.md.
• Installs. Every route in Install for your agent except Cursor, from a local copy.

If something still depends on my setup, open an issue with your environment and the exact error.

Contributing

A gotcha you hit yourself, with symptom, cause and fix, is the best contribution. Questions and before/after shots go to Discussions; bugs and gotchas to issues. See CONTRIBUTING.md, the code of conduct and the changelog. Working with an agent? Point it at AGENTS.md.

If a rule caught something in your file, a star helps other designers find this.

Who made this

I'm Thiago Xikota, AI Product Designer, founder of Xikota Design and researcher at Lemme (UFSC). I'm writing Design na era da IA (Casa do Código, in production). Follow me on LinkedIn.

Credits

Built on figma-console-mcp by Southleft. The skill format is the open Agent Skills standard.

Not affiliated with Figma. Figma is a trademark of Figma, Inc.

License

MIT. See LICENSE.