agentleFS
dabowmandabowman/Figmagent/skills/figma-sub-agents/SKILL.md

figma-sub-agents

Skill0 starsChanged 2 months agoMITView on GitHub

Orchestrator guide for delegating Figma MCP phases to specialized sub-agents. Use when a Figma task is large enough to risk context overflow — component sets with 8+ variants, unknown tree depth, or sessions expected to exceed 100 tool calls. Supports both serial discovery and parallel build/style phases.

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Orchestrator joins the channel first: Call use_file (no args) before spawning any sub-agent.

    line 44
  2. Distinctive:

    Don't mix phases: Don't run a Builder and Styler in parallel — build everything first, then style everything.

    line 68
  3. Very specific:

    Verify after parallel phases: After all parallel agents complete, call read(nodeId, detail="structure") on the parent to confirm the …

    line 71
  4. Very specific:

    Use the Agent tool with subagent_type: "figma-discovery".

    line 110
  5. Very specific:

    Post-session: After completing a large Figma session (50+ tool calls), run /analyze-session to capture efficiency metrics, error patterns, …

    line 366

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Figma MCP Sub-Agent Orchestration

Large Figma sessions hit three problems in a single-agent context: context pressure (large node tree responses), attention drift (losing track of which nodes are done after 30+ sequential calls), and error pollution (9 retries of a failing tool consuming planning context). Sub-agents solve this by giving each phase its own clean context window.

The primary tool for reading nodes is read, which returns structured YAML (FSGN format) with deduplicated variable/style/component defs and a tokenEstimate in the meta. It accepts nodeId (single) or nodeIds (multiple, fetched in parallel).

Sub-agents also enable parallel execution — on the plugin transport only: multiple agents can modify different parts of the Figma document simultaneously, with plugin-level concurrency control ensuring safety. On the remote transport (FIGMA_TRANSPORT=remote) the MCP server serializes every command per file (FIFO queue), so parallel sub-agents do NOT increase throughput. Sub-agents still pay off on remote for context isolation — just launch Build/Style agents serially instead of in parallel.

Available sub-agents:

  • Discovery (figma-discovery agent) — read-only exploration, always runs serial
  • Builder (general-purpose agent) — creates/clones node structures, can run in parallel
  • Styler (general-purpose agent) — applies variables and text styles, can run in parallel

When to Use Sub-Agents

Discovery — delegate when any of these are true:

  • Target component set has 8+ variants
  • Frame tree depth is unknown or likely > 4 levels
  • This is the first time seeing this Figma file in the session
  • A read response has tokenEstimate > 8000 even at detail=structure
  • You need both a full text node inventory AND a variable binding audit in the same pass

Skip it when you already have the node IDs and structure, the target has < 20 children, or you only need one piece of info (just call the tool directly).

Builder/Styler — delegate when:

  • Build spec has 5+ nodes to create or clone
  • Binding plan has 20+ variable bindings or text style assignments
  • Work can be partitioned into independent node subtrees (different variants, different sections)
  • You want to parallelize to reduce wall-clock time (plugin transport only — remote serializes per file)

Execution Protocol

Channel Setup (always do this first)

  1. Orchestrator joins the channel first. Call use_file (no args) before spawning any sub-agent.
  2. Pass the channel name explicitly in every sub-agent prompt. Do not let sub-agents auto-discover — this avoids race conditions. (Remote transport: there are no channels — use_file takes a Figma URL or fileKey; pass that same fileKey to every sub-agent.)
  3. Check status first in every sub-agent result — if "blocked", surface the error to the user and stop.

Serial Phases (must be in order)

Discovery → Planning → Building → Styling → Verification

Discovery always runs alone. Planning happens in the orchestrator. Verification happens in the orchestrator.

Parallel Execution (within Building or Styling phases — plugin transport only)

The Figma plugin has concurrency control that makes parallel agent execution safe:

  • Node-level write locks prevent two agents from writing to the same node simultaneously
  • Global mutex serializes tree-mutation operations (the create, delete_multiple_nodes, etc. wire commands)
  • Concurrency cap (max 6 in-flight operations) prevents Figma CPU budget exhaustion

Remote transport: none of this applies — the server's per-file FIFO queue serializes every command, so parallel agents just wait in line. On remote, run Build/Style agents one at a time and keep the partitioning (it still bounds each agent's context).

Rules for parallel sub-agents:

  1. Partition by node subtree. Each agent operates on a disjoint set of nodes. Partition by variant, by section, or by component — never assign the same node to two agents.
  2. Don't mix phases. Don't run a Builder and Styler in parallel — build everything first, then style everything. The Styler needs the nodes to exist before it can bind variables.
  3. Use run_in_background: true on the Agent tool to launch parallel agents. You will be notified when each completes.
  4. All agents share one channel. Sub-agents share the parent's MCP server and WebSocket connection. Request ID correlation handles response routing — no multi-channel needed.
  5. Verify after parallel phases. After all parallel agents complete, call read(nodeId, detail="structure") on the parent to confirm the expected structure.
  6. Max 3 parallel agents for build/style phases. More than 3 creates diminishing returns and risks hitting the plugin's concurrency cap (6 in-flight operations, ~2 per agent).

Partitioning Strategies

By variant (most common): Each agent handles a disjoint set of variants within a component set.

Agent A: Build/style variants for State=Loading  (nodes A1-A5)
Agent B: Build/style variants for State=Empty    (nodes B1-B5)
Agent C: Build/style variants for State=Selection (nodes C1-C5)

By section: Each agent handles a different top-level section of the page.

Agent A: Build Header component set
Agent B: Build Sidebar component set
Agent C: Build Footer component set

By operation type (for styling): Each agent handles a different type of binding.

Agent A: Bind all color variables
Agent B: Apply all text styles
Agent C: Bind all spacing/radius variables

Note: this only works if each node gets only ONE type of binding per agent. If a node needs both a color variable and a text style, assign that node to ONE agent that does both.


Discovery Sub-Agent

The agent definition ships in this plugin at agents/figma-discovery.md. It has:

  • A read-only tool set (no create/modify tools)
  • A system prompt with its full workflow and output schema

Tools available to the agent: use_file, read, grep, get_local_components, get_design_system. All tools are declared in the agent definition and loaded automatically — no ToolSearch needed. Note: read includes component metadata in defs.components, and get_design_system covers both variables and styles.

Spawning the Agent

Use the Agent tool with subagent_type: "figma-discovery". The prompt only needs task-specific parameters — no system prompt needed.

Agent(
  subagent_type: "figma-discovery",
  description: "Discover <component name> structure",
  prompt: JSON.stringify({
    channelName: "<from your use_file call>",
    nodeId: "<target component set or frame ID>",
    description: "Map DataViews component set",
    include: ["text_nodes", "variables", "text_styles"],
    nameFilter: "DataRow"   // omit if not filtering components
  })
)

Valid include values: text_nodes, variables, text_styles, components.

Using the Result

The agent's final message is JSON. Parse it immediately:

const discovery = JSON.parse(agentResult);

if (discovery.status === "blocked") {
  // Surface to user: discovery.error + discovery.recommendation
  // Do NOT proceed to build/style phases
} else {
  // discovery.component_set.variants[].id → parentId values for create/clone calls
  // discovery.component_sets_in_frame     → all component sets when target is a FRAME (pick one to deep-map)
  // discovery.text_nodes[]                → input for edit (variables, textStyleId)
  // discovery.unbound_nodes               → if >= 20, a Styler phase is needed; null = unknown
  // discovery.variables                   → sanity-check tokens are loaded
  // discovery.summary                     → user-facing status message
  //
  // Variant children now include:
  //   layoutMode       → auto-layout direction (if active)
  //   boundVariables   → list of bound field names (e.g. ["fill", "cornerRadius"])
  //   componentName/Id → resolved for INSTANCE nodes via defs.components in FSGN
}

Output Schema Reference

Success:

{
  "status": "success",
  "component_sets_in_frame": [
    { "id": "...", "name": "DataViews", "type": "COMPONENT_SET", "variantCount": 16 },
    { "id": "...", "name": "DataForm", "type": "COMPONENT_SET", "variantCount": 2 }
  ],
  "component_set": {
    "id": "...",
    "name": "...",
    "variant_properties": ["Layout", "State"],
    "variants": [
      {
        "id": "...",
        "name": "Layout=List, State=Default",
        "children": [
          { "id": "...", "name": "Header", "type": "FRAME", "layoutMode": "HORIZONTAL", "boundVariables": ["fill", "cornerRadius"] },
          { "id": "...", "name": "Row 1", "type": "INSTANCE", "componentName": "_Dataviews/Table/Row", "componentId": "2254:11156", "boundVariables": [] }
        ]
      }
    ]
  },
  "text_nodes": [
    { "id": "...", "name": "Title", "parentVariantId": "16547:36681", "content": "Activity", "style": "Heading MD", "fills_variable": null }
  ],
  "variables": {
    "collections": ["Primitives", "Semantic"],
    "total_count": 84,
    "by_collection": {
      "Semantic": [
        { "id": "VariableID:15613:5786", "name": "gray-700", "type": "COLOR" },
        { "id": "VariableID:15613:5784", "name": "surface-primary", "type": "COLOR" }
      ]
    }
  },
  "text_styles": [
    { "name": "Heading MD", "id": "S:5a04abc..." },
    { "name": "Body SM", "id": "S:7b12def..." }
  ],
  "unbound_nodes": 47,
  "summary": "4 variants exist. 47 nodes have no variable bindings. 12 text nodes have no text style."
}

Blocked:

{
  "status": "blocked",
  "error": "read timed out twice",
  "last_tool": "read",
  "recommendation": "Call use_file again — connection may have dropped"
}

Builder Sub-Agent

Creates or clones node structures. Uses general-purpose agent type (not a custom agent definition — the prompt contains all instructions).

Spawning

Agent(
  description: "Build [description] variants",
  run_in_background: true,  // for parallel execution
  prompt: `You are a Figma Builder agent. The WebSocket channel is already joined —
call use_file with channelName "${channelName}" as your first action.

YOUR ASSIGNED NODES (do NOT touch anything outside this list):
${JSON.stringify(assignedNodes)}

WHAT TO BUILD:
${buildSpec}

RULES:
- Use write for complex structures (reduces many calls to 1)
- Use write with fromNodeId when duplicating existing patterns
- Use write with type="INSTANCE" and componentId for reusing library parts
- write responses include the created structure plus a warnings block (100px balloons, FILL-not-applied, font fallback, overlaps) — act on warnings; only read(nodeId, detail="structure") back when warnings or the returned structure suggest a mismatch
- Return JSON: {"status": "success", "created_nodes": [...ids], "summary": "..."}
- If any tool fails twice on the same call, stop and return: {"status": "blocked", "error": "...", "last_tool": "...", "recommendation": "..."}
`
)

When to Parallelize Builders

  • Multiple independent variants to create (e.g., 4 State variants each with the same structure)
  • Multiple independent component sets to build
  • Large write specs that don't share parent nodes

Output

{
  "status": "success",
  "created_nodes": ["16547:36700", "16547:36701", "16547:36702"],
  "summary": "Created 3 Loading state variants with 4 children each"
}

Styler Sub-Agent

Applies variable bindings and text styles. Uses general-purpose agent type.

Pre-flight with read

Before spawning Styler agents, the orchestrator can call read(nodeId, detail="full") on the built subtree. The FSGN defs section lists all variables and styles already present; variableBindings on each node shows what's already bound. This makes the binding plan explicit — pass it directly to the Styler via VARIABLE BINDINGS TO APPLY.

Spawning

Agent(
  description: "Style [description] variants",
  run_in_background: true,  // for parallel execution
  prompt: `You are a Figma Styler agent. The WebSocket channel is already joined —
call use_file with channelName "${channelName}" as your first action.

YOUR ASSIGNED NODES (do NOT touch anything outside this list):
${JSON.stringify(assignedNodes)}

VARIABLE BINDINGS TO APPLY:
${JSON.stringify(bindings)}

TEXT STYLE ASSIGNMENTS:
${JSON.stringify(textStyles)}

RULES:
- Use edit() with variables field to bind design tokens to node properties (supports flat list or nested tree)
- Use edit() with textStyleId to apply text styles (deduplicates font loading automatically)
- Process in order: variable bindings first, then text styles
- edit responses report per-op failures and warnings (scope-mismatched binds are skipped with a warning) — act on those; spot-check ONE node with read(nodeId, detail="full") only if a result looks off
- Return JSON: {"status": "success", "bindings_applied": N, "styles_applied": N, "summary": "..."}
- If any tool fails twice on the same call, stop and return blocked status
`
)

When to Parallelize Stylers

  • 40+ bindings to apply across different node subtrees
  • Multiple variants that each need independent styling
  • Different sections of a page with no shared nodes

Binding Plan Format

The orchestrator prepares a binding plan from Discovery output and passes it to each Styler:

{
  "bindings": [
    { "nodeId": "16547:36700", "field": "fill", "variableId": "VariableID:15613:5786" },
    { "nodeId": "16547:36701", "field": "cornerRadius", "variableId": "VariableID:15613:5800" }
  ],
  "textStyles": [
    { "nodeId": "16547:36710", "styleId": "S:5a04abc..." },
    { "nodeId": "16547:36711", "styleId": "S:7b12def..." }
  ]
}

Output

{
  "status": "success",
  "bindings_applied": 22,
  "styles_applied": 8,
  "summary": "Applied 22 variable bindings and 8 text styles to Loading variants"
}

Parallel Session Example

TIME    ORCHESTRATOR              BUILDER-A             BUILDER-B
─────   ────────────              ─────────             ─────────
0:00    use_file
0:01    → Discovery agent
0:03    ← discovery JSON
0:04    Plan: partition by State
0:05    → Builder A (Loading)     write ──►
0:05    → Builder B (Empty)                             write ──►
        [both run_in_background]
0:07                              ◄── done              ◄── done
0:08    verify structure

TIME    ORCHESTRATOR              STYLER-A              STYLER-B
─────   ────────────              ────────              ────────
0:09    → Styler A (Loading)      edit ──►
0:09    → Styler B (Empty)                              edit ──►
        [both run_in_background]
0:11                              ◄── done              ◄── done
0:12    verify bindings
0:13    Report to user

Estimated speedup (plugin transport): For a 16-variant component set with 130+ variable bindings:

  • Serial: ~36 minutes
  • Parallel (3 agents): ~19 minutes (~1.9x speedup)

The speedup scales with workload size. Design system builds with 50+ components see larger gains because build and style phases dominate. On the remote transport expect NO parallel speedup (per-file FIFO) — the win there is fewer calls per task and context isolation.


Post-session: After completing a large Figma session (50+ tool calls), run /analyze-session to capture efficiency metrics, error patterns, and improvement recommendations.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.