apple-targets

Apple 拡張機能ターゲットのスキルリファレンス

このディレクトリには、サポート対象のすべての Apple 拡張機能およびターゲットの種類に関する包括的なスキルドキュメントが含まれています。各スキルドキュメントには、特定の Apple 拡張機能の種類を理解、実装、トラブルシューティングするために AI エージェントが必要とするすべての情報が記載されています。内容は次のとおりです。

• Apple のドキュメントへのリンクと WWDC セッションの参照
• ランタイムの動作とライフサイクルの説明
• 実際のユースケースと実装パターン
• 本番環境で使える Swift コードの例
• プラットフォームの対応状況とバージョン要件
• よくある落とし穴とデバッグのヒント

このスキルのインストール

npx skills を使って、このスキルをコーディングエージェント（Claude Code、Cursor、Codex など）にインストールします。

npx skills add EvanBacon/expo-apple-targets/tree/main/skills/apple-targets

CLI はインストール済みのエージェントを自動検出し、SKILL.md（およびこのディレクトリにある補足のリファレンスドキュメント）をエージェントのスキルディレクトリ（例：.claude/skills/ や .agents/skills/）にコピーします。インストールすると、Apple 拡張機能やターゲットの構築を依頼するたびに、エージェントがこのガイダンスを自動的に読み込みます。

これらのスキルの使い方

AI エージェント向け：

1. ユーザーが特定の拡張機能の種類について質問したとき（例：「ウィジェットを作るにはどうすればよいですか？」や「共有拡張機能を追加したい」）、対応するスキルドキュメントを読み、完全な実装ガイダンスを確認します。

2. 拡張機能が必要になる可能性のある機能を計画するとき（例：「ホーム画面に表示する」→ widget.md を読む）、要件と制約を理解するためにスキルドキュメントを参照します。

3. 拡張機能の問題をデバッグするときは、該当するスキルドキュメントの「落とし穴」セクションを参照します。ここには、Apple Developer Forums や実際の経験から得られた、よくある問題がまとめられています。

4. ユースケースに適した拡張機能の種類がわからないときは、関連するスキルの「ユースケース」セクションを確認し、最適な種類を探します。

各スキルドキュメントの構成：

すべてのスキルドキュメントは、_template.md で定義されているテンプレートに従っています。

• Frontmatter：タイトル、1 行の説明、最小 OS バージョン
• Apple のドキュメント：公式リファレンスへのリンク
• WWDC の履歴：機能の進化を示すセッションへのリンク
• 機能の概要：ランタイムの動作を段階的に説明
• ユースケース：業界やアプリの種類ごとに整理した実際のシナリオ
• 主要クラス：重要なフレームワークの型をまとめた表
• 実装：インラインコメント付きの、本番環境で使える Swift コード
• @bacons/apple-targets での使用：このプラグインのセットアップ手順
• プラットフォーム対応状況：OS バージョンの一覧
• 落とし穴：よくある間違い、メモリ制限、通知されずに失敗するケース

カテゴリ別のスキル

ユーザーインターフェイス拡張機能

スキル	拡張機能の種類	読むタイミング
widget.md	widget	ホーム画面ウィジェット、ロック画面ウィジェット、ライブアクティビティ、スタンバイモードの UI、またはコントロールセンターのコントロール（iOS 18 以降）が必要な場合に読みます。タイムラインベースの SwiftUI ビューです。
clip.md	clip	NFC、QR コード、App Clip コード、Safari バナー、またはメッセージのリンクから起動する、即時起動のミニアプリが必要な場合に読みます。拡張機能ではなく、サイズ制限のあるアプリケーションターゲットです。
share.md	share	他のアプリから URL、画像、テキスト、またはファイルを受け取るために、システムの共有シートにアプリを追加したい場合に読みます。
action.md	action	Safari、写真、またはファイルのコンテキストメニューに、コンテンツを変換し、必要に応じて変更後のデータを返すアクションを追加したい場合に読みます。
keyboard.md	keyboard	特殊な入力（絵文字ピッカー、GIF 検索、言語固有のレイアウト、計算機など）に対応するカスタムシステムキーボードが必要な場合に読みます。
photo-editing.md	photo-editing	写真アプリの編集 UI で、写真や動画にフィルター、調整、またはエフェクトを直接追加したい場合に読みます。
quicklook-preview.md	quicklook-preview	インタラクティブなコントロールや複数ページに対応する、カスタムファイル形式のリッチな Quick Look プレビューを作成したい場合に読みます。
quicklook-thumbnail.md	quicklook-thumbnail	Finder、ファイルアプリ、Spotlight に表示するカスタムファイル形式のサムネイル画像を生成したい場合に読みます。

通知

スキル	拡張機能の種類	読むタイミング
notification-service.md	notification-service	表示前に画像をダウンロードしたり、ペイロードを復号したり、プッシュ通知の内容を変更したりしたい場合に読みます。バックグラウンドで実行され、制限時間は 30 秒です。
notification-content.md	notification-content	インタラクティブなコントロールやリッチメディアに対応する、展開時のプッシュ通知用のカスタム SwiftUI/UIKit UI が必要な場合に読みます。

Siri とインテント

スキル	拡張機能の種類	読むタイミング
intent.md	intent	組み込みドメイン（メッセージ、決済、ワークアウト、メディア再生、配車予約）向けの Siri 音声コマンドが必要な場合に読みます。従来の SiriKit フレームワークを使用します。
intent-ui.md	intent-ui	インテントの確認時または処理時に、Siri インターフェイス内でカスタム UI を表示したい場合に読みます。intent 拡張機能と組み合わせて使用します。
app-intent.md	app-intent	ショートカット、Spotlight、Siri、集中モードフィルタ、コントロールセンターウィジェット向けに、最新の App Intents（iOS 16 以降）が必要な場合に読みます。カスタム .intentdefinition ファイルに代わるものです。

ネットワーキングと VPN

スキル	拡張機能の種類	読むタイミング
network-packet-tunnel.md	network-packet-tunnel	すべてのデバイストラフィックをカスタムプロトコル経由でトンネルする VPN クライアントを構築したい場合に読みます。従来型および最新のパーソナル VPN に対応します。
network-app-proxy.md	network-app-proxy	特定のアプリのトラフィックをカスタムプロキシ経由でルーティングする、アプリ単位のネットワークフィルタリング（アプリごとの VPN）が必要な場合に読みます。MDM または監視対象デバイスが必要です。
network-dns-proxy.md	network-dns-proxy	システム全体の DNS クエリを傍受して応答し、DNS フィルタリング、ログ記録、またはカスタム名前解決を実現したい場合に読みます。
network-filter-data.md	network-filter-data	コンテンツフィルタリング（保護者による制限、エンタープライズセキュリティ）のために、ディープパケットインスペクションを行いたい場合に読みます。Apple の特別な権限が必要です。

ファイル管理

スキル	拡張機能の種類	読むタイミング
file-provider.md	file-provider	オンデマンドダウンロード、検索、同期に対応したクラウドストレージまたはリモートファイルシステムを「ファイル」アプリで公開したい場合。
file-provider-ui.md	file-provider-ui	書類ピッカーでファイル操作（共有、権限設定）用のカスタム UI を提供したい場合。「File Provider」拡張機能と併用します。

コミュニケーションと電話

スキル	拡張機能の種類	読むタイミング
message-filter.md	message-filter	受信した SMS／MMS メッセージをフィルタリングし、迷惑メッセージ、取引、プロモーションを別々のタブに分類したい場合。
call-directory.md	call-directory	電話番号をブロックしたり、着信に発信者 ID ラベルを表示したりしたい場合。システムが管理する SQLite データベースを更新します。
unwanted-communication.md	unwanted-communication	ユーザーが迷惑電話、メッセージ、FaceTime の着信を報告サービスに報告するための UI を提供したい場合。特別なエンタイトルメントが必要です。

コンテンツとメディア

スキル	拡張機能の種類	読むタイミング
broadcast-upload.md	broadcast-upload	ReplayKit の画面録画をライブストリーミングサービス（Twitch、YouTube Live）に配信したい場合。動画／音声バッファーをリアルタイムで受信します。
broadcast-setup-ui.md	broadcast-setup-ui	ライブ配信を設定するためのカスタム UI（ストリームキー、プライバシー設定の選択など）を提供したい場合。「broadcast upload」拡張機能と併用します。
safari.md	safari	コンテンツスクリプト、バックグラウンドページ、コンテナアプリへのネイティブメッセージングに対応した Safari Web Extensions（Manifest V3）を作成したい場合。
content-blocker.md	content-blocker	JSON の宣言型ルールを使用して、Safari でルールベースの広告ブロック、トラッカーブロック、コンテンツ非表示を実現したい場合。JavaScript は実行されません。

教育とスクリーンタイム

スキル	拡張機能の種類	読むタイミング
classkit-context.md	classkit-context	ClassKit フレームワークを介して、教育アプリでの生徒の進捗状況を Apple の Schoolwork アプリに報告したい場合。
device-activity-monitor.md	device-activity-monitor	アプリ／Web サイトの利用状況を監視し、スクリーンタイムの制限に達したときにアクションを実行したい場合。ペアレンタルコントロールアプリや集中支援アプリ向けです。
shield-action.md	shield-action	ユーザーがスクリーンタイムのシールド（ブロックされたアプリ／Web サイト）を回避しようとしたときに、カスタム UI を表示したい場合。リクエストを処理または拒否します。
shield-config.md	shield-config	スクリーンタイムのルールによってアプリや Web サイトが制限されたときに表示する、カスタムシールド UI（ブロック画面）を作成したい場合。

認証とセキュリティ

スキル	拡張機能の種類	読むタイミング
authentication-services.md	authentication-services	Safari やアプリでパスワードとパスキーの自動入力に対応したい場合。credentials-provider に代わる最新の方法です。パスキーの作成／認証（WebAuthn）に対応しています。
credentials-provider.md	credentials-provider	旧式のパスワード自動入力（iOS 12 以降）に対応したい場合。新しいプロジェクトでは、パスワードとパスキーの両方に対応する authentication-services を使用してください。
smart-card.md	smart-card	CryptoTokenKit フレームワークを介して、スマートカードやハードウェアトークン（YubiKey、PIV カード）で認証したい場合。エンタープライズ向けです。
account-auth.md	account-auth	Kerberos やその他のエンタープライズ向けシングルサインオン（SSO）プロトコルの認証リクエストを変更したい場合。特別なエンタイトルメントが必要です。

位置情報とバックグラウンドサービス

スキル	拡張機能の種類	読むタイミング
location-push.md	location-push	高精度な位置情報を更新するためにアプリを起動する、サイレントプッシュ通知をユーザーが必要としている場合です。車両追跡、配達アプリ、位置情報に基づくアラートに使用します。
bg-download.md	bg-download	オンデマンドリソースや大容量アセットのダウンロードを、システムのバックグラウンドアセットダウンローダーで管理したい場合です。ゲームやメディアアプリに使用します。

スマートホームとMatter

スキル	拡張機能の種類	読むタイミング
matter.md	matter	Homeアプリを介したデバイスのコミッショニングに対応するため、Matterスマートホームデバイスのサポートを追加したい場合です。MFiへの登録とMatter認証が必要です。

印刷

スキル	拡張機能の種類	読むタイミング
print-service.md	print-service	AirPrintを使わずにネットワークプリンターを検出して印刷したい場合、または特殊なプリンター向けにカスタムの印刷レンダリングを提供したい場合です。

検索とインデックス作成

スキル	拡張機能の種類	読むタイミング
spotlight.md	spotlight	アプリのコンテンツをSpotlightにインデックス登録し、詳細な検索結果を提供して、Spotlight検索からのタップに対応したい場合です。Core SpotlightとNSUserActivityを使用します。
spotlight-delegate.md	spotlight-delegate	システム管理のスケジュールで定期的に実行される、大規模なSpotlightインデックス作成用のバックグラウンド拡張機能が必要な場合です。macOSのみ（iOSでは使用できません）。

コラボレーションと会議

スキル	拡張機能の種類	読むタイミング
virtual-conference.md	virtual-conference	ビデオ会議アプリをシステムの通話UIおよびCallKitと統合し、Handoff、ピクチャ・イン・ピクチャ、システムの通話コントロールを利用できるようにしたい場合です。

Apple Watch

スキル	拡張機能の種類	読むタイミング
watch.md	watch	コンプリケーション、ワークアウトセッション、HealthKitとの統合、iPhoneとの同期に使うWatch Connectivityを備えた、単独で動作するwatchOSアプリが必要な場合です。これは拡張機能ではなく、完全なアプリケーションターゲットです。

ターゲットの種類と拡張機能の違い

アプリケーションターゲット（拡張機能ではありません）：

• App Clip（clip） — プロダクトタイプcom.apple.product-type.application.on-demand-install-capableを使用します
• watchOSアプリ（watch） — プロダクトタイプcom.apple.product-type.applicationを使用します

これらは、独自のInfo.plist、アプリアイコン、ライフサイクルを持つ完全なアプリケーションです。NSExtensionPointIdentifierは使用しません。

これ以外のすべての種類はアプリ拡張機能であり、プロダクトタイプcom.apple.product-type.app-extensionを使用し、Info.plistで拡張ポイント識別子を宣言します。

よくあるユースケースのクイックリファレンス

ユーザーの依頼...	参照するスキル
「ホーム画面ウィジェットを追加する」	widget.md
「共有エクステンションを追加する」	share.md
「インスタントアプリ／App Clipを構築する」	clip.md
「Siriと連携する」	intent.md または app-intent.md
「プッシュ通知を変更する」	notification-service.md
「通知のカスタムUI」	notification-content.md
「VPNアプリを構築する」	network-packet-tunnel.md
「パスワードマネージャーの自動入力」	authentication-services.md
「迷惑電話をブロックする」	call-directory.md
「SMSの迷惑メッセージをフィルタリングする」	message-filter.md
「ファイルアプリに追加する」	file-provider.md
「カスタムキーボード」	keyboard.md
「写真フィルターエクステンション」	photo-editing.md
「Safariの広告ブロッカー」	content-blocker.md
「Safariエクステンション」	safari.md
「ライブ配信／画面収録」	broadcast-upload.md
「watchOSアプリ」	watch.md
「スクリーンタイムのペアレンタルコントロール」	device-activity-monitor.md
「スマートホーム／Matter」	matter.md
「ネットワークプリンターに印刷する」	print-service.md
「Spotlight検索と連携する」	spotlight.md

@bacons/apple-targets を使った新しいエクステンションの作成

各スキルドキュメントには、3ステップのセットアップを説明する「@bacons/apple-targets での使用」セクションがあります。

# 1. Run the CLI to scaffold the extension
bunx create-target <type>

# 2. Ensure the plugin is in app.json
{
  "expo": {
    "plugins": [["@bacons/apple-targets"]]
  }
}

# 3. Generate the native project
npx expo prebuild --clean

<type> パラメーターは、各スキルドキュメントのタイトルに表示されるエクステンションタイプのスラッグ（例：widget、share、clip、notification-service）に対応します。

Prebuild を実行するタイミング

ターゲットのソースファイルは /ios ディレクトリの外にあり、Xcodeプロジェクトにコピーされるのではなくリンクされるため、Swiftコードの変更は自動的に同期されます。コードを編集する際に、prebuildを再実行する必要はありません。

• prebuild --clean を実行する場合：

  • 新しいターゲットを作成した後の初期セットアップ
  • expo-target.config.js（アイコン、色、エンタイトルメント、バンドルID、フレームワーク）を変更するとき
  • app.json のプラグイン設定を変更するとき
  • ターゲットを追加または削除するとき
  • Xcodeプロジェクトの破損や原因不明のビルド失敗が発生したとき

• prebuild（--clean なし）を実行する場合：

  • 手動で加えたXcodeの変更を保持したままプロジェクトを再生成する必要があるとき
  • プラグインのバージョンを更新し、プロジェクトに軽微な変更を加えるとき

• prebuildが不要な場合：

  • targets/<name>/ ディレクトリ内のSwiftコードを編集するとき — ファイルはリンクされているため、変更はすぐにXcodeに反映されます
  • 既存のターゲット内にSwiftファイルを追加または変更するとき
  • ターゲット実装に関するほとんどの日常的な開発作業

このアーキテクチャにより、Xcodeプロジェクト全体を何度も再生成することなくエクステンションのコードを反復的に開発でき、開発を高速化し、手動で加えたプロジェクトのカスタマイズを保持できます。

エンタイトルメントとケイパビリティのガイド

entitlements/ ディレクトリには、複数のエクステンションタイプに適用されるiOSのエンタイトルメントとケイパビリティに関するガイドがあります。

ガイド	参照するタイミング
entitlements/app-groups.md	メインアプリとエクステンション（ウィジェット、共有、通知、App Clip）の間でデータを共有する必要がある場合。命名規則、UserDefaultsスイート、共有コンテナ、Keychainアクセスグループ、自動EASプロビジョニングについて説明しています。

エンタイトルメントのガイドで回答しているよくある質問：

• 「アプリとウィジェットの間でデータを共有するには？」→ app-groups.md を参照
• 「エクステンションからメインアプリのUserDefaultsにアクセスできない」→ app-groups.md を参照
• 「EASではApp Groupsのコード署名をどのように処理するのか？」→ app-groups.md を参照

新しいスキルのテンプレート

新しいスキルのドキュメントを作成する場合は、_template.md を出発点として使用してください。必須のフロントマター、セクション構成、コード例の形式、品質チェックリストが定義されています。

追加リソース

• CLAUDE.md（プロジェクトのルート）：@bacons/apple-targets プラグイン自体の開発環境のセットアップ、ビルド手順、アーキテクチャに関するメモ
• Apple Developer Documentation：各スキルから、Apple の公式ドキュメントや WWDC セッションにリンクしています
• Expo Documentation：https://docs.expo.dev/config-plugins/introduction/
• Continuous Native Generation：https://docs.expo.dev/workflow/continuous-native-generation/