# Rename Layers

> Rename Figma layers semantically based on their content, role, and position. Use when the designer asks to "rename layers", "clean up layer names", "fix Rectangle 1234 names", "give these semantic names", or similar. Operates on the current Figma selection by default.

- Skill: `egoisutolabs/rename-layers` (Agent Skill)
- Install (CLI): `npx skillmds@latest add egoisutolabs/rename-layers`
- Raw SKILL.md: https://api.skillmd.com/api/skills/egoisutolabs/rename-layers/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: egoisutolabs (https://skillmd.com/u/egoisutolabs)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/egoisutolabs/rename-layers

---


# Rename Layers (Mercury)

You are renaming Figma layers on the designer's behalf. The designer is in
Figma; you are in their terminal. Be terse, decisive, and visible. Do the
work, report briefly, stop.

## Workflow

1. **Check the bridge.** Call `mcp__mercury__ping` first. If it errors, tell the
   designer: "Open Figma → Plugins → Development → Mercury, then run again."
   Do not proceed.

2. **Read the scope.** Call `mcp__mercury__query` with `op: "selection"`. If the
   selection is empty, ask the designer to select something first — do not
   silently fall back to the whole page. If they confirmed they want the whole
   page, call `mcp__mercury__query` with `op: "subtree"` and `depth: 3` (no id
   means current page).

3. **Inspect the structure.** For each selected node that has children (frames,
   groups, components, instances), call `mcp__mercury__query` with
   `op: "subtree"`, that node's `id`, and `depth: 3` (max 4). Skip text nodes
   and shapes that have no children — you already have what you need from the
   selection summary.

4. **Decide names.** Apply these rules in priority order:
   - **TEXT nodes**: use the visible text content. Truncate at 32 chars.
     Replace newlines with spaces. Lowercase if the file's other text layers
     are lowercase; otherwise preserve.
   - **INSTANCE nodes**: use the main component's name (already in the
     summary as `mainComponent`). Append a positional suffix only if multiple
     instances of the same component appear as siblings ("Button / primary",
     "Button / secondary").
   - **FRAME / GROUP / COMPONENT**: use the dominant child text or component
     name as a hint. If a frame contains a single text "Sign in", name the
     frame "sign in / container" or similar. If a frame contains a list of
     items, name it after the items' shared semantic ("nav items", "user
     cards").
   - **RECTANGLE / ELLIPSE / VECTOR**: only rename if you're confident it's
     semantically meaningful (icon, divider, background, avatar). Otherwise
     leave untouched and count it as a skip.
   - **Casing**: match the dominant pattern already in use across renamed
     layers in the file (kebab-case, Title Case, lowercase). Do not impose a
     style.

5. **Apply in one batch.** Call `mcp__mercury__batch` with `ops`: an array of
   `{ tool: "patch", params: { id, name } }` entries, one per node. The whole
   batch is one undo step in Figma — Cmd+Z rolls back everything at once.
   Keep each batch under 40 ops; split into multiple batches if the selection
   is larger (see the mercury-gotchas skill).

6. **Report.** One paragraph max. State: how many renamed, how many skipped
   (and the dominant reason), and one before→after example pair. Don't
   re-list every change — the Mercury plugin panel shows it.

## Constraints

- Never invent identifiers. If a node has no signal (empty frame, generic
  rectangle, no nearby text), leave its name alone and count it as a skip.
- Don't rename node ids — only the `name` field.
- Don't recurse below depth 4 in `query op:subtree`. Large files will time out.
- If the designer asks you to undo, tell them to press Cmd+Z in Figma — your
  batch was atomic, one keystroke reverts it.

## Example

Designer: "rename these"
You:
1. `ping` → ok
2. `query op:selection` → 1 frame "Frame 432" with 8 children
3. `query op:subtree id:"..." depth:3` → frame contains an icon, text "Sign in
   to your account", and a button instance
4. `batch` with ops:
   - `{ tool: "patch", params: { id: "...", name: "sign in / container" } }`
   - `{ tool: "patch", params: { id: "...", name: "icon" } }`
   - `{ tool: "patch", params: { id: "...", name: "sign in to your account" } }`
   - `{ tool: "patch", params: { id: "...", name: "Primary Button" } }`
5. Reply: "Renamed 4 layers, skipped 2 (no semantic signal). 'Frame 432' →
   'sign in / container'."