clarify

clarify skill 概览

clarify skill 用于改写令人困惑的 UI 文案，让用户能看懂发生了什么、下一步该做什么，以及这件事为什么重要。它面向 UI/UX design work，尤其适合产品里存在以下问题时使用：标签含义模糊、错误提示无效、操作说明难以跟随，或 microcopy 虽然技术上没错，却依然让真实用户看不懂。

clarify 最适合解决什么问题

当问题的核心首先不是布局或交互流程，而是界面里的文案表达时，就该用 clarify：

• 按钮文案看不出点击后会发生什么
• 错误信息只是在解释系统，没有帮助用户解决问题
• 空状态没有给出下一步
• 表单帮助文本默认用户已经懂很多背景知识
• 操作说明虽然准确，但在高压场景下读起来负担很重

因此，clarify skill 很适合产品设计师、UX writer、前端团队，以及上线前要打磨用户可见文案的创始人使用。

clarify 真正解决的是什么工作

从实操角度看，clarify 的职责是把粗糙、含混的界面文案，改成更符合使用场景的表达，让文本做到：

• 更容易扫读
• 更容易促成下一步操作
• 更贴合用户的知识水平
• 更贴合当下的情绪场景

最后一点尤其关键。这个 skill 明确要求你提供用户的 technical level 和 mental state in context，这比泛泛地说一句“帮我写清楚一点”有用得多。

clarify 和普通改写提示词有什么不同

普通提示词也许能把句子润色得更顺。clarify 的不同在于，它更关注文案为什么会失败，且判断标准更明确：

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

它还依赖更完整的设计上下文。这个 skill 要求先有 /frontend-design，如果这部分上下文还没有建立，还要先运行 /teach-impeccable。这点对安装决策很重要：clarify 不是一个独立的文案润色宏，而是被设计为在更大的 UX/设计系统工作流中使用。

如何使用 clarify skill

在正确的仓库上下文中安装 clarify

clarify install 路径遵循 pbakaus/impeccable 仓库所在宿主 skill 系统的方式。如果你使用兼容 Skills 的环境，把该 repo 加入后，再从其中调用 clarify skill。这个 skill 文件位于：

/.agents/skills/clarify/SKILL.md

由于目前仓库证据里只暴露了 SKILL.md，不要先假设还存在其他辅助脚本或资源；第一次使用前应先把这个文件读完。

第一次运行前先看这个文件

先看：

• SKILL.md

真正的运行逻辑都在这里：包括前置准备、评估标准，以及逐步执行的文案审查流程。当前没有可见的配套脚本或参考文件，因此是否按对顺序使用这个 skill，基本决定了它的实际价值。

不要跳过必需的依赖

使用 clarify 之前，skill 明确要求先调用：

• /frontend-design

如果还没有任何设计上下文，则还需要先调用：

• /teach-impeccable

这通常是新用户采用 clarify 时最大的阻碍。如果跳过这一步，你也许仍能得到“还不错”的改写结果，但 UX 判断往往会变弱。因为这个 skill 默认设计原则和上下文收集已经先完成了。

clarify 需要什么输入，效果才会好

要让 clarify usage 起码可用，至少要提供当前文案，以及它出现的位置。想得到更好的结果，建议再补充：

• 目标页面或流程节点
• 具体的 UI 元素类型
• 受众的 technical level
• 用户当时的 mental state
• 读完后希望用户采取的动作
• 语气、品牌风格、字符限制等约束

如果缺少这些信息，这个 skill 依然能改写文本，但很难稳定判断到底该多直接、讲多细、情绪语气要怎么拿捏。

面向 UI/UX Design 的 clarify，什么样的提示词更好

一个较弱的请求是：

• “Improve this error message: Authentication failed.”

一个更强的请求是：

• “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.”

后者之所以更有效，是因为它补足了 skill 最需要的决策信息：受众、情绪、设备场景，以及成功标准。

把模糊目标改造成可用的 clarify 提示词

如果你的起点只是“把 app 文案写得更清楚”，建议改造成下面这个结构：

1. 当前文案
2. 在产品中的具体位置
3. 用户是谁
4. 用户当前想完成什么
5. 用户此刻处于什么情绪状态
6. 用户接下来应该做什么
7. 长度或语气上的限制

这个结构和 skill 清单中隐含的实际 clarify guide 高度一致。

实际使用 clarify 的推荐工作流

一个更稳妥的工作流通常是：

1. 先用 /frontend-design 收集产品和设计上下文。
2. 确认用户层级和 mental state。
3. 原样贴出当前文案，不要先自行改写。
4. 说明页面场景和期望的用户动作。
5. 先要求诊断，再要求改写方案。
6. 选定一个方向后，再迭代语气、长度或具体程度。

其中“先诊断”非常重要，因为这个 skill 的设计重点是找出文案为什么不清楚，而不只是替换成另一种说法。

让 clarify 先诊断，再改写

如果你想获得比通用 LLM 润色更高的价值，可以要求输出分两步进行：

• 先列出发现的 clarity issues
• 再给出改写后的 alternatives

例如：

• “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.”

这样团队在评审时就不只是“挑一个听起来最顺的版本”，而是能围绕具体判断依据做决定。

clarify 最擅长的场景

clarify skill 最擅长处理短而关键的 UI 文案，例如：

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

这些位置一旦表达不清，用户很快就会产生阻碍；而结合上下文改写，往往能直接提升完成率和使用信心。

clarify 不太适合的场景

如果真正的问题是以下这些，就要谨慎使用：

• 产品流程设计错误
• 功能本身缺失
• 信息架构差
• 法务或合规文案几乎不能改
• 长篇 marketing copy

在这些情况下，clarify 也许能提升可读性，但解决不了根因。

clarify skill 常见问题

clarify 只适合 UX writer 吗？

不是。clarify 同样适合设计师、PM、工程师和创始人，只要他们负责界面文案，即使不是专业 UX writer 也能用。关键前提是，你能提供足够的用户和场景上下文。

clarify 对新手友好吗？

大体上是友好的，但前提是你注意到它的依赖链。原始 skill 要求在改写前先运行 /frontend-design，必要时还要先跑 /teach-impeccable。很多新手忽略这一步后，会误以为 skill 很“薄”；实际上，它本来就是按“先上下文、后改写”的方式设计的。

clarify 比普通“rewrite this”提示词强在哪里？

最大的优势在于结构化诊断。clarify 会专门检查导致理解障碍的具体原因，比如 jargon、ambiguity、passive voice、missing context，以及对用户知识水平的错误预设。这通常能产出更适合界面文案的、可执行性更强的改写结果。

什么情况下不该用 clarify？

当文案问题只是更深层产品问题的表象时，不要优先使用 clarify。如果用户困惑的原因是流程本身坏了、权限规则不清，或者 UI 把关键信息藏起来了，那么单靠更好的措辞是无法解决问题的。

clarify 适合处理错误提示吗？

适合。这是它最明确的应用场景之一。该 skill 明确把用户的 mental state 纳入考虑，这对登录失败、支付异常、表单校验失败这类高压力时刻尤其重要。

clarify 能兼顾语气和品牌风格吗？

可以，但前提是你要明确给出约束。如果你想要的是“plain but premium”“friendly but not playful”或“supportive under stress”这类风格，请直接说清楚。否则，这个 skill 默认主要会优化 clarity。

如何提升 clarify skill 的使用效果

给 clarify 的不只是句子，还要给用户状态

最有杠杆效应的改进方式，是把用户所处的情况说清楚，例如：

• first-time 还是 expert
• calm 还是 stressed
• 是在浏览，还是在失败后试图恢复
• desktop 还是 mobile
• attention 高还是低

这些信息会直接影响最佳文案到底应该更短、更温和、更明确，还是更偏指导式。

提供周边 UI，而不是只给一句孤立文本

很多标签或提示之所以显得糟糕，是因为缺少周边上下文。想提升 clarify 的效果，建议一并提供：

• 附近的字段或按钮
• 页面标题
• 上一步是什么
• 预期的下一步动作是什么

同一句“看起来不够好”的文案，在某个页面里可能完全合理，在另一个页面里却会造成严重误导。

主动要求多种改写策略

不要只要一个答案，可以直接让它给出多个方向，例如：

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

这对 clarify for UI/UX Design 尤其有价值，因为团队常常需要在简洁度、语气和引导力度之间做权衡。

尽早说明字符数或布局限制

如果文案必须塞进 button、toast、modal 或 mobile 表单字段里，一开始就要讲清楚。否则 clarify 很可能给出“理论上更清楚、实际上放不下”的版本。

留意常见失败模式

即使用了 clarify，团队也常会接受一些看似更好、其实仍有问题的改写，例如：

• 更清楚了，但太长
• 更友好了，但过于模糊
• 更精确了，但技术味太重
• 更 polished 了，但脱离真实任务

评估输出时，不要只看写得顺不顺，更要对照你真正希望用户完成的动作来判断。

迭代时优先追问诊断，不只改表面措辞

如果第一轮结果没有打中目标，不要只说“再短一点”。更有效的做法是追问这个 skill 可能误解了什么，例如：

• 对受众的假设错了
• 对 mental state 的判断错了
• 缺少产品上下文
• 过度简化了
• 对下一步说明得不够

相比表层修词，这样更能加快后续输出质量的提升。

把 clarify 和整屏评审配合使用

在实际工作中，提升 clarify skill 效果的最好方式，是把它当成 screen review 的一部分，而不是一句一句单独修文案。把相关文案一起审：

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

这样能发现单句改写很难暴露出来的一致性问题。

为 clarify usage 保留一个可复用的提示词模板

一个简单好用的模板是：

• “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.”

这样能让团队内部的 clarify usage 更稳定，也能减少因为上下文不足而产出泛化答案的情况。