polish

polish skill の概要

polish ができること

polish skill は、出荷前の最後に行う UI レビュー向けのワークフローです。完成した画面に対して、仕上がりを不揃い・未完成・想定より低品質に見せてしまう細かな問題を拾うことに特化しています。すでに画面としては動いていて、リリース前に整列、余白、インタラクション状態、コピーの一貫性、エッジケース、見た目や操作感の滑らかさを整えたい場面で力を発揮します。

polish を使うべき人

この polish skill は、すでに動くインターフェースを持っていて、構造化された品質チェックを入れたいデザイナー、フロントエンドエンジニア、AI を活用して実装を進めるビルダーに向いています。
特に、「最後の詰めをしたい」「なんとなく違和感がある」「本番品質にしたい」「良い状態からもう一段上げたい」といった依頼に合います。

polish skill が本当に解決する仕事

ユーザーが polish を導入する理由は、単なるデザインの感想をもらうためではありません。目的は、出荷前の体系的な最終確認を回して、目立つマイクロな不備を見落とさないようにすることです。

• 余白ルールが揃っていない
• グリッドからズレた整列
• hover、focus、loading、error の状態不足
• コピーのトーンやラベル表記の揺れ
• 遷移やインタラクション細部の粗さ

この polish skill が他と違う点

最大の違いは、polish が明確に 最後の一手のための skill として設計されていて、広範な再設計ツールではないことです。さらに、上流のデザイン文脈に依存します。リポジトリでは、まず /frontend-design を実行し、まだデザインコンテキストがない場合は polish の前に /teach-impeccable を走らせるよう求めています。
この依存関係は重要です。polish は、すでにデザインの方向性や品質基準が存在している前提で、その基準に照らして仕上げを評価する skill だからです。

polish が強くハマるケース

次の条件なら polish はかなり有効です。

• UI が機能面では完成している
• リリース前に最終品質チェックを入れたい
• 問題の中心がプロダクト戦略ではなく一貫性にある
• 対象の画面、コンポーネント、またはフローを明示できる
• 求める水準が MVP か flagship か分かっている

polish を使うべきでないケース

次の段階では、最初に polish を使うのは適切ではありません。

• まだ機能要件や仕様を固めている途中
• 主要フローが壊れている、または未完成
• 大きな UX 再構成が必要
• まだデザインコンテキストがない
• チーム内でどこまで磨き込むべきか決まっていない

polish skill の使い方

skills 環境に polish を追加する

このリポジトリでは SKILL.md 内に専用の install コマンドは書かれていないため、多くのユーザーは skills manager 経由でソースリポジトリから追加する形になります。よくあるパターンは次のとおりです。

npx skills add pbakaus/impeccable --skill polish

環境ごとにインストーラーが異なる場合は、次の場所から skill を追加してください。

https://github.com/pbakaus/impeccable/tree/main/.agents/skills/polish

最初に読むべきファイル

最初に確認するのは次です。

• SKILL.md

この skill は自己完結型です。skill フォルダ内に resources/、rules/、補助スクリプトのような追加要素は表に出ていないため、実際に使ううえで重要なワークフローはほぼこの 1 ファイルにまとまっています。

必須の依存チェーンを守る

polish を呼ぶ前に、リポジトリのガイドではまず次を実行するよう指定されています。

• /frontend-design

さらに、まだデザインコンテキストが確立していない場合は、先に次を実行する必要があります。

• /teach-impeccable

これは導入時にいちばん重要なポイントです。この文脈なしで polish を使うと、「余白をもっと揃える」程度の浅い指摘に寄りやすく、実際のデザイン原則に結びついた精度の高い仕上げレビューになりません。

polish に必要な入力を把握する

polish skill が最も機能しやすいのは、次の情報を渡したときです。

• 対象を正確に示すこと: ページ、コンポーネント、またはフロー
• 現在のスクリーンショット、またはコード上の文脈
• 目指す品質水準: MVP か flagship
• 既知の不備を今回直すのか、それとも TODO として残すのか
• 出荷までの期限、または polish に割ける時間

これらの入力は出力を大きく左右します。たとえば flagship のマーケティングページと、MVP の社内ツールでは、入るレビューの深さも優先順位も変わります。

ざっくりした依頼を使える polish プロンプトに変える

弱いプロンプト:

Polish this UI.

より良いプロンプト:

Use polish on the checkout flow. The flow is functionally complete. Quality bar is flagship. Keep the current structure, do not redesign the information architecture. Focus on alignment, spacing consistency, interaction states, error handling, and copy consistency. We have one day before ship, so prioritize high-visibility issues first.

この形が機能する理由は次のとおりです。

• 仕上げレビューに入れる状態かどうかを明示できる
• スコープが定まる
• 意図しない再設計を防げる
• 現実的な時間制約を共有できる
• どこまで深く見るべきかを skill に伝えられる

まずは狭い対象に polish を使う

引数ヒントは [target] です。これは重要な手がかりで、プロダクト全体への漠然としたレビューではなく、具体的な対象を渡すほうが向いていると分かります。良い例は次のようなものです。

• polish pricing page
• polish onboarding modal
• polish dashboard table states
• polish mobile settings flow

「アプリ全体を polish して」といった広すぎる依頼より、狭い対象のほうが実装に落とし込みやすい出力になりやすいです。

想定されたワークフローに沿って進める

実務的な polish の使い方は、次の流れが自然です。

1. UI が機能面で完成していることを確認する。
2. /frontend-design を通してデザインコンテキストを集める。
3. まだデザインコンテキストがない場合は /teach-impeccable を実行する。
4. 品質水準と時間予算を定義する。
5. 具体的な対象を指定して polish にレビューさせる。
6. ランダムに直すのではなく、カテゴリごとに修正する。
7. 修正後の結果に対して polish を再実行し、最終確認を行う。

これは、細部に手を入れる前に事前評価を重視するというリポジトリの考え方にも沿っています。

polish が見にいく可能性が高いポイント

ソースを見る限り、polish は次のような観点を体系的にチェックします。

• 視覚的な整列
• 余白の一貫性
• インタラクション状態の網羅性
• コピーの一貫性
• エッジケースとエラー状態
• ローディングや遷移の滑らかさ

この情報は実用的です。というのも、どんな材料を渡すべきかが分かるからです。静的な UI マークアップだけを貼ると、loading、transition、state まわりのフィードバックは取りこぼしやすくなります。

ハッピーパスだけでなく状態を見せる

polish が期待ほど機能しない典型的な理由は、状態の情報が不足していることです。可能であれば、次を含めてください。

• default state
• hover/focus/active states
• validation errors
• empty states
• loading states
• disabled states
• success confirmation states

こうすることで、本番で実際にユーザーが気づく「もう少しで完成なのに惜しい」問題を polish skill が拾いやすくなります。

polish の出力は可視性と工数で優先順位付けする

リリースが近いなら、polish に対して指摘を次のように分類するよう頼むと有効です。

• must fix before ship
• nice to have
• can defer

とくに品質基準が高い一方で時間が足りないとき、これは単なる批評の羅列よりずっと使いやすくなります。

実用的なリポジトリ読解ルート

このフォルダで表に出ているのが SKILL.md だけなので、読む順番としては次が効率的です。

1. description と argument-hint を確認する
2. MANDATORY PREPARATION を読む
3. Pre-Polish Assessment を読む
4. 体系化された polish のカテゴリを、そのままチェックリストとして使う

これだけで、リポジトリを過剰に読み込まなくても、適合性の判断と実運用の開始までは十分進められます。

polish skill FAQ

polish は普通のプロンプトより優れている？

多くの場合、最終品質チェックが課題なら yes です。通常のプロンプトだと、広い意見や再設計寄りの提案になりがちです。polish skill はもっと絞られていて、すでに実装済みであることを前提に、プロジェクト終盤で見落としやすい細部を重点的に見ます。

polish は UI Design 専用？

主な用途は polish for UI Design とフロントエンド体験の品質向上です。ソースでも、整列、余白、インタラクション状態、エッジケース、滑らかさが強調されているため、バックエンドアーキテクチャやプロダクト戦略より、インターフェース改善のほうがはるかに相性が良いです。

初心者でも polish skill を使える？

使えます。ただし初心者ほど、前提情報を多めに渡す必要があります。自分のプロジェクトにおける「quality bar」や「design context」がまだ曖昧なら、先に必須の上流デザイン skill を実行してください。そうしないと、出力自体はもっともらしく見えても、内容がぼんやりしやすくなります。

polish を使う前にコードは完成している必要がある？

完全である必要はありませんが、少なくとも十分に実装された状態、またはそれに準ずるプロトタイプは必要です。リポジトリでも、polish は最初の工程ではなく最後の工程だと明言されています。主要な挙動がまだ変わり続けている段階では、フィードバックが不安定になり、価値も下がります。

導入時の最大のつまずきどころは？

最大の障害は、必須の事前準備を飛ばしてしまうことです。polish を入れても、/frontend-design の文脈なしに呼び出すと、この skill の信頼性を支えている大事な部分を活かせません。

MVP 作業でも polish は使うべき？

使って問題ありません。ただし、品質水準が MVP であることは必ず伝えてください。そこによってレビューの深さが変わります。MVP では、完璧さを追いすぎず、もっとも目につく不整合や状態抜けを拾う用途で使うのが最も効果的です。

どんなときは polish を使わないほうがいい？

次のようなものが必要なら、polish は見送ったほうがよいです。

• 全面的な再設計
• プロダクトディスカバリー
• ユーザーリサーチの統合や整理
• アーキテクチャ変更
• 未完成のコア機能

こうしたケースでは、別の skill か、デザイン／エンジニアリングの直接的なワークフローを先に使うほうが適しています。

polish skill を改善するには

対象をもっと具体的にする

polish の出力を最も速く改善する方法は、対象を具体化することです。たとえば次を比べてください。

弱い例:
Use polish on my app.

より良い例:
Use polish on the mobile checkout summary card and payment error state.

対象が具体的になるほど、一般論は減り、そのまま修正に移せる指摘が増えます。

品質水準を明示する

ソースが MVP vs flagship をわざわざ挙げているのには理由があります。ここを指定しないと、シンプルな社内ツールを過剰にレビューしたり、公開直前の重要画面を浅くしか見なかったりします。どの水準を求めるのかは毎回はっきり伝えるべきです。

変えてはいけない部分を polish に伝える

構造、レイアウト、ブランド表現を動かせないなら、最初にそう書いてください。たとえば次のように伝えます。

Polish this settings page without changing the information architecture or component library.

こうしておくと、仕上げの品質向上に集中しやすくなり、再設計の方向へ流れにくくなります。

TODO のまま残す既知の問題を含める

この skill は、既知の問題を残すかどうかを確認する設計になっています。実務ではここが重要です。意図的に先送りしている不具合があるなら、最初から共有してください。そうしないと、レビューの往復が無駄に増えます。

指摘をカテゴリ別に出してもらう

強いプロンプト形式の例は次です。

Use polish on [target]. Group findings into spacing/alignment, interaction states, copy consistency, edge cases, and motion/loading. For each item, say why it matters and whether it is must-fix or nice-to-have.

これはリポジトリの体系的な進め方と噛み合っていて、実装にも移しやすくなります。

抽象的な目標だけでなく、スクリーンショットや UI 状態を渡す

出荷品質の体験を本当に改善したいなら、polish に観察可能な材料を渡すべきです。強い入力の例は次のとおりです。

• screenshots
• component code
• state descriptions
• acceptance criteria
• brand or design-system constraints

見える証拠が多いほど、一般論に頼らず、具体的な指摘を返しやすくなります。

よくある失敗パターンを把握する

polish の結果が崩れやすいのは、次のような場合です。

• 機能が実際にはまだ完成していない
• 対象が広すぎる
• デザインコンテキストがない
• ハッピーパスしか見せていない
• チーム内で「done」の定義がない

多くの「polish の出力がいまいち」という問題は、実際には入力かタイミングの問題です。

修正後に polish を再実行する

良い運用は 1 回で終わりません。2 パス前提で考えるのが有効です。

1. 1 回目で問題を見つける
2. 実装で修正する
3. 2 回目で回帰や、新たに目立つ不整合を確認する

これは、余白スケール、コンポーネント状態、コピーのパターンを複数画面にまたがって変更した後に特に効果的です。

批評ツールではなく、出荷前チェックリストとして polish を使う

最も成果が出やすいのは、ship 前に順番に潰せる短い実行可能チェックリストを作らせる使い方です。そうすると polish は主観的なフィードバック装置ではなく、実務の実行支援ツールになります。そこが、この polish skill の価値が最も出るポイントです。