🧭 本記事は Claude Code実務運用シリーズ の STEP 4「カスタムコマンド化する」です。
公式の標準Skillに続き、外部コミュニティのSkill「apple-design」を導入し、Appleのデザイン原則をAIコーディングに取り込みます。
シリーズ全体の地図と読む順は 親記事 にまとめています。
はじめに
CodexやClaude Codeは、SKILL.md にまとめられた専門知識や作業手順を読み込み、特定分野に強いAIコーディングエージェントとして動作できます。
今回は、デザインエンジニアのEmil Kowalski氏が公開している apple-design Skillを、CodexとClaude Codeの両方へ導入する方法を解説します。
対象のSkillはこちらです。
emilkowalski/skills - apple-design
この記事では、次の内容を扱います。
-
apple-designSkillで何ができるのか - Codexへの導入方法
- Claude Codeへの導入方法
- 日本語プロンプトでの呼び出し方
- 実務で使えるプロンプト
- SwiftUIやUIKitへ適用するときの注意点
- チーム運用するときの設計
この記事の内容は、2026年7月21日時点の公式ドキュメントと公開リポジトリを基にしています。Skillsの保存場所や呼び出し方法は今後変更される可能性があるため、導入時には最新の公式ドキュメントも確認してください。
Agent Skillとは
Agent Skillは、AIエージェントへ専門知識や再利用可能な作業手順を追加する仕組みです。
基本構成は、次のようなディレクトリです。
my-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/
必須なのは SKILL.md です。
SKILL.md の先頭には、Skill名や適用条件を記載します。
---
name: my-skill
description: このSkillが何を行い、どのような場面で使用するか
---
その後に、AIエージェントが従うべき判断基準や作業手順をMarkdownで記述します。
CodexとClaude Codeは、タスクとSkillの description が一致すると自動的にSkillを読み込めます。また、利用者がSkill名を指定して明示的に呼び出すこともできます。
Agent Skillsの基本仕様については、以下を参照してください。
apple-design Skillとは
apple-design は、Appleのインターフェース設計と流動的なモーションに関する考え方を、AIコーディングエージェントへ与えるSkillです。
Skillの説明には、次のように記載されています。
Apple's approach to interface design and fluid, physical motion, translated for the web.
扱われている主なテーマは、入力に対する即時反応、ドラッグ操作への追従、中断可能なアニメーション、スプリング、速度の引き継ぎ、慣性、空間的な一貫性、タイポグラフィ、アクセシビリティ、Reduced Motionなどです。
特に重要なのが、アニメーションを固定された演出としてではなく、ユーザーの入力に継続して反応する「振る舞い」として設計する考え方です。
例えば、次のような問題をレビューする判断基準が含まれています。
- ボタンが押された瞬間に反応しているか
- ドラッグ中の要素が指やポインターへ1対1で追従しているか
- アニメーションの途中でも操作を反転できるか
- ドラッグ終了時の速度がアニメーションへ引き継がれているか
- 画面に入ってきた方向と消える方向が一致しているか
- 不要なバウンドや過剰なモーションを使用していないか
-
prefers-reduced-motionを考慮しているか
現在の apple-design ディレクトリには、単一の SKILL.md が格納されています。
Apple公式Skillではない
最初に明確にしておく必要があります。
apple-design はAppleが公開している公式Skillではありません。
Emil Kowalski氏がAppleのWWDCデザインセッションなどから設計原則を整理し、Webプラットフォーム向けに翻訳した第三者製のSkillです。
また、名前に apple-design とありますが、SwiftUIやUIKit専用ではありません。
Skill内の具体例は、主に以下の技術を対象としています。
CSS
Pointer Events
requestAnimationFrame
Motion
Framer Motion
Webのスプリングライブラリ
したがって、このSkillを使用したからといって、Apple Human Interface Guidelinesへの完全準拠や、SwiftUIの適切なAPI選択が保証されるわけではありません。
Web UIのレビューや実装では直接利用できます。SwiftUIやUIKitでは、モーションや操作感を評価するための設計知識として利用し、ネイティブ実装固有の知識は別のSkillやApple公式ドキュメントで補完するのが適切です。
CodexとClaude Codeの保存場所
現在の公式ドキュメントに基づく保存場所は、次のとおりです。
| 対象 | 全プロジェクト共通 | プロジェクト限定 | 明示的な呼び出し |
|---|---|---|---|
| Codex | $HOME/.agents/skills/ |
.agents/skills/ |
$apple-design |
| Claude Code | ~/.claude/skills/ |
.claude/skills/ |
/apple-design |
Codexについては、過去の記事や一部の外部ツールで ~/.codex/skills/ が使われている場合があります。
しかし、現行のCodex公式ドキュメントでは、ユーザー共通のSkill保存先として次のパスが案内されています。
$HOME/.agents/skills/
この記事では、各製品の公式ドキュメントに記載された保存場所を使用します。
Codex公式ドキュメント：
Build skills | OpenAI Developers
Claude Code公式ドキュメント：
Extend Claude with skills | Claude Code Docs
方法1：CodexとClaude Codeへまとめて導入する
全プロジェクトで利用できるようにする場合は、SkillのディレクトリをCodexとClaude Codeそれぞれの個人用ディレクトリへコピーします。
MacまたはLinuxのターミナルで、次のコマンドを実行します。
tmpdir="$(mktemp -d)"
git clone --depth 1 \
https://github.com/emilkowalski/skills.git \
"$tmpdir/emilkowalski-skills"
mkdir -p "$HOME/.agents/skills/apple-design"
mkdir -p "$HOME/.claude/skills/apple-design"
rsync -a \
"$tmpdir/emilkowalski-skills/skills/apple-design/" \
"$HOME/.agents/skills/apple-design/"
rsync -a \
"$tmpdir/emilkowalski-skills/skills/apple-design/" \
"$HOME/.claude/skills/apple-design/"
rm -rf "$tmpdir"
導入後は、次の構成になります。
~/.agents/
└── skills/
└── apple-design/
└── SKILL.md
~/.claude/
└── skills/
└── apple-design/
└── SKILL.md
ファイルが存在するか確認します。
test -f "$HOME/.agents/skills/apple-design/SKILL.md" \
&& echo "Codex: installed"
test -f "$HOME/.claude/skills/apple-design/SKILL.md" \
&& echo "Claude Code: installed"
次のように表示されれば、ファイルの配置は完了しています。
Codex: installed
Claude Code: installed
方法2：特定プロジェクトだけに導入する
チームで共有する場合や、特定のWebプロジェクトだけで利用する場合は、プロジェクト内へ導入します。
プロジェクトのルートディレクトリで、次のコマンドを実行します。
npx skills@latest add emilkowalski/skills \
--skill apple-design \
--agent codex \
--agent claude-code \
--copy \
--yes
--global を指定していないため、プロジェクト内へインストールされます。
想定される構成は次のとおりです。
your-project/
├── .agents/
│ └── skills/
│ └── apple-design/
│ └── SKILL.md
└── .claude/
└── skills/
└── apple-design/
└── SKILL.md
この方法では、CodexとClaude Codeの両方が同じプロジェクトで apple-design を使用できます。
skills CLIの詳細は、以下を参照してください。
対話形式でインストールする
インストール対象を画面で選択したい場合は、リポジトリが案内している次のコマンドを使用できます。
npx skills@latest add emilkowalski/skills
実行後、対象のSkillとして apple-design を選択します。
続いて、対象エージェントとしてCodexとClaude Codeを選択します。
CLIのバージョンによって質問内容や表示順が変更される可能性があります。インストール後は、必ず実際の保存場所を確認してください。
Skillが認識されない場合
Skillを追加した状態でCodexやClaude Codeをすでに起動していた場合、Skillが一覧へ反映されないことがあります。
Codexでは、Skillの変更は通常自動検出されます。ただし、表示されない場合はCodexを再起動します。
Claude Codeも既存のSkillディレクトリ内の変更を監視します。ただし、Claude Codeの起動後に ~/.claude/skills/ 自体を初めて作成した場合は、Claude Codeの再起動が必要です。
まず、Skillファイルが正しい場所に存在するか確認します。
ls -la "$HOME/.agents/skills/apple-design/"
ls -la "$HOME/.claude/skills/apple-design/"
次のファイルが存在している必要があります。
SKILL.md
Codexでの呼び出し方
Codexでは、Skill名の前に $ を付けて明示的に指定します。
$apple-design を使って、このWeb UIをレビューしてください。
より確実に作業条件を指定する場合は、次のように入力します。
$apple-design を明示的に使用してください。
このプロジェクトのWeb UIをレビューしてください。
特に以下を確認してください。
- 入力に対する反応速度
- ドラッグ操作への1対1の追従
- アニメーションの中断可能性
- 速度と慣性の引き継ぎ
- 空間的な一貫性
- Reduced Motionへの対応
この段階ではソースコードを変更せず、問題点を重要度順に提示してください。
Codex CLIやIDE拡張機能では、/skills から利用可能なSkillを確認できる場合もあります。
Claude Codeでの呼び出し方
Claude Codeでは、スラッシュコマンドとして呼び出します。
/apple-design
その後に日本語でタスクを指定します。
/apple-design
このWeb UIの操作感とアニメーションをレビューしてください。
変更はまだ行わず、問題点、影響、改善方針、対象ファイルを提示してください。
1回の入力としてまとめても構いません。
/apple-design このWeb UIのドラッグ操作とスプリングアニメーションをレビューし、優先順位付きの改善計画を作成してください。
日本語プロンプトでも使用できる
SKILL.md が英語で書かれていても、日本語のプロンプトで利用できます。
Skillの記述言語と、利用者が入力する言語を一致させる必要はありません。
例えば、Codexでは次のように使用できます。
$apple-design を使って、現在のモーダル表示をレビューしてください。
開く動作と閉じる動作の経路が一致しているか、
途中で操作を反転できるか、
不要なバウンドがないかを確認してください。
Claude Codeでは次のように使用できます。
/apple-design
このボトムシートを、指へ直接追従しているように感じられる実装へ改善してください。
ドラッグ終了時の速度をスプリングへ引き継ぎ、
アニメーション途中でも再度つかめるようにしてください。
自動適用に任せることもできますが、検証結果の再現性を高めるには、$apple-design または /apple-design を明示する方が確実です。
実務で使えるプロンプト
1. UIを変更せずに監査する
最初から実装させると、問題の整理とコード変更が同時に進み、修正範囲が必要以上に広がることがあります。
最初は監査だけを依頼します。
Codexの場合：
$apple-design を使用してください。
このリポジトリのUIとアニメーションを監査してください。
ソースコードは変更しないでください。
各問題について、以下を提示してください。
1. 重要度
2. 対象ファイルと該当箇所
3. 現在の問題
4. ユーザー体験への影響
5. apple-designのどの原則に反するか
6. 推奨する改善方法
最後に、優先順位付きの対応一覧を作成してください。
Claude Codeの場合は、先頭を次のように変更します。
/apple-design
2. 改善計画を作成する
$apple-design を使用してください。
監査結果を基に、実装可能な改善計画を作成してください。
各タスクには、対象ファイル、変更内容、使用するAPI、
完了条件、確認方法を含めてください。
タスク同士に依存関係がある場合は、実行順序も示してください。
まだコードは変更しないでください。
3. 1件ずつ実装する
$apple-design を使用してください。
改善計画のうち、最優先の1件だけを実装してください。
既存のデザインシステムとコンポーネント構成を維持してください。
変更後は、関連するテスト、lint、型チェックを実行してください。
実装完了後に、変更内容と確認結果を報告してください。
他の改善項目には着手しないでください。
一度にすべて変更させるより、監査、計画、実装、確認を分離した方が、差分をレビューしやすくなります。
4. ドラッグ操作を改善する
/apple-design
このドラッグ可能なカードの操作感を改善してください。
次の条件を満たしてください。
- ポインターへ1対1で追従する
- つかんだ位置のオフセットを維持する
- リリース時の速度を次のアニメーションへ引き継ぐ
- 移動先を現在位置だけでなく慣性から予測する
- アニメーション途中でも再度つかめる
- Reduced Motion設定を尊重する
最初に現在の実装を分析し、変更計画を提示してから実装してください。
5. Skill使用前後を比較する
Skillの効果を確認する場合は、同じコミットから2つの作業ブランチを作り、同じ依頼を実行します。
Skillを使用しない条件：
このボトムシートの操作感とアニメーションを改善してください。
Skillを使用する条件：
$apple-design を使用して、このボトムシートの操作感とアニメーションを改善してください。
次の観点で差分を比較します。
入力直後のフィードバック
ドラッグ中の追従性
アニメーションの中断可能性
リリース速度の引き継ぎ
不要なバウンドの有無
Reduced Motion対応
変更コードの複雑さ
単に生成された見た目を比較するのではなく、操作中の挙動とコード上の実装を確認することが重要です。
SwiftUIやUIKitで使う場合
このSkillの原則には、iOSアプリにも通用する内容があります。
例えば、次の考え方はSwiftUIやUIKitにも適用できます。
入力への即時反応
指への直接追従
中断可能なアニメーション
速度の引き継ぎ
スプリングによる連続的な動き
画面遷移の空間的一貫性
Reduced Motionへの配慮
ただし、Skill内の実装例はWeb向けです。
そのため、SwiftUIプロジェクトで使用する場合は、プロンプトにネイティブ実装であることを明記します。
$apple-design を設計原則として使用してください。
対象はWebではなく、SwiftUIで実装されたiOSアプリです。
Skill内のCSS、Pointer Events、Framer Motionのコードをそのまま使用せず、
同じ設計意図をSwiftUIのGesture、Transaction、Animation、
accessibilityReduceMotionなどへ置き換えてください。
Apple公式APIと現在のプロジェクトのDeployment Targetを優先してください。
Claude Codeでは、先頭を /apple-design に変更します。
また、Human Interface Guidelinesへの準拠を確認したい場合は、Apple公式ドキュメントも別途参照させる必要があります。
apple-design 単体を「Apple公式の正解」として扱わないことが重要です。
グローバル配置とプロジェクト配置の使い分け
個人で複数のプロジェクトに使用する場合は、グローバル配置が便利です。
Codex:
$HOME/.agents/skills/apple-design/
Claude Code:
$HOME/.claude/skills/apple-design/
一方、チームで同じSkillと同じバージョンを使用する場合は、プロジェクト内へ配置した方が再現性を確保できます。
.agents/skills/apple-design/
.claude/skills/apple-design/
プロジェクトへ含めることで、メンバーごとに異なるSkillを使用する状態を防げます。
ただし、第三者が公開しているSkillをリポジトリへコピーして再配布する場合は、元リポジトリのライセンス条件を確認してください。
emilkowalski/skills はMITライセンスで公開されています。必要な著作権表示やライセンス文を保持したうえで利用します。
外部Skillを導入するときの注意点
SkillはAIエージェントへ与える命令です。
Skillによっては、SKILL.md だけでなく、実行可能なスクリプト、外部ツール、MCP設定、参照ファイルが含まれる場合があります。
導入前に、少なくとも次の内容を確認します。
SKILL.mdの内容
scriptsディレクトリ
実行されるシェルコマンド
外部通信の有無
ファイルの削除や上書き
認証情報へのアクセス
ライセンス
今回の apple-design は、2026年7月21日時点では単一の SKILL.md で構成されています。
それでも、リポジトリの内容は将来変更される可能性があります。更新時にも差分を確認する方が安全です。
更新方法
skills CLIでインストールした場合は、次のコマンドで更新できます。
npx skills@latest update apple-design
グローバルにインストールしたSkillだけを更新する場合は、次のようにします。
npx skills@latest update -g apple-design
手動でコピーした場合は、最初に使用したcloneとrsyncの手順を再実行します。
独自に SKILL.md を編集している場合は、更新前にバックアップを取得し、上書きされる差分を確認してください。
アンインストール方法
手動でグローバル配置したSkillを削除する場合は、次のコマンドを実行します。
rm -rf "$HOME/.agents/skills/apple-design"
rm -rf "$HOME/.claude/skills/apple-design"
プロジェクト限定で配置した場合は、プロジェクトルートで次を削除します。
rm -rf ".agents/skills/apple-design"
rm -rf ".claude/skills/apple-design"
skills CLIでインストールした場合は、次のコマンドも利用できます。
npx skills@latest remove apple-design
まとめ
apple-design を導入すると、CodexとClaude CodeへAppleのインターフェース設計や流動的なモーションに関する判断基準を追加できます。
Codexでは次のように呼び出します。
$apple-design
Claude Codeでは次のように呼び出します。
/apple-design
日本語のプロンプトでも問題なく使用できます。
ただし、このSkillはApple公式ではなく、SwiftUIやUIKit専用でもありません。Web UIでは具体的な実装指針として利用でき、iOSアプリでは設計原則として利用するのが適切です。
実務では、いきなり実装を依頼するのではなく、次の順序に分けると扱いやすくなります。
監査
↓
改善計画
↓
1件ずつ実装
↓
動作確認
↓
Skill未使用時との比較
Skillの価値は、AIへ知識を追加することだけではありません。
複数のAIコーディングエージェントへ同じ判断基準を与え、設計レビューと実装の再現性を高められる点にあります。
参考資料
- emilkowalski/skills
- apple-design SKILL.md
- Build skills | OpenAI Developers
- Extend Claude with skills | Claude Code Docs
- Agent Skills Overview
- vercel-labs/skills
このシリーズの歩き方
Claude Code実務運用シリーズ ― 暴走させない、から仕組みにするまで。