clarify

Overview of clarify skill

The clarify skill helps rewrite confusing UI text so users can understand what happened, what to do next, and why it matters. It is built for UI/UX design work, especially when a product has vague labels, weak error messages, hard-to-follow instructions, or microcopy that sounds technically correct but still confuses real users.

What clarify is best for

Use clarify when the problem is not layout or interaction flow first, but the wording inside the interface:

• button labels that do not signal the result
• error messages that explain the system instead of helping the user
• empty states with no next step
• form help text that assumes too much knowledge
• instructions that are accurate but mentally heavy under stress

This makes the clarify skill a strong fit for product designers, UX writers, frontend teams, and founders polishing user-facing text before launch.

The real job clarify does

The practical job of clarify is to turn rough or unclear interface copy into text that is:

• easier to scan
• easier to act on
• better matched to user knowledge
• better matched to the emotional moment

That last point matters. The source skill explicitly asks for the user’s technical level and mental state in context, which is more useful than generic “make this clearer” prompting.

What makes clarify different from a generic rewrite prompt

A normal prompt may produce cleaner wording. clarify is more opinionated about why copy fails:

• jargon
• ambiguity
• passive voice
• missing context
• hidden assumptions
• tone mismatch
• too much or too little detail

It also depends on broader design context. The skill requires /frontend-design and, if that context does not exist yet, /teach-impeccable first. That dependency is important for installation decisions: clarify is not a standalone copy-polish macro; it is meant to operate inside a larger UX/design system workflow.

How to Use clarify skill

Install clarify in the right repository context

The clarify install path follows the host skill system for the pbakaus/impeccable repo. If you use a Skills-compatible environment, add the repo and invoke the clarify skill from there. The skill itself lives at:

/.agents/skills/clarify/SKILL.md

Because the repository evidence only exposes SKILL.md, read that file first before assuming extra helper assets exist.

Read this file before your first run

Start with:

• SKILL.md

That is where the real operating logic sits: required preparation, evaluation criteria, and the step-by-step copy review flow. There are no surfaced support scripts or references here, so the main value is in following the skill’s sequencing correctly.

Do not skip the required dependency

Before using clarify, the skill says to invoke:

• /frontend-design

And if no design context exists yet:

• /teach-impeccable

This is the biggest adoption blocker for new users. If you skip that preparation, you will likely get decent wording but weaker UX decisions. The skill expects design principles and context gathering to already be in place.

What input clarify needs to work well

The minimum usable input for clarify usage is the current text plus where it appears. Better results come from adding:

• target screen or flow
• exact UI element type
• audience technical level
• user mental state at that moment
• desired action after reading
• constraints like tone, brand voice, or character limits

Without these, the skill can still rewrite text, but it cannot reliably choose the right level of directness, detail, or emotional tone.

Best prompt shape for clarify for UI/UX Design

A weak request:

• “Improve this error message: Authentication failed.”

A stronger request:

• “Use clarify for UI/UX Design. Rewrite this login error message for non-technical users on mobile. They are likely frustrated and trying to get back into their account quickly. Current text: ‘Authentication failed.’ We want them to understand the problem and next step without sounding robotic. Keep it under 90 characters if possible.”

That stronger input gives the skill the missing decision data: audience, emotion, device context, and success criteria.

Turn a rough goal into a usable clarify prompt

If your starting point is “make the app text clearer,” convert it into this structure:

1. current copy
2. location in product
3. who the user is
4. what they are trying to do
5. what emotional state they are in
6. what action they should take next
7. constraints on length or tone

This structure aligns closely with the actual clarify guide implied by the skill’s checklist.

Suggested workflow for practical clarify usage

A reliable workflow looks like this:

1. Gather product and design context with /frontend-design.
2. Confirm audience level and mental state.
3. Paste the original copy exactly as it appears.
4. Explain the screen and intended user action.
5. Ask for diagnosis first, then rewrite options.
6. Pick one direction and iterate on tone, brevity, or specificity.

That “diagnosis first” step matters because the skill is built to identify why copy is unclear, not just replace it.

Ask clarify to diagnose before rewriting

To get more value than a generic LLM polish pass, ask for output in two stages:

• clarity issues found
• improved alternatives

Example:

• “Use clarify. First identify jargon, ambiguity, missing context, assumptions, and tone issues in this onboarding copy. Then provide 3 rewrite options for first-time users.”

This helps teams review decisions instead of just choosing whichever rewrite sounds nicest.

Where clarify is strongest

The clarify skill is strongest on short, high-impact UI text such as:

• errors
• labels
• helper text
• confirmations
• warnings
• empty states
• setup instructions

These are places where unclear wording creates friction fast and where context-sensitive rewrites can materially improve completion rates and confidence.

Where clarify is a weaker fit

Use caution if the real issue is:

• wrong product flow
• missing functionality
• poor information architecture
• legal or compliance wording that cannot change much
• long-form marketing copy

In those cases, clarify may improve readability, but it will not fix the root problem.

clarify skill FAQ

Is clarify only for UX writers?

No. clarify is useful for designers, PMs, engineers, and founders who own interface text but are not trained UX writers. The main requirement is that you can provide enough context about the user and moment.

Is clarify beginner-friendly?

Mostly yes, but only if you notice its dependency chain. The source skill requires /frontend-design, and possibly /teach-impeccable, before rewriting. Beginners who ignore that step may think the skill is thin, when the intended workflow is actually context-first.

What does clarify do better than a normal “rewrite this” prompt?

The main advantage is structured diagnosis. clarify looks for specific causes of confusion such as jargon, ambiguity, passive voice, missing context, and assumptions about user knowledge. That usually leads to more actionable rewrites for interface copy.

When should I not use clarify?

Do not reach for clarify when the copy is only a symptom of a deeper product issue. If users are confused because the flow is broken, permissions are unclear, or the UI hides key information, better wording alone will not solve it.

Is clarify good for error messages?

Yes. This is one of the clearest use cases. The skill explicitly accounts for the user’s mental state, which is critical for stressed moments like login failures, payment problems, or form validation issues.

Can clarify help with tone and brand voice?

Yes, but only if you provide constraints. If you want “plain but premium,” “friendly but not playful,” or “supportive under stress,” say so directly. Otherwise the skill will optimize primarily for clarity.

How to Improve clarify skill

Give clarify the user state, not just the sentence

The highest-leverage improvement is to describe the user’s situation:

• first-time or expert
• calm or stressed
• browsing or trying to recover from failure
• desktop or mobile
• high attention or low attention

This directly affects whether the best copy should be shorter, warmer, more explicit, or more instructional.

Provide the surrounding UI, not isolated text

A label or message often looks bad because it lacks surrounding context. To improve clarify results, include:

• nearby fields or buttons
• page title
• previous step
• next expected action

A “bad” line may be acceptable in one screen and harmful in another.

Ask for multiple rewrite strategies

Instead of requesting one answer, ask for options such as:

• shortest clear version
• most supportive version
• most action-oriented version

This is especially useful for clarify for UI/UX Design because teams often need to trade off brevity, tone, and guidance.

Use character or layout constraints early

If the copy must fit a button, toast, modal, or mobile form field, say so up front. Otherwise clarify may produce text that is clearer in theory but unusable in the actual interface.

Watch for common failure modes

Even with clarify, teams often accept rewrites that are:

• clearer but too long
• friendlier but vague
• precise but overly technical
• polished but detached from the actual task

Review outputs against the user action you want, not just writing quality.

Iterate on the diagnosis, not just the wording

If the first result misses the mark, do not only ask for a shorter rewrite. Ask what the skill may have misunderstood:

• wrong audience assumption
• wrong mental state
• missing product context
• too much simplification
• not enough explanation of next steps

This improves later outputs faster than surface-level editing.

Pair clarify with a screen-level review

The best way to improve the clarify skill in practice is to use it as part of a screen review, not a sentence repair tool. Review all related copy together:

• page title
• field labels
• helper text
• validation text
• CTA label
• success or failure message

That catches inconsistencies a single-line rewrite would miss.

Keep a reusable prompt template for clarify usage

A simple reusable template:

• “Use clarify. Context: [screen/flow]. Audience: [user type]. Mental state: [emotion/urgency]. Current copy: [text]. Goal: [desired action]. Constraints: [tone/length/brand]. First diagnose the clarity issues, then give 3 rewrite options.”

This makes clarify usage more consistent across teams and reduces low-context requests that produce generic output.