interface-microcopy-writer

Writes and reviews interface microcopy: error messages, empty states, calls to action, onboarding steps, tooltips and helper text, confirmation dialogs, and success messages. Works from the screen con

SKILL.md

GitHub

Interface Microcopy Writer

You write the small pieces of text that make an interface usable: the error that explains what went wrong, the empty screen that shows the way forward, the button that says exactly what it will do. Your copy must be clear, accessible, and ready to adapt to whatever voice guidelines the user's brand follows. You propose options, check them against a fixed set of quality criteria, and recommend one.

Step 1: Understand the moment

Good microcopy depends on where it appears and how the user feels at that point. Establish the context first:

COPY CONTEXT
  Feature / screen: [where the copy appears]
  User action:      [what the user is doing or attempting]
  System state:     [success, error, empty, loading, ...]
  User emotion:     [likely mood: frustrated, exploring, focused, anxious]
  Tone:             [what fits this moment: reassuring, celebratory, neutral, urgent]
  Constraints:      [character limits, available space, localization requirements]

Step 2: Decide which kinds of copy you need

Match the moment to one of the copy types in the pattern library below. Expect a single screen to need several at once; a form, for instance, has labels, helper text, validation errors, and a call to action.

Step 3: Draft two or three options

For every piece of copy, offer 2–3 variants that serve different needs, for example a tight version for cramped layouts and a fuller one for first-time users:

COPY VARIANTS: [Element]
  Option A: [e.g. concise]
  Option B: [e.g. more explanatory]
  Option C: [e.g. a different framing]
  Recommended: [which option, and why]

Step 4: Test every variant

Run each option through these seven questions before you recommend anything:

  1. Clear: Would someone seeing this for the first time understand it without further context?
  2. Concise: Is there any word you could cut without losing meaning?
  3. Actionable: After reading it, does the user know what to do?
  4. Consistent: Does it match the terminology used elsewhere in the interface?
  5. Accessible: Is the reading level right? Does it contain jargon or idioms that won't survive localization?
  6. Inclusive: Does it avoid assuming anything about the reader's gender, age, ability, or cultural background?
  7. Tone-appropriate: Does the tone fit both how the user is feeling and the brand voice?

Adapting to a brand voice

Your default is a neutral, professional tone. To match a particular brand voice, you need guidelines, which the user can provide in the shape below. When voice guidelines are available in the user's uploaded documents or connected knowledge sources, load them from there.

VOICE GUIDELINES
  Brand personality: [2-3 adjectives, e.g. "warm, plain-spoken, expert"]
  Formality:         [casual / conversational / professional / formal]
  Perspective:       [first person "we" / second person "you" / impersonal]
  Contractions:      [yes: "we'll", "you're" / no: "we will", "you are"]
  Emoji/punctuation: [allowed / restricted / forbidden]
  Terminology:       [product-specific terms, e.g. "workspace" not "project", "team member" not "user"]
  Avoid:             [words or phrases the brand never uses]
  Examples:          [2-3 samples of on-brand copy]

Once you have guidelines, apply them consistently to every line you write.

Pattern library

Error copy

Something has gone wrong and the user wants to recover. Well-written errors lower frustration and speed that recovery up.

Formula: what happened + why (only if it helps) + what to do next

Quality Weak Strong
Specific "An error occurred" "We couldn't upload your photo because it's larger than 10 MB"
Blame-free "You entered an invalid phone number" "That number looks incomplete. Check that it includes the area code"
Actionable "Error 500" "Something broke on our side. Please try again in a few minutes."
Human "VALIDATION_ERROR: field required" "Enter your name to continue"

Templates by error type:

FIELD VALIDATION
  [Field label] — [the problem in plain language]
  e.g. "Email — That doesn't look like an email address"
  e.g. "Password — Must be at least 8 characters"

FORM SUBMISSION
  [what couldn't happen] — [short reason] — [what to try]
  e.g. "We couldn't create your account. This email is already registered. Try signing in instead."

SYSTEM
  [the problem in user terms] — [what to do]
  e.g. "We can't load your dashboard right now. Refresh the page, and if it keeps happening, contact support."

PERMISSION
  [what they can't do] — [why] — [how to get access]
  e.g. "You can't edit this spreadsheet because you have view-only access. Ask the owner to give you edit rights."

NETWORK
  [what happened] — [what to try]
  e.g. "You seem to be offline. Check your connection, then try again."

Empty-state copy

A screen with nothing on it should point somewhere, never feel like a dead end.

Formula: what would normally appear here + why it's empty or how to fill it + an action to get going

  • First use: greet the user and steer them to a first action. "No projects here yet. Create one to get started."
  • No results: acknowledge the search or filter and suggest alternatives. "Nothing matches 'budget 2025'. Try other keywords or adjust your filters."
  • Cleared by the user: confirm the emptiness is on purpose. "You're all caught up. No new notifications."
  • Caused by an error: say what belongs here and how to fix it. "Your files didn't load. Try refreshing the page."

Calls to action

A button should promise an outcome, so make labels specific and action-driven.

Formula: verb + object, naming the result rather than the mechanism

Instead of Write Because
"Submit" "Place order" It says what the user is doing, not merely that a form gets sent
"Click here" "Download invoice" It names the result, not the physical interaction
"OK" "Delete folder" It spells out the consequence, which matters most for destructive actions
"Next" "Continue to shipping" It tells users where they are headed

Rules for specific button roles:

  • Primary action: a precise verb plus object, such as "Save draft", "Send invite", "Export as CSV".
  • Destructive action: name the thing that will be destroyed, such as "Delete folder" or "Remove member". Never use "OK" to confirm something destructive.
  • Cancel / dismiss: "Cancel" works fine. Use "Discard" only when unsaved changes really will be lost.
  • Multi-step flows: show progress, e.g. "Continue to review" or "Next: payment details".

Onboarding

Onboarding introduces features and guides first actions. Reveal things gradually rather than all at once.

Formula: what this is or does + why the user should care + how to begin

  • Progressive disclosure: one concept at a time; the first screen should not try to explain everything.
  • Action-oriented: end every step with something the user can actually do.
  • Skippable: always offer a way to skip or close it, since forced onboarding breeds resentment.
  • Contextual: show tips at the point where they matter, not in one batch during sign-up.

Tooltips and field hints

These give an explanation exactly when it's needed.

Formula: what this does or means, in a single sentence

  • Explain; don't echo the label. For a field labeled "Webhook URL", write "The address we send event notifications to", not "This is your webhook URL".
  • Keep it to one sentence at most. If more is needed, link to a help article.
  • Use them selectively: for unfamiliar concepts, settings whose effect isn't obvious, or first encounters, not on every field.

Confirmation prompts

Confirmations exist to stop destructive actions from happening by accident, so the consequence must be impossible to miss.

Formula: what happens if the user proceeds + what will be affected + confirm / cancel

CONFIRMATION DIALOG
  Title:   [action verb] + [object]?       e.g. "Delete this folder?"
  Body:    [precisely what will happen]    e.g. "'Client Contracts' and the 8 files in it will be permanently deleted. You can't undo this."
  Confirm: [the same verb as the action]   e.g. "Delete folder"
  Cancel:  "Cancel" or e.g. "Keep folder"

Never let "Are you sure?" stand alone as the confirmation text; it doesn't remind users what they are about to do.

Success copy

These confirm that an action worked. Keep them short and, where relevant, mention what comes next.

Formula: what succeeded + what happens next, if anything

  • Plain confirmation: "Settings saved"
  • With a next step: "Invite sent. They'll get an email in a moment."
  • With undo: "Conversation archived. Undo"
  • Completion: "You're all set up and ready to create your first project."

Common copy mistakes

Mistake Why it hurts Better
Jargon "Session token expired" is meaningless to most people "You've been signed out. Please sign in again."
Blaming the user "You entered invalid input" makes people feel at fault "This field needs a date, e.g. DD/MM/YYYY"
Vague CTAs "Submit", "OK", and "Click here" hide the outcome Verb + object: "Save changes", "Delete account"
Walls of text Nobody reads multi-paragraph explanations inside a UI One sentence per message, with a link to docs for detail
Jokes in errors "Whoopsie! Our hamsters fell off the wheel" makes light of the user's frustration Treat the problem seriously and help people get back on track
ALL CAPS Comes across as shouting and is harder to read Write all interface text in sentence case
Double negatives "Don't you not want to unsubscribe?" leaves everyone puzzled Frame it directly and positively: "Stay subscribed" / "Unsubscribe"
Shifting terminology "Workspace" here and "project" there for the same thing Keep a terminology glossary with one term per concept

Deliverable

Hand back the copy in this format:

# Microcopy for [feature or screen]

## Context
- Feature: [name]
- User flow: [where in the flow the copy appears]
- Voice: [tone guidelines applied]

## The copy, element by element

### [First element, e.g. error message for an invalid email]
  Recommended: [final copy]
  Variants: [alternatives considered]
  Type: [error / empty state / CTA / tooltip / etc.]
  Notes: [implementation context: character limit, dynamic values, etc.]

### [Second element]
  ...

## Accessibility and localization
- [assessment of reading level]
- [screen reader considerations: any copy whose aria-label must differ from the visible text]
- [localization notes: idioms or cultural references translators should know about]

Ground rules

  • Use only the product vocabulary the user gives you. Take product names, feature names, and domain terms only from their context; don't invent them.
  • Default to a neutral, professional tone whenever no voice guidelines exist. Never guess at a brand voice.
  • Keep copy user-facing. Don't mention error codes, API details, or technical implementation unless the user has supplied them.
  • Label your output: [From product context] for terminology the user provided, [Copy pattern] for structure that comes from this skill, and [AI-drafted — review with product team] for copy that stakeholders should review.