moai-platform-chrome-extension

Chrome Extension Manifest V3 の開発

クイックリファレンス

Chrome Extension Manifest V3 開発スペシャリストは、最新の Chrome プラットフォーム API を使った最新のブラウザー拡張機能の構築を支援します。

自動トリガー：manifest_version 3 を含む manifest.json、サービスワーカーファイル、コンテンツスクリプトの宣言、chrome API の使用パターンから Chrome 拡張機能プロジェクトを検出します。

主な機能

Manifest V3 プラットフォーム：

• イベント駆動型アーキテクチャでは、永続的なバックグラウンドページの代わりにサービスワーカーを使用します
• セキュリティを強化するため、リモートコード実行を廃止しています
• ネットワークフィルタリングでは、ブロッキング方式の webRequest を declarativeNetRequest に置き換えます
• すべての chrome.* API メソッドが Promise ベースです
• action API により browserAction と pageAction が統一されたインターフェースになります
• Chrome 88 以降でサポートされています

プロセスアーキテクチャ：

• サービスワーカーは、アイドル状態になると終了する、単一のイベント駆動型バックグラウンドスクリプトとして動作します
• コンテンツスクリプトは、分離されたワールド内のウェブページコンテキストで実行されます
• ポップアップとサイドパネルは、専用の UI サーフェスを提供します
• オプションページは、拡張機能の設定インターフェースを提供します
• DevTools パネルは Chrome Developer Tools を拡張します

通信パターン：

• sendMessage を介して、サービスワーカーとコンテンツスクリプト間で一度限りのメッセージを送信します
• connect を介して、ポートベースの通信による長期間の接続を確立します
• externally_connectable 宣言を通じて、拡張機能間でメッセージを送信します
• 検証済みのオリジンに対して、ウェブページから拡張機能へメッセージを送信します

セキュリティモデル：

• コンテンツセキュリティポリシーにより、スクリプトのソースを self のみに制限します
• インラインスクリプトとリモートコード実行は許可されません
• 必要な API アクセス権限は、インストール時に宣言します
• オプションの権限を使うと、ユーザーの同意を得て実行時にアクセスを要求できます
• ホスト権限により、ウェブページへのアクセスパターンを制御します

Context7 ドキュメントへのアクセス

最新の Chrome Extension API ドキュメントを参照するには、Context7 MCP ツールを使用します。

ステップ 1 - ライブラリ ID を解決する：query "chrome extension" を指定して mcp__context7__resolve-library-id を使い、Context7 互換のライブラリ ID を取得します。

ステップ 2 - ドキュメントを取得する：解決したライブラリ ID とトピック、トークン割り当てを指定して、mcp__context7__get-library-docs を使います。

トピックの例：「manifest v3 configuration」、「service worker lifecycle」、「content scripts injection」、「message passing patterns」、「chrome.storage API」、「side panel API」、「declarativeNetRequest rules」。

---

モジュール一覧

このスキルでは段階的開示を採用しており、詳細な実装パターンを扱う専用モジュールを用意しています。

コアモジュール

manifest-v3-referenceでは、Manifest V3 拡張機能の manifest.json の全フィールドを解説します。必須フィールドと任意フィールド、フィールドの型と制約、権限の宣言、MV2 から MV3 への移行に関する注意事項、拡張機能の設定に関するベストプラクティスを扱います。

service-worker-patternsでは、サービスワーカーのライフサイクル、イベント登録、状態管理、デバッグを解説します。イベント駆動型アーキテクチャ、トップレベルでのリスナー登録、chrome.storageを使った状態の永続化、キープアライブ戦略、DOM にアクセスするためのオフスクリーンドキュメント、chrome://extensionsを使ったデバッグを扱います。

content-scripts-guideでは、コンテンツスクリプトの挿入方法、分離されたワールド、通信を解説します。マニフェストでの静的宣言、chrome.scriptingを使った動的登録、プログラムによる挿入、分離されたワールドのアーキテクチャ、DOM へのアクセス方法、セキュリティ上の考慮事項を扱います。

messaging-patternsでは、拡張機能のコンポーネント間のメッセージパッシングを解説します。sendMessageを使った一度限りのメッセージ、connectとポートを使った長時間接続、非同期応答のパターン、拡張機能間のメッセージング、ウェブページとのメッセージング、エラー処理戦略を扱います。

apis-quick-referenceでは、主要な chrome.* API のメソッドシグネチャと必要な権限を解説します。chrome.runtime、chrome.tabs、chrome.storage、chrome.action、chrome.scripting、chrome.alarms、chrome.notifications、chrome.contextMenus、chrome.sidePanel、chrome.declarativeNetRequest、chrome.offscreen、chrome.identity、chrome.commandsを扱います。

ui-componentsでは、ポップアップ、サイドパネル、オプションページ、DevTools パネル、コンテンツスクリプトの UI を解説します。ポップアップの HTML とライフサイクル、サイドパネルの設定と API、オプションページのパターン、DevTools 拡張機能との連携、コンテンツスクリプトから挿入する UI を扱います。

security-cspでは、コンテンツセキュリティポリシー、権限モデル、安全なコーディング手法を解説します。拡張機能ページの CSP 設定、最小権限の付与、入力値の検証、XSS の防止、安全なメッセージングパターン、HTTPS の強制を扱います。

publishing-guideでは、Chrome ウェブストアへの申請と配布を解説します。デベロッパーアカウントの設定、拡張機能のパッケージ化、プライバシーポリシーの要件、審査プロセス、更新の仕組み、セルフホスト可能な配布を扱います。

---

実装ガイド

Manifest V3 の構成

すべての Chrome 拡張機能では、プロジェクトのルートに manifest.json ファイルが必要です。必須フィールドは 3 つあります。manifest_versionには整数の3を設定し、nameには拡張機能の表示名を設定します。表示名は最大75文字です。versionには semver と互換性のある文字列を設定します。

descriptionフィールドには、Chrome ウェブストアに表示される概要を記述します。最大132文字です。iconsオブジェクトでは、さまざまな Chrome UI コンテキストで使用する、16、32、48、128ピクセルサイズの PNG アイコンを指定します。

バックグラウンド処理を行うには、backgroundオブジェクト内のservice_workerフィールドに、サービスワーカーファイルを指す単一の文字列パスを指定します。ES モジュールのインポートを使用する場合は、typeにmoduleを設定します。サービスワーカーのパスは単一の文字列で指定する必要があり、配列にはできません。

コンテンツスクリプトはオブジェクトの配列として宣言します。各オブジェクトでは、URL のマッチングパターンを指定するmatches、JavaScript ファイルの配列であるjs、任意のスタイルシート配列であるcss、そしてdocument_start、document_end、document_idleの値で挿入タイミングを制御するrun_atを指定します。

フィールドの詳細なリファレンスと移行ガイダンスについては、modules/manifest-v3-reference.mdを参照してください。

Service Worker アーキテクチャ

Manifest V3 のサービスワーカーは、永続的なバックグラウンドページをイベント駆動型モデルに置き換えます。サービスワーカーはイベントに応答するときだけ実行され、アイドル状態になると終了するため、メモリと CPU の消費を抑えられます。

すべてのイベントリスナーは、サービスワーカースクリプトのトップレベルで登録する必要があります。コールバック、Promise、または非同期関数内で登録したリスナーは、サービスワーカーの再起動後も維持されません。

サービスワーカーは DOM にアクセスできず、window オブジェクトも localStorage も使えないため、状態を永続化するには chrome.storage API を使用してください。スケジュールされたタスクには、サービスワーカーの終了後も維持される setTimeout や setInterval ではなく、Alarms API を使用してください。ネットワークリクエストには XMLHttpRequest ではなく fetch を使用してください。

DOM へのアクセスが必要な長時間実行処理には、Offscreen Documents API の chrome.offscreen.createDocument を使用して、DOM 機能を備えた非表示のドキュメントを作成してください。

サービスワーカーのパターンとデバッグ方法について詳しくは、modules/service-worker-patterns.md を参照してください。

Content Scripts

コンテンツスクリプトは、ウェブページのコンテキストで JavaScript と CSS を実行します。分離されたワールドで実行されるため、ホストページと DOM へのアクセスを共有しながら、JavaScript の実行環境は別々になり、変数や関数の競合を防ぎます。

インジェクション方法は 3 つあります。静的インジェクションでは、manifest の content_scripts 配列に URL のマッチパターンとともにスクリプトを宣言します。動的インジェクションでは、chrome.scripting.registerContentScripts を使用して実行時に登録します。プログラムによるインジェクションでは、chrome.scripting.executeScript を使用して必要に応じてスクリプトを挿入します。この方法には host_permissions または activeTab 権限が必要です。

コンテンツスクリプトから直接アクセスできる chrome API は限られており、dom、i18n、storage、および connect、sendMessage、onMessage、onConnect、getManifest、getURL、id などの特定の runtime メソッドのみです。それ以外の API 呼び出しは、すべてメッセージパッシングを介してサービスワーカーに送信する必要があります。

インジェクションのパターン、分離されたワールドの詳細、セキュリティ上の考慮事項については、modules/content-scripts-guide.md を参照してください。

メッセージパッシングのパターン

拡張機能は、Chrome のメッセージパッシングを使用してコンポーネント間で通信します。単発メッセージには chrome.runtime.sendMessage を使用してサービスワーカーに送信し、chrome.tabs.sendMessage を使用してコンテンツスクリプトに送信します。各メッセージに対して、コールバックまたは Promise を通じて 1 つの応答が返されます。

長時間の接続には、chrome.runtime.connect または chrome.tabs.connect を使用してポートを確立します。ポートは、どちらかの側が disconnect を呼び出す、リスナーが削除される、またはポートを含むタブがアンロードされるまで開いたままです。ポートを使うと、双方向の通信を継続できます。

単発メッセージで非同期応答を返すには、onMessage リスナーが true を返して非同期の sendResponse 呼び出しを示す必要があります。または、Chrome 144 以降では Promise を直接返します。

すべてのメッセージは JSON シリアライズされ、最大サイズは 64 MiB です。ホストページのコンテキストが侵害されている可能性があるため、コンテンツスクリプトからのメッセージ内容を決して信頼しないでください。

拡張機能間の通信やウェブページとの通信を含むメッセージングのパターンについて詳しくは、modules/messaging-patterns.md を参照してください。

Chrome API リファレンス

chrome.runtime API は、拡張機能のライフサイクル管理、メッセージング、マニフェストへのアクセスを提供します。インストール、更新、一時停止のイベントを処理し、拡張機能の URL やプラットフォーム情報を取得するメソッドを提供します。

chrome.tabs API は、タブの検索、作成、更新、削除のメソッドを使ってブラウザーのタブを管理します。chrome.storage API は、3 つのストレージ領域を提供します。容量が 10 MB の local、ログイン済みのデバイス間で同期される 100 KB の sync、ブラウザーの再起動時に消去されるメモリ内ストレージの session です。

chrome.action API は、バッジテキスト、アイコン、ポップアップ、クリックハンドラーなど、ツールバーのボタンを制御します。chrome.scripting API は、ウェブページへのスクリプトや CSS のプログラムによる挿入を提供します。

chrome.sidePanel API は、ウェブコンテンツの横に表示される常設の UI 領域である拡張機能のサイドパネルを管理します。chrome.declarativeNetRequest API は、webRequest をブロックせずに静的ルールと動的ルールを使ってネットワークリクエストをフィルタリングします。

API メソッドのシグネチャと権限要件の詳細については、modules/apis-quick-reference.md を参照してください。

UI コンポーネント

拡張機能は複数の UI サーフェスに対応しています。ポップアップはマニフェストの action.default_popup で設定し、ツールバーボタンをクリックすると標準的な HTML ページとして表示されます。ポップアップはフォーカスを失うと閉じるため、すばやく読み込めるようにしてください。

サイドパネルはマニフェストの side_panel.default_path で設定し、ウェブコンテンツの横に常設パネルを表示します。chrome.sidePanel API でパネルの動作を制御し、タブごと、または全体のパネルを有効にできます。

オプションページはマニフェストの options_ui.page で設定し、拡張機能の設定画面として chrome://extensions 内で開きます。DevTools パネルは、マニフェストの devtools_page フィールドを使って Chrome Developer Tools を拡張します。

コンテンツスクリプトは、DOM を操作してウェブページに UI 要素を直接挿入し、カスタム CSS を適用してスタイルを設定できます。

UI の実装パターンの詳細については、modules/ui-components.md を参照してください。

権限モデル

権限は 4 つのカテゴリに分かれます。標準権限では、storage、tabs、activeTab、contextMenus、notifications、scripting、alarms、sidePanel、declarativeNetRequest、identity、offscreen など、API へのアクセス要件を宣言します。これらの権限はインストール時に付与されます。

ホスト権限では、https://.example.com/ のようなパターンを使って、ウェブページにアクセスする URL パターンを指定します。オプション権限とオプションのホスト権限は、chrome.permissions.request を通じた実行時のリクエストを可能にし、インストール時に表示される権限の確認を減らします。

権限に関する警告を最小限に抑えるため、広範なホスト権限よりも activeTab を優先してください。拡張機能の機能に必要な最小限の権限のみをリクエストしてください。

権限戦略とセキュリティガイダンスの詳細については、modules/security-csp.md を参照してください。

セキュリティのベストプラクティス

Manifest V3 のコンテンツセキュリティポリシーでは、script-src は self と wasm-unsafe-eval のみに制限されています。インラインスクリプト、eval、リモートコードの読み込みは禁止されています。すべての JavaScript は拡張機能パッケージにバンドルする必要があります。

コンテンツスクリプトは分離されたワールドで実行されますが、ホストページが共有 DOM を操作できるため、侵害される可能性があるものとして扱ってください。サービスワーカーで、コンテンツスクリプトから受け取ったデータを必ず検証し、サニタイズしてください。信頼できないデータに eval、document.write、innerHTML を使用しないでください。すべての外部ネットワークリクエストには HTTPS を使用してください。

セキュリティパターンと CSP の設定について詳しくは、modules/security-csp.md を参照してください。

---

高度なパターン

高度なトピックの詳しい実装ガイダンスについては、modules ディレクトリを参照してください。

Manifest V3 への移行：

• MV2 のバックグラウンドページをサービスワーカーに変換する
• ブロッキング型 webRequest を declarativeNetRequest に置き換える
• リモートコードをバンドルされたモジュールに更新する
• chrome.storage のパターンに合わせて永続状態を適応させる

複雑なサービスワーカーのパターン：

• 周期的なタスク向けの複数アラームによるスケジューリング
• 長時間実行処理向けのサービスワーカーのキープアライブ
• 音声、キャンバス、DOM 解析向けのオフスクリーンドキュメント管理
• サービスワーカーとコンテンツスクリプト間での共有モジュールのインポート

高度なコンテンツスクリプトのパターン：

• ユーザー設定に基づく動的なスクリプト登録
• メインワールドと分離されたワールドの分離戦略
• カプセル化された UI コンポーネント向けの Shadow DOM 注入
• 動的なページコンテンツ向けの MutationObserver パターン

コンテキスト間の通信：

• 複数のコンテンツスクリプト間でのメッセージルーティング
• すべてのタブへのブロードキャストパターン
• 外部 Web サイトから拡張機能への通信
• chrome.runtime.connectNative を介したローカルアプリケーションとのネイティブメッセージング

ストレージの同期：

• デバイス間の設定に chrome.storage.sync を使用する
• 一時データに chrome.storage.session を使用する
• リアクティブな更新のためのストレージ変更リスナー
• クォータ管理と超過時の対処戦略

---

トラブルシューティング

よくある問題と解決策：

サービスワーカーが登録されない：

manifest.json の background.service_worker フィールドが配列ではなく、単一の文字列パスであることを確認してください。サービスワーカーファイルが指定されたパスに存在することを確認してください。chrome://extensions で拡張機能カードのエラーメッセージを確認してください。拡張機能の詳細ページにあるサービスワーカーのリンクをクリックして、サービスワーカーのコンソールを確認してください。

コンテンツスクリプトが注入されない：

manifest.json の matches パターンが目的の URL を正しく対象にしていることを確認してください。アクセスするページコンテンツに対して run_at のタイミングが適切であることを確認してください。拡張機能に必要なホスト権限があることを確認してください。対象ページのコンソールでコンテンツスクリプトのエラーを確認してください。

メッセージの受け渡しに失敗する：

送信側と受信側でチャネル名とメッセージ構造が一致していることを確認してください。メッセージ送信前に受信側のリスナーが登録されていることを確認してください。リスナーが戻る前に sendResponse が呼び出されることを確認するか、非同期応答の場合は true を返してください。chrome.tabs.sendMessage を使用する場合は、対象のタブが存在することを確認してください。

権限拒否エラー：

必要な権限がすべて manifest.json に宣言されていることを確認してください。プログラムによる注入では、host_permissions または activeTab 権限が付与されていることを確認してください。chrome://extensions で権限に関する警告や無効な状態がないか確認してください。chrome.permissions.contains を使用して、実行時の権限を確認してください。

拡張機能が Chrome ウェブストアに表示されない：

manifest.json がエラーなく検証に合格することを確認してください。アイコン、HTML ファイル、スクリプトなど、宣言されたすべてのリソースがパッケージ内に存在することを確認してください。説明が 132 文字を超えていないことを確認してください。デベロッパーダッシュボードで送信エラーを確認してください。

デバッグコマンド：

chrome://extensions を開いて、インストール済みの拡張機能とその状態を確認してください。デベロッパーモードを有効にすると、拡張機能の詳細とエラーログにアクセスできます。サービスワーカーのリンクをクリックすると、専用の DevTools コンソールが開きます。chrome://inspect を使用して、ページのコンテキスト内でコンテンツスクリプトをデバッグしてください。

---

相性の良い項目

• .claude/rules/moai/languages/typescript.md：拡張機能開発における TypeScript のパターン（paths frontmatter を介して自動読み込み）
• .claude/rules/moai/languages/javascript.md：JavaScript のパターンと ES モジュールの使用方法（paths frontmatter を介して自動読み込み）
• React またはフレームワークベースのポップアップとサイドパネル UI 向けの moai-domain-frontend
• サーバーサイド API 統合向けの moai-domain-backend
• 拡張機能のテスト戦略向けの moai-workflow-testing

---

リソース

モジュールリファレンス

詳細な実装パターンについては、modules ディレクトリを参照してください:

• modules/manifest-v3-reference.md は manifest.json の完全なフィールドリファレンスを扱っています
• modules/service-worker-patterns.md はサービスワーカーのライフサイクルとパターンを扱っています
• modules/content-scripts-guide.md はコンテンツスクリプトのインジェクションと通信を扱っています
• modules/messaging-patterns.md はすべてのメッセージパッシングパターンを扱っています
• modules/apis-quick-reference.md は chrome.* API のメソッドシグネチャを扱っています
• modules/ui-components.md はポップアップ、サイドパネル、オプション、DevTools UI を扱っています
• modules/security-csp.md は CSP、権限、セキュアコーディングを扱っています
• modules/publishing-guide.md は Chrome ウェブストアの公開ワークフローを扱っています

外部ドキュメント

最新のドキュメントについては、Context7 を使用して以下をクエリしてください:

• /nicedoc/chrome-extension-doc で Chrome Extension API を検索

公式の Chrome ドキュメントについては、WebFetch で以下を使用してください:

• https://developer.chrome.com/docs/extensions/develop で開発ガイドを参照
• https://developer.chrome.com/docs/extensions/reference/api で API リファレンスを参照

---

ステータス: 本番環境対応済み 生成ツール: MoAI-ADK Skill Factory v1.0 最終更新: 2026-02-01 バージョン: 1.0.0 (初回リリース) カバレッジ: Manifest V3、Service Workers、Content Scripts、Messaging、Chrome API、UI、セキュリティ、公開

よくある正当化

正当化	現実
「広範な権限をリクエストして、後で絞り込むつもりだ」	ユーザーはインストール時に権限を確認します。広範な権限はインストールを躊躇させ、Chrome ウェブストアの審査拒否を引き起こす可能性があります。
「コンテンツスクリプトはページ上のすべてにアクセスできるので、セキュリティはページ側の問題だ」	コンテンツスクリプトはユーザーのコンテキストで実行されます。コンテンツスクリプト経由で信頼できないコンテンツをインジェクトすることは、拡張機能における XSS の侵入経路です。
「Manifest V2 はまだ動くので、移行する必要はない」	Chrome ウェブストアは MV2 の投稿を受理しなくなりました。MV2 拡張機能は将来の Chrome リリースで無効化されます。
「サービスワーカーはバックグラウンドページと同じだ」	サービスワーカーはイベント駆動型で、アイドル時には終了します。永続的な状態にはグローバル変数ではなく chrome.storage を使用する必要があります。
「CSP は後で追加する。ただのセキュリティヘッダーだ」	manifest.json に CSP がないと、インラインスクリプトと eval() が許可され、これらは拡張機能の主な攻撃ベクターとなります。

レッドフラグ

• manifest.json が正当な理由なく <all_urls> または *://*/* のホスト権限を要求している
• コンテンツスクリプトが eval() や、信頼できないコンテンツに対する innerHTML を使用している
• サービスワーカーが状態をグローバル変数に保存している (終了時に失われます)
• manifest.json に content_security_policy がない
• 拡張機能がオリジン検証なしで外部サーバーと通信している

検証

• manifest.json の権限は最小限であり、それぞれがドキュメントで正当化されている
• Content Security Policy が manifest.json で定義されている (unsafe-eval なし、unsafe-inline なし)
• サービスワーカーが永続的な状態に chrome.storage を使用している (グローバル変数の状態がない)
• メッセージパッシングが処理前に送信元オリジンを検証している
• 拡張機能が開発者モードで Chrome 上でテストされている (テスト結果を提示)
• Manifest V3 準拠が検証されている (MV2 専用 API を使用していない)

テレメトリウィンドウ

ステータス: 不明確 (60 日間のウィンドウ) R4 監査判定: KEEP (監視) SPEC: SPEC-V3R2-WF-001 §6.2 (REQ-WF001-013) ウィンドウ開始: 2026-04-25 (Wave 1.5 コミット日) ウィンドウ終了: 2026-06-24 (60 日間) 再監査トリガー: このスキルの SessionStart フック発動回数 判定基準:

• ウィンドウ中の発動回数が 5 以上の場合 → 恒久的に保持
• ウィンドウ中の発動回数が 0 の場合 → v3.1 で RETIRE を予定
• 0 < 回数 < 5 の場合 → 「低使用」タグを付けて保持