---
id: sm-clarify
name: "clarify"
url: https://skills.yangsir.net/skill/sm-clarify
author: pbakaus
domain: product
tags: ["requirements-gathering", "user-stories", "product-specification", "communication", "stakeholder-management"]
install_count: 81600
rating: 4.70 (1704 reviews)
github: https://github.com/pbakaus/impeccable
---

# clarify

> 此技能运用设计语言，旨在使AI产品的功能和信息表达更清晰、更易于用户理解和操作，从而提升产品的可用性和用户满意度。

**Stats**: 81,600 installs · 4.7/5 (1704 reviews)

## Before / After 对比

### 产品需求智能澄清与细化

## Readme

# clarify

Identify and improve unclear, confusing, or poorly written interface text to make the product easier to understand and use.

## MANDATORY PREPARATION

Use the frontend-design skill — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run teach-impeccable first. Additionally gather: audience technical level and users' mental state in context.

## Assess Current Copy

Identify what makes the text unclear or ineffective:

- 

**Find clarity problems**:

**Jargon**: Technical terms users won't understand

- **Ambiguity**: Multiple interpretations possible

- **Passive voice**: "Your file has been uploaded" vs "We uploaded your file"

- **Length**: Too wordy or too terse

- **Assumptions**: Assuming user knowledge they don't have

- **Missing context**: Users don't know what to do or why

- **Tone mismatch**: Too formal, too casual, or inappropriate for situation

- 

**Understand the context**:

Who's the audience? (Technical? General? First-time users?)

- What's the user's mental state? (Stressed during error? Confident during success?)

- What's the action? (What do we want users to do?)

- What's the constraint? (Character limits? Space limitations?)

**CRITICAL**: Clear copy helps users succeed. Unclear copy creates frustration, errors, and support tickets.

## Plan Copy Improvements

Create a strategy for clearer communication:

- **Primary message**: What's the ONE thing users need to know?

- **Action needed**: What should users do next (if anything)?

- **Tone**: How should this feel? (Helpful? Apologetic? Encouraging?)

- **Constraints**: Length limits, brand voice, localization considerations

**IMPORTANT**: Good UX writing is invisible. Users should understand immediately without noticing the words.

## Improve Copy Systematically

Refine text across these common areas:

### Error Messages

**Bad**: "Error 403: Forbidden"
**Good**: "You don't have permission to view this page. Contact your admin for access."

**Bad**: "Invalid input"
**Good**: "Email addresses need an @ symbol. Try: [name@example.com](https://github.com/pbakaus/impeccable/blob/HEAD/.claude/skills/clarify/mailto:name@example.com)"

**Principles**:

- Explain what went wrong in plain language

- Suggest how to fix it

- Don't blame the user

- Include examples when helpful

- Link to help/support if applicable

### Form Labels & Instructions

**Bad**: "DOB (MM/DD/YYYY)"
**Good**: "Date of birth" (with placeholder showing format)

**Bad**: "Enter value here"
**Good**: "Your email address" or "Company name"

**Principles**:

- Use clear, specific labels (not generic placeholders)

- Show format expectations with examples

- Explain why you're asking (when not obvious)

- Put instructions before the field, not after

- Keep required field indicators clear

### Button & CTA Text

**Bad**: "Click here" | "Submit" | "OK"
**Good**: "Create account" | "Save changes" | "Got it, thanks"

**Principles**:

- Describe the action specifically

- Use active voice (verb + noun)

- Match user's mental model

- Be specific ("Save" is better than "OK")

### Help Text & Tooltips

**Bad**: "This is the username field"
**Good**: "Choose a username. You can change this later in Settings."

**Principles**:

- Add value (don't just repeat the label)

- Answer the implicit question ("What is this?" or "Why do you need this?")

- Keep it brief but complete

- Link to detailed docs if needed

### Empty States

**Bad**: "No items"
**Good**: "No projects yet. Create your first project to get started."

**Principles**:

- Explain why it's empty (if not obvious)

- Show next action clearly

- Make it welcoming, not dead-end

### Success Messages

**Bad**: "Success"
**Good**: "Settings saved! Your changes will take effect immediately."

**Principles**:

- Confirm what happened

- Explain what happens next (if relevant)

- Be brief but complete

- Match the user's emotional moment (celebrate big wins)

### Loading States

**Bad**: "Loading..." (for 30+ seconds)
**Good**: "Analyzing your data... this usually takes 30-60 seconds"

**Principles**:

- Set expectations (how long?)

- Explain what's happening (when it's not obvious)

- Show progress when possible

- Offer escape hatch if appropriate ("Cancel")

### Confirmation Dialogs

**Bad**: "Are you sure?"
**Good**: "Delete 'Project Alpha'? This can't be undone."

**Principles**:

- State the specific action

- Explain consequences (especially for destructive actions)

- Use clear button labels ("Delete project" not "Yes")

- Don't overuse confirmations (only for risky actions)

### Navigation & Wayfinding

**Bad**: Generic labels like "Items" | "Things" | "Stuff"
**Good**: Specific labels like "Your projects" | "Team members" | "Settings"

**Principles**:

- Be specific and descriptive

- Use language users understand (not internal jargon)

- Make hierarchy clear

- Consider information scent (breadcrumbs, current location)

## Apply Clarity Principles

Every piece of copy should follow these rules:

- **Be specific**: "Enter email" not "Enter value"

- **Be concise**: Cut unnecessary words (but don't sacrifice clarity)

- **Be active**: "Save changes" not "Changes will be saved"

- **Be human**: "Oops, something went wrong" not "System error encountered"

- **Be helpful**: Tell users what to do, not just what happened

- **Be consistent**: Use same terms throughout (don't vary for variety)

**NEVER**:

- Use jargon without explanation

- Blame users ("You made an error" → "This field is required")

- Be vague ("Something went wrong" without explanation)

- Use passive voice unnecessarily

- Write overly long explanations (be concise)

- Use humor for errors (be empathetic instead)

- Assume technical knowledge

- Vary terminology (pick one term and stick with it)

- Repeat information (headers restating intros, redundant explanations)

- Use placeholders as the only labels (they disappear when users type)

## Verify Improvements

Test that copy improvements work:

- **Comprehension**: Can users understand without context?

- **Actionability**: Do users know what to do next?

- **Brevity**: Is it as short as possible while remaining clear?

- **Consistency**: Does it match terminology elsewhere?

- **Tone**: Is it appropriate for the situation?

Remember: You're a clarity expert with excellent communication skills. Write like you're explaining to a smart friend who's unfamiliar with the product. Be clear, be helpful, be human.
Weekly Installs17.9KRepository[pbakaus/impeccable](https://github.com/pbakaus/impeccable)GitHub Stars10.2KFirst Seen14 days agoSecurity Audits[Gen Agent Trust HubPass](/pbakaus/impeccable/clarify/security/agent-trust-hub)[SocketPass](/pbakaus/impeccable/clarify/security/socket)[SnykPass](/pbakaus/impeccable/clarify/security/snyk)Installed oncodex17.7Kopencode17.6Kgithub-copilot17.6Kgemini-cli17.5Kcursor17.5Kamp17.5K

---
*Source: https://skills.yangsir.net/skill/sm-clarify*
*Markdown mirror: https://skills.yangsir.net/api/skill/sm-clarify/markdown*