clarify

Overview of clarify skill

What clarify skill does

The clarify skill improves unclear UX copy: labels, helper text, empty states, onboarding instructions, confirmations, and especially error messages. It is built for moments where users are confused not because the interface is missing features, but because the words are making the product harder to understand.

Best fit for clarify for UI/UX Design

clarify for UI/UX Design is best for product designers, UX writers, frontend teams, PMs, and AI agents reviewing interface text before release. It is most useful when a screen already exists and the job is to make wording clearer, more actionable, and better matched to user context.

Real job-to-be-done

Users do not install clarify just to “rewrite copy.” They use it to answer tougher practical questions: why a message is failing, what users are likely to misunderstand, how much context to add, what tone fits the moment, and how to rewrite text so people can act without hesitation.

What makes clarify different from a generic prompt

The main differentiator is process. The skill is not a freeform “make this nicer” prompt. It pushes a structured review of:

• audience technical level
• user mental state
• action the user needs to take
• context missing from the current text
• specific clarity failure types such as jargon, ambiguity, assumptions, or tone mismatch

That makes clarify skill more useful than a loose copy-polish prompt when the stakes are functional comprehension, not style alone.

Important adoption caveat

The biggest blocker is dependency on prior design context. The skill explicitly requires /frontend-design, and if no design context exists yet, it says you must run /teach-impeccable first. So clarify install is easy at the skill level, but good output depends on whether you can supply product, audience, and interface context up front.

How to Use clarify skill

clarify install and invocation

The repository excerpt shows clarify as a user-invocable skill with argument hint [target]. In practice, install it from the pbakaus/impeccable repository and invoke clarify against a specific screen, flow, component, or copy block rather than a vague product-wide request.

A practical install pattern is:

• add the skill from https://github.com/pbakaus/impeccable
• invoke clarify with a target such as a modal, checkout error, onboarding step, or settings page

If your environment supports named skill install commands, use the repo URL plus the clarify skill path. If not, import the repository’s skill set and call clarify directly.

Read this file first

Start with:

• SKILL.md

This skill has no visible supporting README.md, metadata.json, rules, or resource folders in the provided tree. That means most of the real usage guidance is concentrated in SKILL.md, and there is less hidden implementation depth than in larger skills.

Required context before using clarify skill

Before asking clarify to rewrite anything, gather:

• the exact current copy
• where it appears in the UI
• who the audience is
• the user’s likely mental state at that moment
• the action users should take next
• any product or domain constraints

This matters because the skill evaluates clarity in context, not in isolation. A technically correct rewrite can still fail if it ignores urgency, trust, or user expertise.

Why the frontend-design dependency matters

clarify usage is explicitly chained to /frontend-design. That is a strong signal that the skill expects design principles and a context-gathering protocol to happen first. If you skip that step, the output may be linguistically cleaner but still wrong for the flow, hierarchy, or user goal.

If no design context exists, the skill instructs you to run /teach-impeccable first. Treat that as required setup, not optional polish.

What input produces the best results

Strong inputs are concrete and bounded. For example, provide:

• current text: “Authentication failed”
• surface: login form error under password field
• audience: non-technical SaaS users
• mental state: frustrated, trying to get back into work quickly
• desired action: retry password, reset if needed
• constraint: do not imply the email is wrong for security reasons

That will produce better output than:

• “Improve this error message”

Turn a rough request into a good clarify prompt

Weak:

• “Make our onboarding copy clearer.”

Better:

• “Use clarify on step 2 of onboarding. Current copy: ‘Configure your workspace for enhanced collaboration efficiency.’ Audience: first-time small business users with low technical confidence. Mental state: curious but impatient. Goal: get them to invite teammates. Constraint: keep headline under 8 words and body under 20 words.”

The better version gives clarify skill enough information to judge jargon, missing context, action clarity, and tone.

What clarify is likely to inspect

Based on SKILL.md, the skill systematically checks for:

• jargon users may not understand
• ambiguity and multiple interpretations
• passive voice that hides agency
• copy that is too long or too terse
• assumptions about user knowledge
• missing context about what happened or what to do next
• tone mismatch for the situation

This is useful because it tells you what kinds of problems the skill is optimized to catch.

Suggested workflow for clarify usage

A practical workflow:

1. Run /frontend-design and gather context.
2. Select one target surface, not an entire app.
3. Paste the exact current copy.
4. State audience, mental state, and desired next action.
5. Ask for a diagnosis first, then rewrites.
6. Review the output against UI space and product constraints.
7. Test the revised text on adjacent states like success, loading, and failure.

This sequence usually yields better decisions than asking for instant rewrites without diagnosis.

Ask for diagnosis before final rewrites

For high-signal clarify guide usage, first ask:

• what is unclear
• what the user might misunderstand
• what context is missing
• whether the tone fits the moment

Then ask for alternatives. This prevents premature rewriting and helps you decide whether the real issue is wording, information architecture, or missing system feedback.

Best use cases for clarify for UI/UX Design

The skill is especially strong for:

• error messages that do not explain what happened or what to do next
• labels that rely on internal terminology
• onboarding instructions that assume prior knowledge
• empty states with vague or unhelpful direction
• settings descriptions that are technically accurate but hard to parse
• confirmation and success messages that do not build confidence

When clarify is a poor fit

Do not expect clarify to solve:

• deeper UX flow problems where the interface is structurally confusing
• legal or compliance copy that cannot be materially changed
• pure brand voice work where clarity is already good
• localization-ready writing without separately checking translation constraints

If the problem is interaction design rather than wording, use clarify after the flow itself is fixed.

clarify skill FAQ

Is clarify skill beginner-friendly?

Yes, if you can provide the current text and basic context. But beginners often skip the hard part: describing audience and user state. Without that, clarify can still improve phrasing, but not reliably improve usability.

Do I need the whole impeccable repo to use clarify?

You mainly need the clarify skill plus its required context dependency. Since the visible tree only exposes SKILL.md for this skill, there is not much extra repo material to study first. The key requirement is access to /frontend-design and, if needed, /teach-impeccable.

How is clarify different from asking an AI to rewrite copy?

A normal prompt often optimizes for sounding polished. clarify skill is better when you need the AI to inspect comprehension risks: jargon, assumptions, ambiguity, missing next steps, and tone under real user conditions.

Can clarify handle error messages well?

Yes. Error states are one of the strongest fits because the skill explicitly asks for the user’s mental state and next action. That leads to more useful rewrites than generic “friendly error message” prompting.

Is clarify only for microcopy?

No. It can also help with short instructions and interface guidance. But it is best on bounded UI text, not long-form marketing pages or content design systems.

When should I not install clarify?

Skip clarify install if your main need is visual design critique, IA restructuring, or content strategy for long documents. Install it when wording clarity inside product interfaces is the real bottleneck.

How to Improve clarify skill

Feed clarify better context, not more text

The fastest way to improve clarify output is to provide better constraints:

• exact UI location
• character limits
• audience expertise
• emotional state
• desired action
• forbidden claims or legal limits

More surrounding copy is only helpful if it changes interpretation.

Separate diagnosis from rewriting

Ask clarify for a short problem list before requesting final copy. This exposes whether the issue is ambiguity, missing context, or tone mismatch. You get better revisions when the failure mode is named first.

Show the current and desired user action

Many weak outputs happen because the model does not know what the user should do next. Include both:

• what just happened
• what the user should do now

For example, “payment failed” is incomplete unless the skill knows whether the right action is retry, update card, contact support, or wait.

Include mental state explicitly

This skill places unusual weight on user mental state, and that is one of its strongest practical levers. “User is stressed and blocked” should produce different copy from “user is exploring settings casually.” If you omit this, the tone may become generically pleasant instead of genuinely useful.

Request alternatives with tradeoffs

Ask for 2 to 4 options with different priorities, such as:

• shortest version
• most reassuring version
• most action-oriented version
• plainest version for non-technical users

That helps you compare clarity tradeoffs instead of accepting one rewrite as final.

Watch for common failure modes

Common ways clarify skill can still underperform:

• polishing wording without fixing missing context
• making copy friendlier but less specific
• removing technical terms that users actually need
• producing text too long for the UI component
• rewriting isolated strings inconsistently with adjacent states

These are usually input problems, not just model problems.

Use real UI constraints during iteration

After the first pass, tighten the request:

• “Keep label under 24 characters”
• “Do not mention internal system names”
• “Must be understandable at 8th-grade reading level”
• “Should not blame the user”
• “Preserve security ambiguity around account existence”

This is where clarify guide usage becomes production-ready instead of merely editorial.

Pair clarify with adjacent screen review

Do not improve one message in isolation if users encounter a sequence. Review the trigger, the message itself, and the next step together. A clear error line can still fail if the CTA label or helper text around it remains vague.

Build a reusable prompt template

For teams using clarify for UI/UX Design repeatedly, create a template with:

• target surface
• current copy
• audience
• mental state
• desired action
• constraints
• ask: diagnose first, then rewrite

That reduces inconsistency across reviews and makes the skill much easier to invoke well.

Improve clarify output with evidence from users

If you have support tickets, usability notes, or examples of users misreading the text, include them. clarify is much stronger when it can rewrite against observed confusion instead of hypothetical confusion.