clarify

clarify skill の概要

clarify skill は、わかりにくい UI テキストを書き直し、ユーザーが「何が起きたのか」「次に何をすべきか」「それがなぜ重要なのか」を理解しやすくするためのスキルです。とくに UI/UX Design の実務向けに作られており、プロダクト内に曖昧なラベル、弱いエラーメッセージ、追いにくい案内文、技術的には正しくても実ユーザーには伝わりにくいマイクロコピーがある場合に力を発揮します。

clarify が最も向いている用途

clarify を使うべきなのは、まずレイアウトや操作フローよりも、インターフェース内の文言そのものが問題になっているケースです。

• 結果が想像できないボタンラベル
• ユーザーを助けるよりシステム事情を説明してしまうエラーメッセージ
• 次の一手が示されていない empty state
• 前提知識を求めすぎるフォームの補足テキスト
• 内容は正確でも、ストレス下では理解負荷が高い案内文

この性質から、clarify skill は、ローンチ前にユーザー向け文言を磨き込みたいプロダクトデザイナー、UX ライター、フロントエンドチーム、創業者に特に適しています。

clarify が実際に担う仕事

clarify の実務上の役割は、粗い・不明瞭な UI コピーを、次のようなテキストに変えることです。

• ひと目で把握しやすい
• 次の行動に移しやすい
• ユーザーの知識レベルに合っている
• その場の感情状態に合っている

最後の点は重要です。元の 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 / design system ワークフローの中で動く前提の skill です。

clarify skill の使い方

適切なリポジトリ文脈で clarify を導入する

clarify install の流れは、pbakaus/impeccable repo のホスト skill システムに従います。Skills 互換の環境を使っているなら、その repo を追加し、そこから clarify skill を呼び出します。skill 本体の場所は次のとおりです。

/.agents/skills/clarify/SKILL.md

リポジトリ上で確認できるのが SKILL.md のみなので、追加の補助アセットがある前提では進めず、まずこのファイルを読むのが確実です。

最初の実行前に読むべきファイル

まず確認すべきなのは次です。

• SKILL.md

実際の運用ロジックはここに集約されています。必要な事前準備、評価基準、コピーを見直す手順がまとまっているからです。表に出ているサポートスクリプトや参照ファイルは見当たらないため、この skill の価値は手順の順番を正しく踏むことにあります。

必須の依存関係は省略しない

clarify を使う前に、この skill は次の実行を求めています。

• /frontend-design

さらに、まだデザイン文脈がない場合は次も必要です。

• /teach-impeccable

新規ユーザーにとって最大の導入障壁はここです。この準備を飛ばすと、文面自体はそれなりに整っても、UX としての判断は弱くなりがちです。clarify は、設計原則と文脈整理が先に済んでいることを前提にしています。

clarify がうまく機能するために必要な入力

clarify usage に最低限必要なのは、現在のテキストと、それがどこに表示されるかです。より良い結果を得るなら、次も添えるべきです。

• 対象の画面またはフロー
• 正確な UI 要素の種類
• 想定ユーザーの technical level
• その時点でのユーザーの mental state
• 読んだ後に取ってほしい行動
• tone、brand voice、文字数制限などの制約

これらがない場合でも書き換え自体は可能ですが、適切な直接性、情報量、感情トーンを安定して選ぶのは難しくなります。

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 プロンプトに変える

出発点が「アプリの文言をもっとわかりやすくしたい」なら、次の構造に落とし込むと実用的です。

1. 現在のコピー
2. プロダクト内の場所
3. ユーザー像
4. ユーザーがしようとしていること
5. そのときの感情状態
6. 次に取ってほしい行動
7. 長さや tone の制約

この構造は、skill のチェックリストから読み取れる実際の clarify guide にかなり近い形です。

実務での clarify usage におすすめの進め方

安定して使えるワークフローは次のようになります。

1. /frontend-design でプロダクトとデザインの文脈を整理する。
2. 対象ユーザーのレベルと mental state を確認する。
3. 元のコピーを表示どおり正確に貼る。
4. その画面と、ユーザーにしてほしい行動を説明する。
5. いきなり書き換えではなく、まず診断、その後に書き換え案を求める。
6. 1 つ方向性を選び、tone、簡潔さ、具体性を調整しながら詰める。

この「まず診断」が重要です。clarify は単に置き換えるためではなく、コピーが なぜ わかりにくいのかを特定する設計になっています。

書き換え前に clarify に診断させる

汎用的な LLM の文章磨き以上の価値を得るには、出力を 2 段階に分けて依頼すると効果的です。

• 見つかった 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 がやや不向きな場面

実際の問題が次にある場合は注意が必要です。

• 間違った product flow
• 欠けている機能
• 弱い information architecture
• ほとんど変更できない legal / compliance wording
• 長文の marketing copy

こうしたケースでは、clarify によって読みやすさは上がっても、根本原因までは解決できません。

clarify skill の FAQ

clarify は UX ライター専用ですか？

いいえ。clarify は、インターフェース文言を担当するデザイナー、PM、エンジニア、創業者にも有用です。必要なのは UX ライティングの専門訓練よりも、ユーザーとその場面に関する十分な文脈を渡せることです。

clarify は初心者でも使いやすいですか？

概ね使いやすいですが、依存関係の流れを見落とさないことが前提です。元の skill では、書き換えの前に /frontend-design、場合によっては /teach-impeccable も必要です。そこを無視すると、「中身の薄い skill」に見えるかもしれませんが、実際の想定ワークフローは context-first です。

普通の「これを書き換えて」プロンプトより clarify が優れている点は何ですか？

最大の利点は、構造化された診断です。clarify は、jargon、ambiguity、passive voice、missing context、ユーザー知識への過剰な assumptions など、混乱の原因を具体的に見にいきます。その結果、インターフェース文言では、より実務的で使える書き換え案になりやすいです。

clarify を使わないほうがいいのはどんなときですか？

コピーが、より深いプロダクト上の問題の「症状」にすぎない場合は、clarify に頼るべきではありません。たとえば、ユーザーが混乱している理由が、フローの破綻、権限設計の不明瞭さ、UI 上で重要情報が隠れていることにあるなら、文言改善だけでは解決しません。

clarify はエラーメッセージに向いていますか？

はい。これは最も明確なユースケースの 1 つです。この skill はユーザーの mental state を明示的に考慮するため、ログイン失敗、決済トラブル、フォーム検証エラーのようなストレスの高い場面で特に有効です。

clarify は tone や brand voice の調整にも使えますか？

はい。ただし、制約を明示した場合に限ります。たとえば “plain but premium” “friendly but not playful” “supportive under stress” のような要件があるなら、そのまま伝えるべきです。そうしないと、skill は主に clarity を優先して最適化します。

clarify skill を改善するには

文だけでなく、ユーザーの状態を clarify に渡す

もっとも効果が大きい改善は、ユーザーの状況を具体的に伝えることです。

• first-time か expert か
• calm か stressed か
• browsing 中か、失敗からの recovery を急いでいるのか
• desktop か mobile か
• attention が高いか低いか

この情報によって、最適なコピーが「より短いべきか」「より温かいべきか」「より明示的にすべきか」「より手順的にすべきか」が変わります。

isolated text ではなく、周辺 UI ごと渡す

ラベルやメッセージは、周辺文脈が欠けているせいで悪く見えることが少なくありません。clarify の結果を良くしたいなら、次も含めましょう。

• 近くにある fields や buttons
• page title
• 直前のステップ
• 次に期待する行動

一見「悪い」1 行でも、ある画面では妥当で、別の画面では有害ということがあります。

複数の書き換え戦略を求める

1 つの答えだけを求めるのではなく、たとえば次のような選択肢を依頼すると有効です。

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

これは特に clarify for UI/UX Design で有効です。チームはしばしば、簡潔さ、tone、ガイダンス量のどこを優先するかを調整する必要があるからです。

文字数やレイアウト制約は早めに伝える

そのコピーが button、toast、modal、mobile の form field に収まる必要があるなら、最初に伝えてください。そうしないと clarify は、理論上は明快でも、実際の UI には置けない文案を返すことがあります。

よくある失敗パターンに注意する

clarify を使っていても、チームは次のような書き換えを採用してしまいがちです。

• わかりやすいが長すぎる
• 親しみやすいが曖昧
• 正確だが技術的すぎる
• きれいだが実際のタスクから切り離されている

文章の出来栄えだけでなく、ユーザーに取ってほしい行動に照らして評価してください。

wording だけでなく診断自体を反復する

最初の結果がずれていた場合、単に「もっと短く」と頼むだけでは不十分です。skill が何を取り違えたのかを確認しましょう。

• audience assumption が違う
• mental state の想定が違う
• product context が足りない
• 単純化しすぎている
• 次のステップの説明が足りない

こちらを詰めたほうが、表面的な編集を重ねるよりも、その後の出力改善が速くなります。

1 文修正ではなく、画面単位のレビューと組み合わせる

実務で clarify skill の効果を最大化するには、1 文の修正ツールとしてではなく、画面レビューの一部として使うのが最善です。関連するコピーをまとめて見てください。

• 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 が安定し、文脈不足の依頼から生まれる無難な出力を減らせます。