ux-writing
Write and review the words inside a product — button labels, error messages, empty states, confirmations, settings labels, placeholders, notifications — and the documentation prose around it, including READMEs, docs pages and release notes. Grounds the wording in the JTBD corpus (the anxiety force tells you what a confirmation must defuse) and hands the result to respondent-panel to find out whether strangers read it the way you meant. Use when writing or reviewing any user-facing string. Triggers on UX writing, microcopy, interface copy, button labels, error messages, empty states, placeholder text, settings labels, confirmation dialog, notification copy, README wording, rewrite these docs, release notes copy, "what should this button say", "rewrite this error", "перепиши текст кнопки".
glebis · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add glebis/humane-agentic-design --skill ux-writingAbout this skill
name: ux-writing description: Write and review the words inside a product — button labels, error messages, empty states, confirmations, settings labels, placeholders, notifications — and the documentation prose around it, including READMEs, docs pages and release notes. Grounds the wording in the JTBD corpus (the anxiety force tells you what a confirmation must defuse) and hands the result to respondent-panel to find out whether strangers read it the way you meant. Use when writing or reviewing any user-facing string. Triggers on UX writing, microcopy, interface copy, button labels, error messages, empty states, placeholder text, settings labels, confirmation dialog, notification copy, README wording, rewrite these docs, release notes copy, "what should this button say", "rewrite this error", "перепиши текст кнопки". handoffs:
- to: respondent-panel when: rewritten copy needs reading by strangers, not by its author accepts:
- from: jtbd
- from: layout-rules
- from: respondent-panel
- from: prototype
UX Writing
Announce at start: "I'm using the humane:ux-writing skill to write and review the words inside this product."
The words are part of the interface, not a layer applied to it. A control that names its exact action needs no tooltip; an error that says what to do next needs no support ticket. Clear beats clever, consistent beats varied, and the best error message is the interaction redesigned so the error cannot happen.
What this skill owns, and what it doesn't
Owns: the source wording of every user-facing string, and the decision about what a string must accomplish.
That includes documentation prose — READMEs, docs pages, release notes,
onboarding guides. The principles below were written for interface strings and
most transfer directly (accuracy, one vocabulary, nothing does double duty, no
selling); where a principle is interface-specific it is marked. A doc that
contradicts the thing it documents is a HIGH finding, not a typo.
| Adjacent concern | Owner |
|---|---|
| Mechanical spacing, protected pairs, punctuation and symbol cleanup, spelling/editorial polish | typography after the wording is settled |
How copy renders — capitalization via text-transform, truncation, wrapping, measure | layout-rules (and better-typography if interfaces is installed) |
| Whether the layout has room for the translated string | layout-rules |
Error markup and announcement (aria-invalid, live regions) | nielsen-heuristics for the heuristic; better-accessibility for the implementation |
| Whether the copy lands with strangers | respondent-panel |
| Whether a stakeholder objects to the argument | persona-review |
| Brand voice for marketing surfaces, taglines, transformation claims | brandkit, before-after |
This skill writes the words. It does not judge the usability of the flow around
them — that is nielsen-heuristics.
Quick Reference
| Category | When to use | Reference |
|---|---|---|
| Copy patterns | Ready-made shapes for errors, empty states, confirmations, toggles, notifications | patterns.md |
Step 0 — Read the evidence before writing a word
This is the step that separates this skill from a style guide, and it is not optional when a corpus exists.
- Look for
<corpus_root>/<slug>/jtbd.json.corpus_rootis thesetupsetting (default~/jtbd); read the configured value rather than assuming the default, or a user who moved their corpus gets "no corpus found" and copy written from assumption. If one exists, read it. If several projects exist, ask which. If none exists, say so plainly in the output — the copy is then written from assumption, and that is a fact the reader should have. - Mine the switch forces, because each one tells you what a specific class of string has to accomplish:
| Force | What it means for the copy |
|---|---|
anxiety | What a confirmation, a destructive dialog, or a first-run screen must defuse. If the anxiety is "I'll lose my data", the delete dialog says what is recoverable and for how long. |
habit | What the old vocabulary was. Name things the way the thing they're leaving named them, or say explicitly that you renamed it. |
push | The frustration to name back to them in an empty state or onboarding. Recognition beats persuasion. |
pull | The one outcome a primary button should promise. It is usually the verb. |
- Reuse the corpus's own words.
evidence.quotes[]is the product's real vocabulary, captured from people who use it. A verbatim noun from a quote beats an invented one every time. When you take a word from a quote, cite the evidence id ([Q2]) beside the string.
Step 1 — Recon the voice you already have
Before writing or changing anything, read the surrounding copy, the product's terminology, its localization files, and any style guide. Preserve intentional character. A difference from generic plain language is a finding only when it creates inconsistency, ambiguity, translation risk, or a tone wrong for the stakes — not merely because it has personality.
Tone flexes with the stakes; voice does not change:
| Context | Tone |
|---|---|
| Success, onboarding, empty states | Warm, can be light |
| Routine actions, settings | Neutral, minimal |
| Errors, destructive confirmations | Calm, plain, zero playfulness |
| Data loss, security, money | Serious, explicit, no compression |
Core Principles
1. A Control Names Its Exact Action
Buttons start with a verb naming the specific thing that happens: Send,
Save draft, Delete project. Never OK, Submit, Let's go!, or a bare
Yes/No on anything consequential. A confirmation repeats the consequence so
the dialog is answerable without reading the body: "Delete this project?" offers
Delete project and Cancel.
2. Nothing Does Double Duty
A label labels, an example demonstrates, a hin
Read the complete source ↗