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

Test skills.sh License: MIT

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 items nobody planted (13 distinct problems: figma-slop-check and figma-handoff-gate flagged the same rename). 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:

WCAG: upsell card body below the contrast and size floor
NAMING: default Figma name on the upsell card
NAMING: default Figma name on a divider
NAMING: default Figma names on the meta icon
INSTANCE: detached copy of ListItem
TOKEN: title raw hex
ICON: hand-drawn person icon instead of Icon/User
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 items point at problems nobody planted: 13 distinct ones, because figma-slop-check and figma-handoff-gate flagged the same rename. 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 them 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 that the checks fire on a live Figma file built for the test, 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

Changing action on a prototype reaction does nothing. Figma reads actions, and the call still returns success.
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.
In one sweep through the figma-console bridge, writes under a locked group did not take. Nothing threw, and each layer read locked: false. Figma's typings say locked does not block plugin writes, so the cause is not established. A count after the sweep is what caught it.

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, on the demo file of the blind test above, with some steps adapted or skipped (the list). 1.1.0 changed detector 8 of figma-slop-check after that run. 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 ran on 2026-10-05 in a clean test folder, and each one installed the 8 skills at version 1.1.1. Claude Code, Codex, Copilot CLI and npx skills add thiagoxikota/figma-maxxing installed from GitHub main at commit 3693845, the commit tagged v1.1.1; Claude Code ran through the claude plugin CLI, the terminal form of the two slash commands. Gemini CLI installed the v1.1.1 release. -a opencode and -a windsurf ran earlier the same day from a local copy of the repository.

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 with Gemini CLI 0.43.0, which installed 1.1.1 from the latest GitHub release. It asks you to trust the folder and to confirm the install; --consent answers both, which is how the test ran.

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

Restart Claude Code. The first start creates the plugin manifest.
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).
Run the Figma Desktop Bridge plugin in the file you want to work on.
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.1.zip \
  --repo thiagoxikota/figma-maxxing

This repository has an entry in the M8ven Trust Index, claimed by the author himself. Its public grade is C (Emerging). The code sub-score was 100 out of 100, read on 2026-10-04 at commit 1dca321, before 1.1.0.

M8ven Score

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 GitHub main, the v1.1.1 release or a local copy, as listed there.

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.