デザイン業務をSKILL.mdにまとめる Claude CodeとCodexで再利用する方法
デザインやアクセシビリティの確認を再利用できるスキルにまとめます。
画面を作るたびに、既存のプロジェクトを先に調べること、既存のボタンや色トークンを使うこと、キーボード操作と狭い画面での表示を確認することを説明していませんか。毎回プロンプトに同じ指示を貼る代わりに、SKILL.mdにまとめておけば、Claude CodeやCodexが必要なときに読み、手順を再利用できます。
スキルはモデルにデザイン判断を任せる仕組みではありません。チームが繰り返している判断や完了条件を、実務で使える形で伝える手順書です。
SKILL.mdとAgent Skillsの構造
Agent Skills標準では、SKILL.mdを中心とするフォルダとしてスキルを構成します。YAML frontmatterには必須項目のnameとdescriptionを記載し、本文には利用条件と実行手順を書きます。必要に応じて、例、チェックリスト、スクリプトなどを補助ファイルとして含められます。
Claude CodeとCodexではスキルを見つける場所や拡張機能が異なりますが、SKILL.mdを再利用可能なガイドとして使う点は共通しています。Claude Codeの公式資料によると、スキル本文は利用時に読み込まれます。Codexも名前と説明から関連性を判断した後、詳しい指示を読み込みます。説明には、どのような依頼で使うべきかを具体的に書きましょう。
デザインスキルの対象業務
一度きりの作業や、まだ方針が合意されていない試行にはスキルは不要です。複数の画面やプロジェクトで同じレビュー手順を使う、アクセシビリティ・レスポンシブ対応・状態の確認漏れが繰り返される、見た目そのものより作業手順を揃えたい、手順を安定した基準として説明できる場合に役立ちます。
「美しいカードUIを作る」では範囲が広すぎます。「既存のトークンを確認し、カードの通常・読み込み・エラー状態を定義した後、小さい画面とキーボードフォーカスを確認する」なら再利用できる手順です。
SKILL.mdの指示構成
1. スキルの実行条件
descriptionには、どの種類の依頼でスキルを使うべきかを書きます。「良いUIを作る」のような広い説明は誤った場面で選ばれやすく、範囲を絞りすぎると必要な依頼で使われないことがあります。
2. プロジェクトの事前調査
作業に入る前に確認する情報を挙げます。フレームワーク、既存コンポーネントやトークン、アクセシビリティ要件、対象画面幅などです。先に既存パターンを探せば、不要な重複を防ぎやすくなります。
3. デザイン作業の手順
動詞を使って具体的な手順を書きます。「デザインの一貫性を保つ」では曖昧です。「既存のボタンバリエーションと色トークンを検索し、適切なものがあれば再利用する」なら実行に移せます。
4. 検証と完了条件
完了条件はレビューの基準として書きます。たとえば、画面幅を変えても主要な操作ができること、必須項目のエラーが表示されること、キーボードだけで主要なフローを操作できることを確認します。
デザインスキルの記述例
既存のプロダクトUIを拡張するときに使える、簡単なスキルの例です。名前とレビュー項目はプロジェクトに合わせて調整してください。
---
name: product-ui-workflow
description: 既存のWebプロダクトで画面やコンポーネントを追加・変更するときに使う。既存のUIルールを先に調べ、アクセシビリティ、レスポンシブ表示、状態を確認する。
---
## プロダクトUIの作業手順
1. 変更前にフレームワーク、既存コンポーネント、トークン、画面構成、関連するUX要件を調べる。
2. 再利用できる既存パターンを探す。新しいパターンが必要なら、解決するユーザーの課題を一文で説明する。
3. 実装前に通常、読み込み、空、エラー、無効状態のうち必要な状態を定義する。
4. 既存のトークンや文言ルールを優先する。新しい色・余白・バリエーションを追加する場合は理由を説明する。
5. 狭い画面と広い画面で内容や操作が隠れないことを確認する。
6. キーボードフォーカス、操作順、アクセシブルな名前、エラーメッセージを確認する。
7. 変更した画面と動作、実施した確認、残っている制約を簡潔にまとめる。
このファイルだけで完成したUIが保証されるわけではありません。どのコンポーネントが適切か、エラーをどんな言葉で伝えるか、小さい画面でどの情報を優先するかは、プロダクトの背景に応じて判断する必要があります。スキルは基準を思い出し、レビューを繰り返す助けになります。
Claude CodeとCodexのスキル配置先
Claude Codeの公式資料では、プロジェクト用スキルを.claude/skills/<skill-name>/SKILL.md、個人用スキルを~/.claude/skills/<skill-name>/SKILL.mdに置きます。フォルダ名は/skill-nameで直接呼び出す際にも使われます。
Codexでは、リポジトリで共有するスキルを.agents/skills/<skill-name>/SKILL.md、個人用を~/.agents/skills/<skill-name>/SKILL.mdに置けます。Codexアプリからスキルを作成・管理することもできます。リポジトリ内のスキルはコードと一緒にバージョン管理でき、個人用スキルはその人の環境に残ります。検出方法や配置場所は更新される可能性があるため、チームに配布する前に最新の公式資料を確認してください。
デザインスキルの指示の保守
- 事実と手順を分ける。長いトークン一覧などは別ファイルにし、いつ読むべきかをスキル内に記す。
- プロジェクトに特定のコンポーネントがあると決めつけない。まず検索するよう指示する。
- エージェントが利用できないツールやファイルを前提にしない。不足する情報を求めるか、提供された資料の範囲で作業する。
- 例外も説明する。既存トークンで要件を満たせないときは、盲目的に従わせず、理由の記録やレビュー方法を示す。
- 実際の利用に基づいて改善する。飛ばされた手順を明確にし、役に立たない一般論を削る。
共有前のチェックリスト
- 名前と説明だけで、どの依頼に使うか分かるか。
- 最初に実際のプロジェクトを調べる手順があるか。
- 手順が具体的な行動として書かれているか。
- 見た目に加えて、状態・キーボード操作・レスポンシブ表示を確認するか。
- 利用できないツールやファイルを前提としていないか。
- チームが変更をレビューできるよう、バージョン管理するか。
繰り返しの説明をスキルにまとめれば、毎回長いプロンプトを書く負担を減らせます。同時に、チームの品質基準と、人が判断すべき点も明確になります。