ux-writingby content-designer

UX Writing Skill.

A Claude Code and Codex skill for UX research: user-centered, accessible microcopy: buttons, labels, errors, forms, onboarding.

UX & Research

Download OpenDesign View usage guide

content-designer/ux-writing-skill · SKILL.mdSKILL.md

--- name: ux-writing description: Create user-centered, accessible interface copy (microcopy) for digital products including buttons, labels, error messages, notifications, forms, onboarding, empty states, success messages, and help text. Use when writing or editing any text that appears in apps, websites, or software interfaces, designing conversational flows, establishing voice and tone guidelines, auditing product content for consistency and … --- ## When to Use This Skill ## Core UX Writing Principles ## UX Text Patterns ## Voice and Tone ## Editing Process ## Workflow

Front matter and section headings read from the upstream file on 2026-09-14 · 15,313 characters in full

01 What it does

What the ux-writing Skill Does in Claude Code and Codex

Summary, workflow and outputs, all read from the skill's SKILL.md.

From the SKILL.mdRead 2026-09-14 · not a recorded run

In the Skill's Own Terms

A working guide for writing and editing microcopy in digital products: buttons, labels, titles, error messages, notifications, forms, onboarding, empty states, success messages and help text. Every string is judged against four quality standards — purposeful, concise, conversational and clear — and each element type has a pattern, such as [Verb] [object] for buttons and [What failed].

[Why/context]. [What to do]. for errors. Voice is treated as fixed brand personality while tone shifts across frustrated, confused, confident, cautious and successful users. The skill adds accessibility rules, research-backed sentence and character benchmarks, a four-phase editing process, and reference files for voice charts, content usability and Figma MCP.

What it produces

The interface copy itself across buttons, labels, error messages, notifications, forms and related elements.
A product voice chart, built with references/voice-chart-template.md, mapping brand concepts to voice characteristics and do/don't examples.
Error messages written from templates/error-message-template.md, a fillable template for effective error messages.
An onboarding flow designed from templates/onboarding-flow-template.md, the framework for clear onboarding experiences.

See the example prompt ↗

How It Works

01
Start from Context
Step one is understanding user goals, business objectives, technical constraints and the emotional state of the user before any drafting begins.
02
Draft from Speech
Begin with what you would say out loud, apply the element's pattern, weigh voice and tone, then front-load the important information.
03
Edit in Four Ordered Passes
The file prescribes four phases, run in order: purposeful, concise, conversational, clear, each with its own checking questions.
04
Match Tone to the Moment
Tone is adapted per user emotional state — frustrated, confused, confident, cautious, successful — while voice stays constant.
05
Test and Measure
Review with the team, test with users when possible, then measure task completion and comprehension rather than opinion.

02 Find your fit

When to Use the ux-writing Skill

Use the ux-writing skill in Claude Code or Codex when the job is UX research of this kind. Fit and limits below are taken from the skill's own file.

Good Fit

Writing fresh copy for interface elements: buttons, labels, titles, messages and forms.
Editing existing UX text that already shipped but reads badly.
Auditing a product's content for consistency and usability across screens.
Writing error, notification and success messages that explain and recover.
Establishing a product's voice and tone, or designing onboarding and conversational flows.

Know the Boundaries

Will not work in ChatGPT — the file states it runs with Codex CLI/IDE and that ChatGPT cannot install or use skills.
Vague failure explanations such as "Something went wrong" are listed as things to avoid.
Overly clever humor is out in serious contexts.

What to Provide

The user's emotional state and stakesTone is picked from how the user feels and how much is at risk — a low-stakes theme change reads differently from deleting an account.
Accessibility constraintsWhether visual context is enough for an element, or explicit labels and ARIA labels are needed for assistive technology.

03 Inside the skill

Rules the ux-writing Skill Gives Claude Code and Codex

8 concrete instructions, defaults and limits the SKILL.md sets for the agent — the part of the file that changes the result.

Lines of 40-60 Characters
Interface text lines should run 40-60 characters, the maximum readability range the file sets.
Buttons: 2-4 Words
Button and CTA labels should be 2-4 words, with 6 words as the absolute ceiling.
Plain Language by Audience
Write to a 7th grade reading level for a general audience and 10th grade for professional contexts.
Active Voice 85% of the Time
Roughly 85% of the copy should be in active voice.
Errors Follow a Fixed Order
Error copy states what failed, then why or the context, then what to do — in that order.
Never Blame the User
Error copy acknowledges the problem without blaming the person reading it.
Never Color Alone
Meaning is never carried by color by itself; visual indicators are paired with text.
Error Messages: 12-18 Words
An error message, including its solution, should land between 12 and 18 words.

04 Put it to work

Install ux-writing in Claude Code or Codex

One npx skills add command, then a first task in your agent and a checklist for the result.

Add ux-writing to Claude Code, Codex or Your Agent

Run in your project; the installer asks which agent to add it to.

Terminal

npx skills add https://github.com/content-designer/ux-writing-skill --skill ux-writing

Generic skills CLI form for SKILL.md; the repository may document its own path.

Give the Skill a First UX Research Task

Written in the skill's own terms; replace the bracketed parts with your material.

Starter prompt

Write the microcopy for our [checkout] flow: the payment button label, the field labels, and the message a user sees when their card is declined. The user will be frustrated, so keep the tone empathetic and give a clear next step. Then run the four-phase edit and flag any line over 60 characters.

Source: written from the SKILL.md in the skill's own terms.

Check the First Result

What the SKILL.md itself says a correct result looks like:

Read the copy aloud and ask whether you would actually say it that way.
Run strings through a readability tool; the file names Hemingway Editor and Flesch-Kincaid scoring.
Check comprehension benchmarks: 8 words or fewer reads at 100% comprehension, 14 words or fewer at 90%.
Work through references/content-usability-checklist.md, the shipped checklist for evaluating UX text quality.
Have the team review and test with users, measuring task completion and comprehension rather than taste.
For accessibility, confirm errors are structured so the error and the field label are announced together by a screen reader.

In OpenDesign import ux-writing from its SKILL.md link: Plugins → Add → Skill → Import from link, then pick it in the top bar.

Download OpenDesign Read the quickstart

05 Open source, traceable

Source, License and Verification

Where this page's facts come from, and when they were last checked.

Author: content-designer
Repository: github.com/content-designer/ux-writing-skill Branch main
Skill file: SKILL.md Content checksum recorded at verification; commit 98cacde
License: MIT From LICENSE.
Repository stars: 168 GitHub snapshot taken 2026-09-14 for the whole content-designer/ux-writing-skill repository. Not a rating or usage count for ux-writing.
Verified by OpenDesign: 2026-09-14 Source file, path, license text and star count were checked. Not bundled in OpenDesign main (checked 2026-08-28); a live run has not been recorded on this page.

Inside the SKILL.md

When to Use This SkillSix triggers: writing or editing interface copy, messages, conversational flows, voice, auditing content.
Core UX Writing PrinciplesThe four quality standards plus conciseness, clarity, conversational tone and user-centered practices.
UX Text PatternsFormats and examples for titles, buttons, four error types, success messages, empty states, forms and notifications.
Voice and ToneBuilding a constant voice; shifting tone by user emotional state and by content type.
Editing ProcessFour ordered passes — purposeful, concise, conversational, clear — each with its checking questions.
WorkflowUnderstand context, draft, edit iteratively through the four phases, then test and measure.
Accessibility in UX WritingScreen reader, cognitive, multi-modal and plain language requirements, with poor and good pattern examples.
UX Text BenchmarksSentence and character targets by element, comprehension rates, and reading levels with testing tools.
Common Mistakes to AvoidEleven anti-patterns, from passive voice and generic labels to inaccessible link text.
Quick ReferenceOne-line reminders on sentence case, imperative buttons, user focus, specific verbs and front-loading.
ResourcesNine shipped files: accessibility guide, voice chart, usability checklist, pattern examples, templates and Figma integration.

The Skill's Own Description

“Create user-centered, accessible interface copy (microcopy) for digital products including buttons, labels, error messages, notifications, forms, onboarding, empty states, success messages, and help text. Use when writing or editing any text that appears in apps, websites, or software interfaces, designing conversational flows, establishing voice and tone guidelines, auditing product content for consistency and usability, reviewing UI strings, or improving existing interface copy. Applies UX writing best practices based on four quality standards — purposeful, concise, conversational, and clear. Includes accessibility guidelines, research-backed benchmarks (sentence length, comprehension rates, reading levels), expanded error patterns, tone adaptation frameworks, and comprehensive reference materials.”

Front-matter description from SKILL.md. The full file is about 15,313 characters. Read the full file on GitHub.

06 Before you install

Questions About the ux-writing Skill

Answers come from the SKILL.md as read on 2026-09-14, not from a recorded run.

Which agents can run this skill?

It is written for Claude, Codex, Cursor and any other agent that supports the agent skills specification. ChatGPT is explicitly excluded — it cannot install or use skills.

Can I use it on copy that already exists?

Yes. The skill covers editing existing UX text, reviewing UI strings and auditing product content for consistency and usability, not just writing from scratch.

Does it cover accessibility?

Yes. Accessible writing is its own section, covering screen reader optimization, cognitive accessibility, multi-modal communication and plain language, with a WCAG AA color contrast minimum of 4.5:1.

UX Writing

Run ux-writing on a Real UX Research Task.

Download OpenDesign, import ux-writing from its SKILL.md link, paste the prompt above, and read the plan before the result.

Download OpenDesign Browse all skills