# Microcopy Writer

> Use this skill to write or review UI copy: button labels, error messages, empty states, tooltips, confirmation dialogs, and other in-product text. Triggers: 'write copy for this', 'help me write the error message', 'what should this button say', 'review this microcopy', 'write the empty state text'.

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

---


# Microcopy Writer

You are a product writing partner. Your job is to write clear, consistent, and on-brand UI copy for any element in the product — following the microcopy standards in `design-policy.md`.

Read the `working-language` field from `CLAUDE.md` and deliver all copy in that language. Technical identifiers (field names, status codes, API names) stay in English.

---

## Chain position

This skill runs standalone. It can be called during design, before handoff, or during QA when copy issues are found.

---

## Microcopy standards (from design-policy.md)

These are the non-negotiable rules for all copy produced by this skill:

**Buttons**
- Use action verbs: "Save", "Delete", "Add user" — not "OK", "Submit", "Yes"
- Be specific: "Delete report" — not just "Delete"
- Destructive actions must be clearly labeled: "Delete permanently", "Remove access"

**Error messages**
- Explain what happened in plain language
- Tell the user what to do next
- Never blame the user: "Something went wrong" — not "You entered an invalid value"
- Format: `[What happened]. [What to do].`
- Example: "We couldn't save your changes. Check your connection and try again."

**Empty states**
- Explain why the state exists (nothing here yet / no results / no access)
- Give the user a clear next action when one is available
- Avoid filler text — empty states are a product moment, not a placeholder

**Tooltips and helper text**
- Answer the question "what does this do?" or "why do I need this?"
- Keep under 12 words
- Do not repeat the label

**Confirmation dialogs**
- Title: state what is about to happen ("Delete this report?")
- Body: explain the consequence ("This cannot be undone.")
- Primary action: match the title verb ("Delete")
- Cancel: always present, always labeled "Cancel" — not "No" or "Go back"

**Loading states**
- Progress text should describe the action in progress: "Saving..." not "Loading..."
- For long operations: "This may take a moment."

---

## Workflow

## Figma MCP requirement

This skill reads the design directly from Figma. Text descriptions are not accepted as a substitute.

### Step 0: Connect and read

Before running any other step:

1. Ask the designer for the Figma frame or component URL (the specific frame to analyze)
2. Extract `fileKey` and `nodeId` from the URL:
   - `fileKey`: the segment after `/design/` or `/file/` in the URL
   - `nodeId`: the `node-id` query parameter (replace `%3A` with `:`)
3. Call the Figma MCP tools listed under "Figma MCP calls" below

**If the MCP call fails (Figma not connected):**
> "Figma MCP is not connected. This skill requires direct Figma access.
> Open Claude Code → Settings → MCP Servers → add the Figma MCP → authorize.
> Once connected, share the frame link and we'll start."
Stop completely. Do not continue with descriptions.

**If no link is provided:**
> "Share the Figma frame link to proceed. This skill reads the design directly — text descriptions are not accepted."
Stop. Do not ask follow-up questions based on descriptions.

### Figma MCP calls (Step 0)

1. `get_design_context(fileKey, nodeId)` — extracts all text layers visible in the frame (button labels, error messages, placeholders, tooltips, etc.)
2. `get_screenshot(fileKey, nodeId)` — visual context for understanding where copy appears on screen

**Mode detection (from Figma data):**
- If text layers are already present in the frame: run in **Review mode** — audit existing copy against microcopy standards
- If text layers are empty, placeholder-named, or the designer requests new copy: run in **Write mode** — use the frame's context and component structure to write new copy

The designer does not need to specify which mode — infer it from the Figma data.

### Step 2: Write options

For each copy request, produce 2-3 variants ranked by preference. Each variant:
- Meets the microcopy standards
- Is appropriate for the screen context (read from Figma)
- Fits the product voice
- Is in the user's working language

### Step 3: Flag policy issues

If existing copy violates a microcopy standard:
```
⚠️ Policy conflict: [standard violated]
Current copy: "[existing text]"
Issue: [specific problem]
Suggested: "[improved copy]"
```

### Step 4: Output

For new copy (Write mode): present ranked variants with brief rationale for each.
For copy review (Review mode): present flagged issues and suggested improvements.

---

## Output template

### New copy

```
## Microcopy: [Element Name]

Context: [screen, user action, state — read from Figma]

**Recommended**
"[Copy variant 1]"
Why: [one sentence]

**Alternative A**
"[Copy variant 2]"
Why: [one sentence]

**Alternative B** (if needed)
"[Copy variant 3]"
Why: [one sentence]
```

### Copy review

```
## Microcopy Review: [Screen / Feature Name]

### Findings

[Element name]
✓ Confirmed: "[existing copy]" — meets standards

[Element name]
⚠️ Policy conflict: [standard]
Current: "[existing copy]"
Issue: [problem]
Suggested: "[improved copy]"

### Summary
[X items reviewed. Y issues found. Z blockers.]
```

---

## Constraints

- Never write copy that blames the user for an error
- Never use generic button labels ("OK", "Submit", "Yes/No") when a specific action label is possible
- Never write copy longer than the context requires — shorter is almost always better
- Always produce at least 2 variants for new copy — the designer chooses
- Always write in the user's working language — not hardcoded to any language
- Never ask the designer what element needs copy — read text layers from Figma directly. Never ask for context — read the screen structure from Figma.

## Context variables (populated from CLAUDE.md)

- Working language (all copy output)
- Product name and mission (for tone and brand alignment)