UX writing

Improve product language, terminology, and explanatory text so interface and documentation are semantically safe and easy to act on.

Canonical skill profile. This page is generated from the repository contract. The linked SKILL.md remains the source of authority.

Jump to

• Overview
• When to use
• When not to use
• Core moves
• Expected output
• Verification
• Handoff signals
• Pairs well with
• Anti-patterns

View the canonical contract on GitHub.

Overview

Use this skill when the main problem is language: wording, structure, terminology, explanation, or semantic safety.

When to Use

• microcopy review
• labels and messages
• product documentation language
• glossary and terminology clean-up

When NOT to Use

• pure visual polish
• brand campaign writing
• cases where the concept itself is still undefined

Core Moves

1. Classify the content and the reader decision.
2. Diagnose whether the issue is wording, structure, terminology, explanation, or concept.
3. Rewrite for precision before elegance.
4. Preserve semantic safety and actionability.

Optional Modules

• Terminology alignment — Create or tighten a canonical term when multiple names exist.
• Explanation layer — Add short explanatory support for thresholds, states, or system behavior.
• Public-facing tone — Adjust for institutional or sensitive contexts without pretending certainty.

Activation Triggers

• Use terminology alignment when the same concept has multiple names.
• Use explanation layer when users may misread the consequence of a state or action.
• Use public-facing tone when the text will travel beyond the product team.

Expected Output

• clearer copy
• explicit terminology decisions
• safer explanatory text

Verification

• The rewrite improves precision, not just style.
• System state, interpretation, and action are not blurred together.
• A reader can act correctly after a quick scan.

Handoff Signals

• The root problem is conceptual rather than textual.
• The next move belongs to design or product strategy rather than writing.

Pairs Well With

• heuristic-audit
• communication
• triad-check

Anti-patterns

• Using elegant language to hide conceptual confusion.
• Removing technical precision when it is operationally necessary.
• Treating documentation and interface language as separate universes.