cordova-plugin-migrator

Cordova プラグインマイグレーター

Cordova プラグインのソースツリーを受け取り、単一のスキル呼び出しで Capacitor プラグインの候補と統合された MIGRATION.md を生成する、エンドツーエンドのオーケストレーターです。内部では Cordova プラグインを分析し、capacitor-plugin-generator/references/input-contract.md に準拠する構造化 YAML プランを出力して、ユーザーの確認を挟んだ後、そのプランを使って capacitor-plugin-generator スキルを構造化モードで呼び出します。このスキルはジェネレーターがすでに行う処理を再実装しません。スキャフォールディングとネイティブコードの生成はジェネレーターが担います。

このスキルを使用する場面

✅ 次の場合にこのスキルを使用してください：

• 既存の Cordova プラグインを Capacitor に移行する場合。
• 移行に着手する前に、複雑さ、工数、障害要因を評価する場合。
• capacitor-plugin-generator に渡す構造化ハンドオフ YAML を作成する場合。
• 公式の Cordova API と、既存または計画中の Capacitor API を比較する場合。
• Cordova プラグインのフック、ネイティブ依存関係、または移植性に関わる <config-file> の変更を監査する場合。

❌ 次の場合はこのスキルを使用しないでください：

• Capacitor プラグインのスキャフォールドや実装を生成する場合。プランを capacitor-plugin-generator に渡してください。
• Cordova のソースがない状態で、新しいプラグインを設計する場合。
• Cordova アプリ全体を移行する場合。対象範囲はプラグイン単位のみです。
• すでに移行済みのプラグインで発生している実行時の問題をデバッグする場合。
• 生成された Capacitor プラグインを公開またはリリースする場合。

前提条件

要件	用途
Cordova プラグインのソース（ローカルクローンまたはアクセス可能なリポジトリ）	plugin.xml、ネイティブソース、JS ブリッジを読み取ります。
Node.js LTS と npm	依存関係を調査し、フックから参照されるスクリプトを実行します。
capacitor-plugin-generator スキル	このスキルが生成する YAML プランを受け取ります。
capacitor-plugin-generator/references/input-contract.md	ハンドオフ YAML の正式な構造を定義します。
公式の Capacitor 相当プラグインへの読み取りアクセス（存在する場合）	Capacitor にすでに存在するプラグインを移植する際に、ワイヤーフォーマットの名前と型を再利用します。
Xcode と Android Studio（任意）	検出されたネイティブ依存関係に必要な SDK が利用可能か確認します。

エージェントの動作

• オーケストレーターとして実行します。フェーズ 1～10 は Cordova ソースを分析し、 YAML プランを生成します。フェーズ 11 は Skill ツール経由で capacitor-plugin-generator を呼び出し、プランを構造化モードで渡します。フェーズ 12 は ドキュメントを統合します。このスキルからネイティブの Capacitor コードを出力しないでください。 生成器がそれを担います。
• YAML を生成する前に capacitor-plugin-generator/references/input-contract.md を読んでください。生成器の コントラクトが正式な情報源です。フィールドを勝手に作ったり、既存のものを 改名したりしないでください。
• まず plugin.xml からプラグインのアイデンティティを解決してください。id、name、version、 宣言されたプラットフォーム、宣言されたフレームワーク、フック、config-file ターゲットです。
• プラットフォームサポートを断言する前に、すべてのネイティブ依存関係の宣言を 検査してください。README の主張ではなく、plugin.xml が実際に述べていることを 反映してください。
• 各 <hook> を、references/hooks-migration.md のルールを使って Tier 1（Capacitor フック）、Tier 2（npm スクリプト／手動手順）、Tier 3（ブロッカー）に分類してください。Tier 3 のフックが 1 つあるだけで 生成器への引き渡しをブロックするのに十分です。
• 公式の Capacitor 相当物（@capacitor/<name> または Capawesome／コミュニティによる移植版）が存在する場合は、その definitions.ts とネイティブソースを読んでください。 そのワイヤーフォーマット文字列、enum 値、メソッド名、イベント名を そのまま再利用してください。「似ている」並行 API を勝手に作らないでください。
• ハイブリッドプラグインを検出してください。package.json がすでに scripts.capacitor:* フックを宣言している場合、そのプラグインは部分的に Capacitor 対応です。既存のフックを Tier 1 の「すでに変換済み」として記録し、再利用するか、書き直すか、 マージするかをユーザーに尋ねてください。黙って捨てないでください。
• Cordova 側の引数が文字列化された JSON ブロブである JS メソッド （ネイティブハンドラーにおける JSON.parse / Gson.fromJson / JSONObject(args.getString(0))）は、api.types の強く型付けされた TypeScript インターフェースに マッピングする必要があり、string パラメーターにしてはいけません。インターフェースの形は ネイティブのパース箇所から取得してください。
• Cordova ネイティブソースが実行時パーミッション API （cordova.requestPermission、requestPermissions(...)、 AVCaptureDevice.requestAccess、PHPhotoLibrary.requestAuthorization、 CLLocationManager デリゲート、CNContactStore.requestAccess など）を使用している場合は、 Cordova JS サーフェスがそれらを公開していなかったとしても、YAML に checkPermissions() メソッドと requestPermissions() メソッドを追加してください。Capacitor の 慣習は明示的なパーミッションメソッドであり、公式の相当物 （もしあれば）はほぼ常にそれらを公開しています。
• Cordova ネイティブソースがヘルパークラス （ExifHelper、MimeTypeHelper、ImageMetadata など）でメタデータを抽出し、それを レスポンスペイロードに含めている場合は、Cordova JS ドキュメントがそれらを 記述していなかったとしても、対応する api.types インターフェースにそれらのフィールドを取得してください。README ではなく、ネイティブコードを 読んでください。
• 公式の Capacitor 相当物を反映する場合は、公式のネイティブ LOC と Cordova ソースのネイティブ LOC を健全性チェックしてください。公式が 3 倍を超えて 大きい場合は、migration.notes エントリを追加して、そのまま移植すると公式が 処理している挙動（例：時間精度の振動のための iOS CHHapticEngine、 インパクト／通知のための Android VibrationEffect パターン）が 置き去りになることをレビュアーに警告してください。生成器の SDK アダプタールールが これを捕捉するかどうかはわかりません。
• セットアップノートを出力する際は、下流の 3 つの送り先を区別してください。
  1. プラグイン自身のパッケージング。 Gradle の implementation '...' 行、 CocoaPods の s.dependency '...' 行、カスタム Maven リポジトリ URL、 s.weak_framework、s.vendored_frameworks、AndroidManifest の <uses-permission> / <meta-data> / <queries> エントリ、および @CapacitorPlugin(permissions = [...]) 宣言はすべて、プラグイン自身の android/build.gradle、.podspec、 android/src/main/AndroidManifest.xml、またはアノテーションに属します。Gradle の マニフェストマージャーと CocoaPods はこれらを推移的にコンシューマーへ伝播するため、 ホストアプリの手順も MIGRATION.md のエントリも 不要です。
  2. ホストアプリのビルド構成。 プラグインパッケージに置けず、 コンシューマーアプリに適用しなければならない項目：Info.plist プライバシー文字列（NSCameraUsageDescription、 NSLocationWhenInUseUsageDescription など）、iOS のケイパビリティと エンタイトルメント（Apple Pay マーチャント ID、aps-environment、 com.apple.security.application-groups）、およびプラグインではなくホストアプリに 置く必要があるその他すべてのマニフェスト変更。 migration.notes に記録し、プラットフォームごとにコピー＆ペースト可能な スニペットとともに MIGRATION.md に文書化してください。
  3. コンシューマーの実行時構成／コード。 Apple Developer 側の資格情報 プロビジョニング、ホストアプリが提供する JSON 構成値（マーチャント 番号、API キー）、およびコンシューマーの JS 呼び出し箇所の移行（コールバック → Promise、位置指定 → 名前指定）。入力がコンシューマー自身のデータであるため、 これを自動化できるツールはありません。 migration.notes 内で、各 plugin.xml ディレクティブをこれら3つの分類のいずれかに記録します。 プラグインに同梱すべき依存関係について、利用者に implementation '...' の追加を求める手順を MIGRATION.md に絶対に記載しないでください。依存関係ごとの表については、 references/dependency-migration.md の「Ownership Model」を参照してください。
• Cordova プラグインが <preference name="VAR" default="..."> を使用し、それが <config-file target="*-Info.plist"> エントリー内のインストール時プレースホルダー（Apple Pay の加盟店設定、OAuth クライアント ID、アナリティクスキーなど）に使われている場合は、これを検出し、migration.warnings でランタイム設定 JSON ファイルのパターンを推奨してください。これは、ハイブリッドの capacitor:sync:after スクリプトで読み込まれる PluginConfig.json で、ビルド時にファイルをネイティブプロジェクトへコピーします。Cordova プラグインにこのスクリプトがすでに含まれている場合（hooks/capacitor*.js を確認してください）は、それを再利用します。含まれていない場合は、1 画面分のテンプレートを提案します。このパターンにより、コンシューマーの値を静的な plist／manifest エントリーに一切含めずに済みます。
• plugin.xml 内の SPM マーカーを検出してください。<platform name="ios" package="swift"> と <pod ... nospm="true"> は、Cordova プラグインに対応する Package.swift がすでに含まれていることを示します。見つかった場合は、次のようにします。（a）その Package.swift を読み込み、依存関係を YAML の dependencies.ios.spm に移します。（b）nospm="true" を含まないすべての pod を dependencies.ios.cocoapods に移します。（c）生成される Capacitor プラグインに Package.swift と .podspec の両方を含める必要がある旨を migration.notes に追加します（Capacitor 8 は両方をサポートしており、新しいプラグインでは SPM がデフォルトです）。スキーマについては、references/dependency-migration.md の「Swift Package Manager (SPM)」を参照してください。
• デフォルトの出力モードは Mode B（サイドバイサイドのディレクトリ）です。ユーザーが明示的に依頼し、ソースが書き込み可能な作業コピーにある場合に限り、Mode A（.cordova-archive/ を使ったインプレース）に切り替えてください。
• ブロッカー、Tier 3 フック、解決できないプロプライエタリー SDK、またはソースファイルの不足により推測が必要になる場合は、処理を停止してユーザーに入力を求めてください。問題を隠した YAML 計画を出力してはいけません。
• 解決可能な警告（手動での手順を文書化すればよいもの）とブロッカー（自動移行できないもの）を区別してください。どちらも計画に含めますが、引き継ぎを停止するのはブロッカーのみです。
• Cordova プラグインのツリーにチェックインされているベンダー提供のバイナリ（例：src/ios/frameworks/Foo.xcframework）は、それだけでブロッカーにはなりません。そのバイナリを引き継ぎ、パスを migration.source_files.ios（または .android）に記録してください。バイナリにユーザーが持っていないランタイム認証情報が必要な場合、または AndroidX／64 ビット／シミュレーター要件を満たさない場合に限り、ブロッカーとして扱います。
• 実際に確認した内容を報告してください。ブロッカーや未対応のパターンを指摘する際は、ファイルパスと行番号を記載してください。
• Phase 9 を宣言する前に、iOS と Android の調査結果を相互に比較してください。一方のプラットフォームにはあるメソッドが、もう一方にはない場合、その不一致を migration.warnings に示し、ジェネレーターが方針（両方に反映する、条件付きで公開する、または削除する）を選べるようにしてください。片方のプラットフォームでしか実現できないコントラクトを、黙って出力してはいけません。
• デフォルトの応答形式は、コードではなくアーキテクチャと計画です。ユーザーが明示的に「コードを見せて」または「詳細に説明して」と依頼しない限り、移行前後のコードブロック全体を含めないでください。migration.cordova_to_capacitor_map のメソッドごとの 1 行のマッピングは、この意味での「コード」には該当せず、計画の一部です。
• migration.cordova_to_capacitor_map のすべての値と、JS 構文（(、)、{、}、:、[、]）を含むその他の YAML 文字列は、すべて引用符で囲んでください。Foo.bar({ x: 1 }) のような引用符で囲まれていない JS 式は YAML として解析できず、読み込み時にジェネレーターに拒否されます。
• ジェネレーターを呼び出すのは、Phase 10 のユーザーチェックポイントで承認された後に限ります。ユーザーが拒否した場合、中止した場合、またはブロッカーが未解決の場合は、処理を停止してください。migration.blockers が空でない、または migration.hooks.tier_3 が空でない YAML で、ジェネレーターを呼び出してはいけません。
• odc_target: true の場合、Phase 11 は 2 つの連続したサブフェーズ（11a と 11b）に分かれます。Phase 11a では build-actions-generator を呼び出し、Phase 11b では capacitor-plugin-generator を呼び出します。全体の手順については、references/using-plugin-generator.md の「ODC Path」を参照してください。ビルドアクションは Capacitor プラグインのフォルダーに書き込まれます。ビルドアクションで完全に対応できるフックと移行メモは、ジェネレーターに渡す YAML（Phase 11b）から除外してください。これにより、ビルドアクションがすでに処理している設定レベルの作業に対し、ジェネレーターが重複した Capacitor フックスクリプトを生成するのを防ぎます。

手順

フェーズ 1：タスクと出力モードの決定

ユーザーが移行対象の Cordova プラグインを持っていることを確認します。変換元となる Cordova ソースがなく、ゼロから新しい Capacitor プラグインを作りたい場合は、ここで中止し、capacitor-plugin-generator に直接案内します。このスキルで追加できることはありません。

それ以外の場合は、出力モードを選択します。

• モード B（デフォルト、並列配置）：ジェネレーターは、Cordova リポジトリの隣接ディレクトリに新しい Capacitor プラグインを生成します。Cordova リポジトリには一切手を加えません。
• モード A（オプトイン、同じ場所に配置）：ジェネレーターは一時ディレクトリに生成します。フェーズ 11 が成功した後、フェーズ 12 でジェネレーターの出力を Cordova リポジトリのルートに移し、元の Cordova ソースを .cordova-archive/ の下に移動します。元のリポジトリの npm パッケージ名と git 履歴は保持されます。明示的なユーザーのオプトインと、クリーンで書き込み可能な git 作業コピーが必要です。

ディレクトリ構成、事前チェック、正確な移動手順については、references/output-modes.md を参照してください。

ODC の確認： リクエスト内のどこかでユーザーが ODC または OutSystems Developer Cloud に言及しているか確認します。言及している場合は、odc_target: true に設定して先へ進みます。言及していない場合は、次のように尋ねます。「この Capacitor プラグインは ODC（OutSystems Developer Cloud）アプリで使用されますか？使用される場合は、MABS でネイティブ設定を処理するビルドアクションを Capacitor プラグインと併せて生成します。」 回答を、フェーズ 11 で使用する odc_target: true/false として記録します。

フェーズ 2：plugin.xml の読み込み

一般的な Cordova プラグインの構成：

my-plugin/
├── plugin.xml           # Plugin manifest and configuration
├── package.json         # NPM metadata (and any capacitor:* scripts)
├── www/                 # JavaScript bridge
├── src/
│   ├── ios/             # CDVPlugin subclasses (.h/.m/.swift)
│   └── android/         # CordovaPlugin subclasses (.java/.kt)
└── hooks/               # Optional lifecycle scripts

plugin.xml を開きます。プラグイン ID、名前、バージョン、宣言されているプラットフォーム（<platform name="...">）、<source-file>／<header-file> のマッピング、<framework> エントリー、<podspec> ブロック、<config-file> の対象、<edit-config> の対象、<hook> 宣言、<dependency> エントリー、<preference> タグ、<js-module> の公開設定（clobbers／merges／runs）を抽出します。ブロッカー候補ごとに、ファイルパスと行番号を記録します。

フェーズ 3：ネイティブ依存関係の分析

references/dependency-migration.md を適用します。各 <framework> と <podspec> の Pod について、直接移行、バージョン更新、代替ライブラリ、ブロッカーのいずれかを判断します。Android の各 Gradle 座標について、AndroidX と Support Library のどちらを使用しているか、および Capacitor の最小コンパイル SDK を確認します。移行後に必要な手動インストール手順を記録します。

フェーズ 4：フックの分析

references/hooks-migration.md の 3 段階ルールを適用します。

• Tier 1：Capacitor プラグインの npm フックに変換できます （capacitor:{sync,copy,update}:{before,after}、 capacitor:{android,ios}:add:{before,after}）。
• Tier 2：npm ライフサイクルスクリプト（postinstall、 preuninstall）または文書化された手動手順に変換できます。
• Tier 3：対話型プロンプト、plugin.xml／config.xml の変更、Cordova CLI 内部の処理、または Capacitor に相当する機能がないその他の処理です。

参照されている各スクリプトを読みます。ファイル名だけで分類しないでください。

フェーズ 5：JavaScript ブリッジの分析

references/api-mappings.md を適用します。www/*.js から、すべての公開メソッド、位置引数の形式、成功／エラーコールバックを使用するかプロミスを返すか、exec() が cordova.exec() のアクション名と対応しているかを一覧にします。各メソッドを Capacitor の methodName(options): Promise<R> シグネチャに対応付けます。

フェーズ 6：iOS 実装の分析

references/api-mappings.md を適用します。src/ios/*.{h,m,swift} から、CDVPlugin サブクラス、JS アクションに対応する各メソッド、command.arguments からの引数抽出、応答の構築（CDVPluginResult）、権限処理フロー、使用されているシステムフレームワークや SDK アダプターを特定します。Objective-C を Swift に最新化する必要がある箇所を記録します。

フェーズ 7：Android 実装の分析

references/api-mappings.md を適用します。src/android/**/*.{java,kt} から、CordovaPlugin サブクラス、execute() ルーター、アクション文字列、引数抽出（args.getString(i)）、応答経路（CallbackContext.success/error）、権限処理フロー、Activity Result のパターンを特定します。Java を Kotlin に最新化する必要がある箇所を記録します。

フェーズ 8: 複雑さの評価

references/complexity-assessment.md を適用します。メソッド数、LOC、依存関係のフットプリント、フックのティア構成、言語のモダナイゼーション、ブロッカー数、Capacitor 相当の再利用性についてプラグインをスコアリングします。simple、moderate、complex、blocked のいずれかを出力します。blocked は、ジェネレーターへの引き渡し前にユーザーが問題を解決する必要があることを意味します。

フェーズ 9: 移行 YAML の生成

references/using-plugin-generator.md を適用します。ジェネレーターの references/input-contract.md に基づいて YAML を構築します。ベースブロック（plugin、platforms、api、permissions、dependencies）に加えて、オプションの migration: ブロック（source、complexity、output_mode、blockers、warnings、language_modernization、source_files、hooks、cordova_to_capacitor_map）を含めます。公式の Capacitor 相当が存在する場合は、ワイヤーフォーマットの文字列をそれに固定します。

フェーズ 10: ユーザーチェックポイント

YAML とあわせて簡潔な人向けサマリーを提示します。複雑さ、ブロッカー、警告、手動セットアップ、推奨出力モード、およびミラーリングされる Capacitor 相当が含まれます。ブロッカーまたは Tier 3 フックが空でない場合は、停止して確認を待ちます。

フェーズ 11: 下流スキルの呼び出し

下流の呼び出しパスは、フェーズ 1 で ODC が確認されたかどうかによって異なります。

非 ODC パス: references/using-plugin-generator.md を適用します。フェーズ 9 の YAML を使用して、Skill ツール経由で構造化モードで capacitor-plugin-generator を呼び出します。ジェネレーターは独自のプレイブックを実行します。このスキルは Cordova ソースを再検査しません。Complex プラグインの場合はインクリメンタルモード（ユーザーチェックポイントを挟みながら一度に 1 つのプラットフォーム）を使用します。ジェネレーターが YAML を拒否した場合は、フェーズ 9 に戻って修正します — ジェネレーターの出力を決して手で編集しないでください。

ODC パス: references/using-plugin-generator.md の「ODC Path」にある 2 つのサブフェーズのシーケンスに従います。

• フェーズ 11a — フェーズ 9 の YAML と Cordova プラグインパスを指定して build-actions-generator を呼び出し、build-actions/ の出力を待ちます。どのフック/要素をカバーしたかに注記します。
• フェーズ 11b — migration.hooks.tier_1 から build-action でカバーされた項目を削除します（または status: handled_by_build_actions とマークします）。これを記録する migration.notes エントリを追加します。次に、注釈付きの YAML を指定して capacitor-plugin-generator を呼び出します（複雑さに応じて標準またはインクリメンタル）。

フェーズ 12: 移行後のクリーンアップ

references/post-migration-cleanup.md を適用します。ジェネレーターが動作するスキャフォールドを生成した後、中間メモをプラグインルートの単一の MIGRATION.md に統合し、選択した出力モードに従って元の Cordova ソースをアーカイブまたは削除し、README をコンシューマー向けの破壊的変更（コールバック → プロミス、位置引数 → 名前付き引数、手動ネイティブセットアップ）で更新します。

すべての migration.notes および migration.warnings エントリが、Agent Behavior ルールに従って（プラグインパッケージング / ホストアプリのビルド構成 / コンシューマーランタイム構成）にバケット分けされていることをクロスチェックします。MIGRATION.md には、バケット 2 または 3 に該当する項目のみを記載する必要があります。プラグインパッケージングの項目はコンシューマーに対して透過的であり、移行の記録に含めるべきではありません。

ベストプラクティス

DO

• ✅ 最初に plugin.xml を読み、すべての主張を実際の XML、ソースパス、またはフックスクリプトの内容に基づかせてください。ブロッカーについては行番号を引用してください。
• ✅ ジェネレーターの入力契約を権威あるものとして扱ってください。capacitor-plugin-generator/references/input-contract.md に基づいて YAML を構築してください。
• ✅ 公式の Capacitor 相当が存在する場合は、そのワイヤーフォーマット文字列を再利用してください。enum の大文字小文字、イベント名、メソッド名を正確にミラーリングしてください。
• ✅ フックはファイル名ではなく、参照されているスクリプトを読んで分類してください。
• ✅ デフォルトはモード B（サイドバイサイド）です。書き込み可能な作業コピーを用意した上で、ユーザーが明示的にオプトインした場合にのみモード A に移行してください。
• ✅ ブロッカーまたは Tier 3 フックが存在する場合は、フェーズ 10 のチェックポイントで停止してください。
• ✅ ブロッカーと警告の両方を記録してください。引き渡しを停止するのはブロッカーのみです。
• ✅ 移行後にコンシューマーが必要とする手動ネイティブセットアップ手順（Info.plist のキー、AndroidManifest のエントリ、Podfile / Gradle の追加）を注記してください。

禁止事項

• ❌ このスキルからネイティブの Capacitor コード（Swift、Kotlin、Java、TypeScript）を出力しないでください。コード出力はジェネレーターが担当します。
• ❌ YAML フィールドを独自に作成したり、ジェネレーターがすでに定義しているフィールド名を変更したりしないでください。
• ❌ 公式の Capacitor 相当の文字列がある場合、人間にわかりやすい名前からワイヤーフォーマットの文字列を再導出しないでください。definitions.ts を確認してください。
• ❌ 参照先のスクリプトを開かずに、フックを Tier 1／2 に分類しないでください。
• ❌ 独自仕様の AAR や対話型セットアップフックを隠したまま、complexity: simple と記載した YAML プランを出力しないでください。
• ❌ ここに Capacitor のバージョン固有のガイダンスを追加しないでください。ジェネレータースキルが、ジェネレーター側のルール（名前の一致、Java ファイル名、notifyListeners の可視性など）を担当します。重複させず、参照してください。
• ❌ ユーザーに知らせずにジェネレーターを呼び出さないでください。フェーズ 10 は必須のユーザーチェックポイントです。省略しないでください。
• ❌ ブロッカーや未解決の Tier 3 フックがある状態で、ジェネレーターを呼び出さないでください。
• ❌ このスキルからジェネレーターの出力をコミット、プッシュ、公開しないでください。

エラー処理

症状	対処方法
plugin.xml がない、または形式が正しくない	停止します。正式なプラグインソースを依頼してください。README の宣伝文句から仕様を推測しないでください。
plugin.xml で参照されているソースファイルがディスク上にない	停止します。パスを示して不足ファイルを報告してください。不足ファイルがある状態では計画は不完全です。Phase 9 に進まないでください。
フックが、開けないスクリプトまたは難読化されたスクリプトを参照している	Tier 3 に分類し、スクリプトのパスとともに migration.blockers に追加してください。フックの種類から推測しないでください。
プラグインが、ユーザーの持っていないランタイム認証情報を必要とする非公開／プロプライエタリな AAR または .framework の <framework> を宣言している	ブロッカーとして記録してください。ベンダーへの問い合わせが必要であることを記載してください。公開されている代替品に黙って差し替えないでください。
プラグインが、ツリー内のバイナリ（例：src/ios/frameworks/Foo.xcframework、src/android/libs/Foo.aar）を同梱しているが、そのバイナリは公開配布されている	ブロッカーではありません。バイナリを引き継ぎ、パスを migration.source_files.{ios,android} に記録してください。ジェネレーターはバイナリを Capacitor プラグインの ios/ または android/libs/ ディレクトリにコピーします。
プラグインが Android の依存関係をカスタム Maven リポジトリ（Azure DevOps、JFrog など）から取得している	URL を migration.dependencies.android.maven_repos に記録してください。認証なしで URL にアクセスできる場合は警告であり、ブロッカーではありません。認証が必要で、認証情報が提供されていない場合はブロッカーです。
プラグインが Support Library（android.support.*）の座標を使用している	ユーザーが Jetifier の使用を承認しない限り、ブロッカーとして記録してください。Capacitor は AndroidX を前提としています。
Cordova プラグインに公式の Capacitor 版（@capacitor/<name>）がある	そのプラグインの definitions.ts とネイティブソースを読み、メソッド名、列挙値、イベント名、エラーコードを YAML に固定してください。レビュー担当者向けに、公式版のパッケージを migration.notes に追加してください。
プラグインが <hook> エントリと package.json の scripts.capacitor:* エントリの両方を宣言している（ハイブリッドプラグイン）	Capacitor スクリプトはすでに存在します。それらを Tier 1 の「変換済み」フックとして記録してください。新たに移行する Cordova フックと再利用、書き換え、統合のどれを行うか、ユーザーに確認してください。
プラグインが <config-file> を使用して、<uses-permission>、<meta-data>、<queries>、または <provider> で AndroidManifest.xml を変更している	プラグイン独自の android/src/main/AndroidManifest.xml に記述します。Gradle のマニフェストマージャーがホストアプリに自動でマージします。ホストアプリ側での作業は不要です。ジェネレーターが出力できるよう、migration.notes に記録してください。
プラグインが <config-file> を使用して、Apple が必須とするプライバシー文字列（NSCameraUsageDescription、NSLocationWhenInUseUsageDescription、NSMicrophoneUsageDescription など）で Info.plist を変更している	ホストアプリの Info.plist に記述します。Apple App Store では、プラグインの plist ではなくホストアプリの plist にこれらを指定する必要があります。migration.notes に記録し、MIGRATION.md にコピーして貼り付けられるスニペットを記載してください。
プラグインが <config-file> を使用して、$VAR のインストール時プレースホルダーを介し、利用者固有の値（Apple Pay の加盟店 ID、OAuth クライアント ID、分析キー）で Info.plist を変更している	ランタイム設定 JSON ファイルのパターンを強く推奨します。ハイブリッドの capacitor:sync:after スクリプトが <Plugin>Configuration.json を読み取る方式です。Cordova プラグインに既存のスクリプトがあれば再利用し、なければ1画面分のテンプレートを提案してください。これにより、利用者固有の値を plist に一切含めずに済みます。
プラグインが <config-file> を使用して、com.apple.developer.in-app-payments、aps-environment、com.apple.security.application-groups などの機能に関するエンタイトルメント plist（*-Debug.plist、*-Release.plist、*-Entitlements.plist）を変更している	ホストアプリの機能とエンタイトルメントです。 migration.notes に記録し、利用者が有効にする必要がある正確な Xcode 機能（Apple Pay、プッシュ通知、App Groups など）とエンタイトルメントの値を MIGRATION.md に記載してください。
プラグインが iOS 用に weak="true" を指定した <framework> を宣言している	プラグイン独自の podspec に記述します。 dependencies.ios.system_frameworks に記録し、ジェネレーターが s.framework ではなく s.weak_framework を出力するよう、migration.notes に行を追加してください。ホストアプリ側での作業は不要です。
プラグインが <edit-config> と mode="merge" を使用して、ホストの <application> 要素に android:requestLegacyExternalStorage などの属性を追加している	属性がホストアプリに適用される場合はホストアプリの AndroidManifest、それ以外の場合はプラグイン独自の AndroidManifest に記述します。正確な属性と親要素を migration.notes に記録し、MIGRATION.md にコピーして貼り付けられるスニペットを記載できるようにしてください。
プラグインが <js-module runs="true"> を使用している	migration.warnings に追加してください。Web レイヤーで明示的な initialize() メソッドを使うか、コンストラクター側で初期化することを推奨してください。
プラグインに、複数の <clobbers> ターゲット（例：定数モジュールとメインモジュール）を持つ <js-module> エントリが複数ある	1つの registerPlugin() 登録にまとめてください。プラグインインターフェースの隣にある definitions.ts から定数をエクスポートしてください。Capacitor には複数の clobber に相当する機能はありません。
プラグインが <source-file target-dir="res/..."> を介して Android リソースファイルを含めている	配置先の res/ サブパスとともに migration.source_files.android に記録してください。ジェネレーターはファイルを android/src/main/res/<subpath>/ にコピーします。FileProvider のパスやテーマでよく使われます。
プラグインが <config-file target="*-Info.plist"> または AndroidManifest.xml 内で参照される、インストール時の変数置換（plugin.xml 内の ${VAR}）を伴う <preference name="..." default="..."> を使用している	ランタイム設定 JSON ファイルのパターンを優先してください（利用者が値を <Plugin>Configuration.json に記述し、ハイブリッドの capacitor:sync:after スクリプトがそれを読み取る方式です）。Cordova プラグインに既存のスクリプトがあれば再利用してください。代替案として、plugins.<PluginJSName> の下にある capacitor.config.json のランタイム設定を使用してください。
プラグインが <preference name="ANDROIDX_CORE_VERSION" default="1.18.0">（または同様のビルド時のみのバージョン固定）を使用し、プラグイン独自の build.gradle 内で参照している	プラグイン独自の build.gradle に記述します。生成する Gradle ファイルにバージョンをそのまま固定してください。ホストアプリ側の作業もランタイム設定も不要です。利用者に見えることはありません。
プラグインのネイティブハンドラーが文字列化された JSON の塊（Gson.fromJson、JSONObject(args.getString(0))）を解析している	解析された構造を、string ではなく、厳密に型付けされた api.types インターフェースに対応付けてください。ネイティブ側の解析箇所（Kotlin のデータクラスまたは Swift の構造体）からスキーマを取得してください。
1つの JS メソッドが、typeof param に応じて複数の cordova.exec() アクション名に振り分けている（例：vibrate(num) と vibrate([...])）	vibrate({ duration })、vibrateWithPattern({ pattern, repeat })、cancelVibration() のように、型付けされた複数の Capacitor メソッドに分割してください。分割内容を migration.cordova_to_capacitor_map に記録し、利用者向けの破壊的変更として migration.warnings に追加してください。
ジェネレーターが「bad indentation」または「mapping entry」の解析エラーで YAML を拒否する	cordova_to_capacitor_map のエントリに、引用符で囲まれていない JS 構文（(、{、: など）が含まれています。すべての cordova: と capacitor: の値を YAML 文字列として引用符で囲んでください。計画を再出力する必要があります。ジェネレーターは現状のままでは読み込めません。
Cordova のネイティブソースはランタイム権限を要求するが、Cordova の JS インターフェースに権限メソッドがない	api.methods に checkPermissions()（Promise<PermissionStatus>）と requestPermissions(options?)（Promise<PermissionStatus>）を追加し、api.types に PermissionStatus インターフェースを追加してください。これらがないと、移行後のプラグインは Capacitor の規約に違反し、利用者はこれらのメソッドを期待します。
Cordova のネイティブソースにメタデータ抽出用のヘルパークラス（ExifHelper、MimeTypeHelper など）があるが、Cordova の JS ドキュメントに結果のフィールドが記載されていない	ネイティブ側でレスポンスを構築している箇所を読んでください。結果の型にメタデータフィールド（通常は exif?: any、mimeType?、size?）を追加してください。Cordova の JS ドキュメントでは、ネイティブ側が実際に返す値が十分に記載されていないことがよくあります。
公式 Capacitor 版のネイティブソースの LOC が Cordova ソースの3倍を超えている	migration.notes に、単純な移植ではプラットフォーム固有の動作が実装されないことをレビュー担当者に警告する記述を追加してください（例：iOS で CHHapticEngine ではなく AudioServicesPlaySystemSound を使う、Android で単発の振動ではなくパターンベースの触覚フィードバックを使うなど）。利用者を公式パッケージに移行させるかどうかの検討を推奨してください。
Cordova プラグインの plugin.xml に <platform name="ios" package="swift"> または nospm="true" の <pod ... nospm="true"> がある	プラグインはすでに CocoaPods とともに SPM にも対応しています。Package.swift の依存関係を dependencies.ios.spm に移し、nospm="true" でないポッドのみを dependencies.ios.cocoapods に移してください。Capacitor 版には Package.swift と .podspec の両方を含める必要があります。
プラグインが別の Cordova プラグインへの <dependency> を宣言している	依存先を個別に調査してください。Capacitor 版または移行計画がない場合は、現在のプラグインのブロッカーとして扱ってください。
プラグインの iOS ソースが Objective-C のみである	migration.language_modernization.ios: { from: objective_c, to: swift } を記録してください。利用者にブリッジングヘッダーが引き続き必要になる可能性があることを記載してください。
プラグインの Android ソースが Java のみである	migration.language_modernization.android: { from: java, to: kotlin } を記録してください。ユーザーが指定すればジェネレーターは Java を出力しますが、Kotlin を標準の推奨言語とします。
ジェネレーターが YAML を拒否する	capacitor-plugin-generator/references/input-contract.md を読み直してください。ジェネレーターではなく、このスキル内の YAML を修正してください。仕様を回避しないでください。
ジェネレーターが wire-format 文字列の不足を指摘する	公式 Capacitor 版の definitions.ts を読み直してください。api.types の値をそのまま更新してください。人にわかりやすい名前から「翻訳」しないでください。
ユーザーが Mode A を要求しているが、作業コピーがバージョン管理下にない、または読み取り専用である	Mode A を拒否してください。Mode B を推奨してください。バージョン管理なしで、問題が起きたインプレース移動から復旧する作業は手動になります。
プラグインが、ソースに実装されていない機能を宣伝している	ソースを信頼してください。宣伝されているが未実装の機能を migration.warnings に記録してください。ドキュメントに合わせるために API メソッドを捏造しないでください。
ファイル名から Tier 1 と分類されたフックが、実際には対話型である	<hook> の name 属性だけでなく、スクリプトのソースを読んでください。stdin から入力を促す、TTY を開く、または read／prompt を実行するものはすべて Tier 3 です。
「直接移行」と分類された依存関係のポッドまたは Gradle アーティファクトが放棄されている	直接移行と分類する前に、最新リリース日と Swift／AndroidX の互換性を照合してください。3年以上更新されていないものはすべて「置き換え」または「ブロッカー」に変更してください。
複雑さが「Simple」と評価されたが、プラグインに15以上の公開 API メソッドがある	公開 API メソッド数は必ず数えてください。公開メソッドが10個を超えるプラグインは、ほかの指標に関係なく、少なくとも Moderate です。
分析中にブロッカーを見落とした	plugin.xml の <config-file>、<edit-config>、<js-module runs="true">、<hook>、<dependency> を必ず確認してください。これらは見落としが許されないブロッカー候補です。YAML が整いすぎているように見える場合は、Phase 9 の前に再確認してください。
ジェネレーターが Phase 11 中に Cordova ソースを再読み込みする	YAML 計画が不完全です。capacitor-plugin-generator/references/input-contract.md に照らして再検証し、JS API シグネチャ、ネイティブメソッドのマッピング、権限、依存関係、ブロッカーをインラインで含めてください。ジェネレーターが Cordova ツリーを参照する必要がない状態にしてください。
ユーザーが、受け入れられないブロッカーのためチェックポイントで中断する	ブロッカーを MIGRATION.md に記録して停止してください。ジェネレーターを呼び出さないでください。次回の試行で対応できるよう、拒否理由を記録してください。
複雑なプラグインのため、1回の呼び出しでジェネレーターのコンテキストが処理しきれない	段階実行モードを使用してください。プラグイン全体を一度に処理するのではなく、ユーザーのチェックポイントを挟みながら、プラットフォームごと（web → iOS → Android → final）にジェネレーターを1回ずつ呼び出してください。references/using-plugin-generator.md を参照してください。
Mode A の移動先が、Cordova リポジトリ内のファイルと競合している（トップレベル名の衝突）	一連の処理を中断してください。ユーザーと手動で解決する（競合ファイルの名前変更、削除、移動）か、兄弟ディレクトリを対象に Phase 11 を再実行して Mode B に切り替えてください。

関連スキル

• capacitor-plugin-generator (必須の後続依存関係)： フェーズ 11 では、フェーズ 9 で生成された YAML プランを使用して、構造化モードの Skill ツールからこのスキルを呼び出します。引き継ぎの正式な形式は、ジェネレーターの references/input-contract.md に記載されています。このスキルはその形式に準拠して参照しますが、ジェネレーター側のルールを重複して記載することはありません。
• build-actions-generator (ODC パスのみで使用する任意の後続依存関係)： odc_target: true の場合、フェーズ 11a でこのスキルを呼び出します。Capacitor プラグインの build-actions/ ディレクトリ用に buildAction.json を生成し、設定レベルのネイティブセットアップ（マニフェスト、plist、Gradle 依存関係、エンタイトルメント）を処理することで、これらの項目に対する Capacitor フック相当のものをジェネレーターが出力する必要がなくなります。

参考資料

• references/output-modes.md：Mode A（.cordova-archive/ を使用した同じ場所での移行）と Mode B（並行配置）のディレクトリ構成、および git mv のパターン。
• references/unsupported-patterns.md：<config-file>、<edit-config>、<hook>、<js-module runs>、設定項目、権限、およびパターンごとのブロッカーしきい値。
• references/dependency-migration.md：CocoaPods、SPM、システムフレームワーク、Gradle の座標、AAR/JAR、カスタム Maven リポジトリ、および依存関係ごとのブロッカーしきい値。
• references/hooks-migration.md：3 段階のフック分類（Tier 1：Capacitor フック、Tier 2：npm スクリプト、Tier 3：ブロッカー）とスクリプト分析ワークフロー。
• references/api-mappings.md：JavaScript ブリッジ、iOS（CDVPlugin → CAPPlugin）、Android（CordovaPlugin → Plugin）、および plugin.xml から package.json への変換。
• references/migration-patterns.md：コールバックから Promise への変換、権限処理、マルチプラットフォーム設定、および各プラットフォームで一貫したエラー処理。
• references/complexity-assessment.md：simple / moderate / complex / blocked の評価基準と、プラグインの分類を変える入力項目。
• references/using-plugin-generator.md：capacitor-plugin-generator/references/input-contract.md に基づく YAML の作成、migration: の任意ブロック、およびフェーズ 11 の呼び出しパターン（標準モードと増分モード）。
• references/post-migration-cleanup.md：中間メモを MIGRATION.md に集約する方法、Mode A の移動フロー、Cordova ソースのアーカイブ、README の更新、および利用者向けの破壊的変更チェックリスト。
• references/example-analysis.md：一連の完全な実例（plugin.xml の読み込み、依存関係の分析、フックの分類、YAML 出力、ジェネレーターへの引き継ぎ）。