Cordova Plugin Migrator

Cordova Plugin Migrator

End-to-end orchestrator that takes a Cordova plugin source tree and produces a candidate Capacitor plugin plus a consolidated MIGRATION.md, via a single skill invocation. Internally it analyzes the Cordova plugin, emits a structured YAML plan conforming to capacitor-plugin-generator/references/input-contract.md, hits a user checkpoint, then invokes the capacitor-plugin-generator skill in structured mode with that plan. This skill never re-implements what the generator already does; the generator owns scaffolding and native code emission.

When to Use This Skill

✅ Use this skill when:

• Migrating an existing Cordova plugin to Capacitor.
• Assessing migration complexity, effort, and blockers before committing.
• Producing the structured handoff YAML for capacitor-plugin-generator.
• Comparing the official Cordova API to an existing or planned Capacitor API.
• Auditing a Cordova plugin's hooks, native dependencies, or <config-file> modifications for portability.

❌ Do NOT use this skill for:

• Generating a Capacitor plugin scaffold or implementation, pass the plan to capacitor-plugin-generator.
• Designing a brand-new plugin without prior Cordova source.
• Migrating entire Cordova apps. Scope is plugin-level only.
• Debugging runtime issues in an already-migrated plugin.
• Publishing or releasing the resulting Capacitor plugin.

Prerequisites

Agent Behavior

• Run as an orchestrator. Phases 1–10 analyze the Cordova source and produce a YAML plan; Phase 11 invokes capacitor-plugin-generator via the Skill tool, passing the plan in structured mode; Phase 12 consolidates documentation. Do not emit native Capacitor code from this skill. The generator owns that.

• Read capacitor-plugin-generator/references/input-contract.md before producing YAML. The generator's contract is authoritative; do not invent fields or rename existing ones.

• Resolve the plugin's identity from plugin.xml first: id, name, version, declared platforms, declared frameworks, hooks, and config-file targets.

• Inspect every native dependency declaration before asserting platform support. Mirror what plugin.xml actually says, not what the README claims.

• Classify each <hook> into Tier 1 (Capacitor hooks), Tier 2 (npm scripts/manual steps), or Tier 3 (blocker) using the rules in references/hooks-migration.md. A single Tier 3 hook is enough to block generator handoff.

• When an official Capacitor equivalent exists (@capacitor/<name> or a Capawesome/community port), read its definitions.ts and native source. Reuse its wire-format strings, enum values, method names, and event names verbatim. Do not invent parallel APIs that "look similar."

• Detect hybrid plugins. If package.json already declares scripts.capacitor:* hooks, the plugin is partially Capacitor-aware. Record the existing hooks as Tier 1 "already converted" and ask the user whether to reuse, rewrite, or merge them. Do not silently drop them.

• A JS method whose Cordova-side argument is a stringified JSON blob (JSON.parse / Gson.fromJson / JSONObject(args.getString(0)) in the native handler) must be mapped to a strongly-typed TypeScript interface in api.types, not a string parameter. Capture the interface shape from the native parsing site.

• When the Cordova native source uses runtime permission APIs (cordova.requestPermission, requestPermissions(...), AVCaptureDevice.requestAccess, PHPhotoLibrary.requestAuthorization, CLLocationManager delegates, CNContactStore.requestAccess, etc.), add checkPermissions() and requestPermissions() methods to the YAML even if the Cordova JS surface did not expose them. Capacitor's convention is explicit permission methods, and the official equivalent (if any) almost always exposes them.

• When the Cordova native source extracts metadata in helper classes (ExifHelper, MimeTypeHelper, ImageMetadata, etc.) and includes it in the response payload, capture those fields in the corresponding api.types interface, even if the Cordova JS docs did not document them. Read the native code, not the README.

• When mirroring an official Capacitor equivalent, sanity-check the official's native LOC against the Cordova source's native LOC. If the official is more than 3× larger, add a migration.notes entry warning the reviewer that a literal port will leave behavior the official handles (e.g., iOS CHHapticEngine for duration-accurate vibration, Android VibrationEffect patterns for impact / notification) on the floor. The generator's SDK-adapter rule may or may not catch this.

• Distinguish three downstream destinations when emitting setup notes:

  1. Plugin's own packaging. Gradle implementation '...' lines, CocoaPods s.dependency '...' lines, custom Maven repo URLs, s.weak_framework, s.vendored_frameworks, AndroidManifest <uses-permission> / <meta-data> / <queries> entries, and @CapacitorPlugin(permissions = [...]) declarations all belong in the plugin's own android/build.gradle, .podspec, android/src/main/AndroidManifest.xml, or annotations. Gradle's manifest merger and CocoaPods transitively propagate these to consumers, so no host-app step and no MIGRATION.md entry is required.
  2. Host-app build configuration. Items that cannot live in the plugin package and must be applied to the consuming app: Info.plist privacy strings (NSCameraUsageDescription, NSLocationWhenInUseUsageDescription, etc.), iOS capabilities and entitlements (Apple Pay merchant ID, aps-environment, com.apple.security.application-groups), and any other manifest mutation that must live on the host app rather than the plugin. Record under migration.notes and document in MIGRATION.md with copy-paste-ready snippets per platform.
  3. Consumer runtime config / code. Apple Developer-side credential provisioning, host-app-supplied JSON config values (merchant numbers, API keys), and consumer JS call-site migration (callback → Promise, positional → named). No tool can automate these because the inputs are the consumer's own data.

  Record each plugin.xml directive under one of those three buckets in migration.notes. Never write a MIGRATION.md step that asks consumers to add implementation '...' for a dep the plugin should bundle. See references/dependency-migration.md "Ownership Model" for the dep-specific table.

• When the Cordova plugin used <preference name="VAR" default="..."> install-time placeholders inside <config-file target="*-Info.plist"> entries (Apple Pay merchant config, OAuth client IDs, analytics keys, etc.), detect it and recommend the runtime config JSON file pattern in migration.warnings: a PluginConfig.json consumed by a hybrid capacitor:sync:after script that copies the file into native projects at build time. The Cordova plugin may already ship this script (look for it in hooks/capacitor*.js); if so, reuse it. Otherwise propose a one-screen template. This pattern keeps consumer values out of static plist / manifest entries entirely.

• Detect SPM markers in plugin.xml: <platform name="ios" package="swift"> and <pod ... nospm="true"> indicate the Cordova plugin already ships a sibling Package.swift. When present: (a) read that Package.swift and lift its dependencies into the YAML's dependencies.ios.spm, (b) move any pod without nospm="true" to dependencies.ios.cocoapods, (c) add a migration.notes entry that the generated Capacitor plugin must ship both Package.swift and .podspec (Capacitor 8 supports both, and SPM is the default for new plugins). See references/dependency-migration.md "Swift Package Manager (SPM)" for the schema.

• Default output mode is Mode B (side-by-side directory). Switch to Mode A (in-place with .cordova-archive/) only when the user explicitly asks and the source is in a writable working copy.

• Stop and request user input when blockers, Tier 3 hooks, unresolvable proprietary SDKs, or missing source files would force you to guess. Do not emit a YAML plan that hides the gap.

• Distinguish between resolvable warnings (documented manual steps) and blockers (cannot be auto-migrated). Both go in the plan; only blockers stop handoff.

• A vendored binary checked into the Cordova plugin's tree (e.g., src/ios/frameworks/Foo.xcframework) is not a blocker on its own. Carry the binary forward and record its path under migration.source_files.ios (or .android). Treat as blocker only when the binary requires runtime credentials the user does not have or fails AndroidX / 64-bit / simulator requirements.

• Report what was actually inspected. Cite file paths and line numbers when flagging blockers or unsupported patterns.

• Compare iOS and Android findings against each other before declaring Phase 9. If one platform exposes a method the other does not, surface the mismatch in migration.warnings so the generator can pick a strategy (mirror both, expose conditionally, or drop). Do not silently emit a contract that only one platform can fulfil.

• Default response shape is architecture and plan, not code. Do not include full before/after code blocks unless the user explicitly asks for "show me the code" or "deep dive". Per-method one-line mappings in migration.cordova_to_capacitor_map are not "code" in this sense, they are part of the plan.

• Quote every value in migration.cordova_to_capacitor_map and any other YAML string that contains JS syntax ((, ), {, }, :, [, ]). Unquoted JS expressions like Foo.bar({ x: 1 }) are unparseable YAML and the generator will reject the plan at load time.

• Invoke the generator only after the Phase 10 user checkpoint approves. If the user rejects, halts, or has unanswered blockers, stop. Never invoke the generator with a YAML that has non-empty migration.blockers or non-empty migration.hooks.tier_3.

• When odc_target: true, Phase 11 splits into two sequential sub-phases (11a and 11b). Phase 11a invokes build-actions-generator; Phase 11b invokes capacitor-plugin-generator. See references/using-plugin-generator.md "ODC Path" for the full sequence. Build actions are written to the Capacitor plugin folder. Hooks and migration notes that are fully covered by build actions must be excluded from the YAML passed to the generator (Phase 11b), to avoid the generator emitting redundant Capacitor hook scripts for config-level work already handled by build actions.

Procedures

Phase 1: Determine the Task and Output Mode

Confirm the user has a Cordova plugin to migrate. If the user wants a brand-new Capacitor plugin from scratch with no Cordova source to convert, stop here and redirect to capacitor-plugin-generator directly, this skill has nothing to add.

Otherwise, pick the output mode:

• Mode B (default, side-by-side), generator scaffolds a new Capacitor plugin into a sibling directory of the Cordova repo. The Cordova repo is never touched.
• Mode A (opt-in, in-place), generator scaffolds into a temp directory. After Phase 11 succeeds, Phase 12 relocates the generator's output into the Cordova repo root and moves the original Cordova source under .cordova-archive/. Preserves the original repo's npm package name and git history. Requires explicit user opt-in and a clean writable git working copy.

See references/output-modes.md for layouts, pre-flight checks, and the exact relocation sequence.

ODC confirmation: Check whether the user mentioned ODC or OutSystems Developer Cloud anywhere in the request. If yes, set odc_target: true and proceed. If not, ask: "Will this Capacitor plugin be consumed by an ODC (OutSystems Developer Cloud) app? If yes, build actions will be generated alongside the Capacitor plugin to handle native configuration in MABS." Record the answer as odc_target: true/false for use in Phase 11.

Phase 2: Read plugin.xml

A typical Cordova plugin layout:

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

Open plugin.xml. Extract: plugin id, name, version, declared platforms (<platform name="...">), <source-file>/<header-file> mappings, <framework> entries, <podspec> blocks, <config-file> targets, <edit-config> targets, <hook> declarations, <dependency> entries, <preference> tags, and <js-module> exposure (clobbers / merges / runs). Record file paths and line numbers for every blocker candidate.

Phase 3: Analyze Native Dependencies

Apply references/dependency-migration.md. For each <framework> and <podspec> pod, decide: direct migration, version update, alternative library, or blocker. For each Android Gradle coord, check AndroidX vs Support Library and Capacitor's minimum compile SDK. Record manual installation steps required after migration.

Phase 4: Analyze Hooks

Apply the three-tier rule in references/hooks-migration.md:

• Tier 1, convertible to a Capacitor plugin npm hook (capacitor:{sync,copy,update}:{before,after}, capacitor:{android,ios}:add:{before,after}).
• Tier 2, convertible to an npm lifecycle script (postinstall, preuninstall) or a documented manual step.
• Tier 3, interactive prompts, plugin.xml/config.xml mutation, Cordova CLI internals, or anything else with no Capacitor equivalent.

Read each referenced script. Do not classify on filename alone.

Phase 5: Analyze the JavaScript Bridge

Apply references/api-mappings.md. From www/*.js, list every public method, its positional argument shape, whether it uses success/error callbacks or returns a promise, and whether exec() is paired with a cordova.exec() action name. Map each method to a Capacitor methodName(options): Promise<R> signature.

Phase 6: Analyze iOS Implementation

Apply references/api-mappings.md. From src/ios/*.{h,m,swift}, identify the CDVPlugin subclass, each method matching a JS action, argument extraction from command.arguments, response construction (CDVPluginResult), permission flows, and any system frameworks or SDK adapters used. Note where Objective-C must be modernized to Swift.

Phase 7: Analyze Android Implementation

Apply references/api-mappings.md. From src/android/**/*.{java,kt}, identify the CordovaPlugin subclass, the execute() router, action strings, argument extraction (args.getString(i)), response paths (CallbackContext.success/error), permission flows, and any Activity Result patterns. Note where Java must be modernized to Kotlin.

Phase 8: Assess Complexity

Apply references/complexity-assessment.md. Score the plugin on method count, LOC, dependency footprint, hook tier mix, language modernization, blocker count, and Capacitor-equivalent reuse. Output one of: simple, moderate, complex, blocked. blocked means the user must resolve issues before generator handoff.

Phase 9: Produce the Migration YAML

Apply references/using-plugin-generator.md. Build the YAML against the generator's references/input-contract.md, base block (plugin, platforms, api, permissions, dependencies) plus the optional migration: block (source, complexity, output_mode, blockers, warnings, language_modernization, source_files, hooks, cordova_to_capacitor_map). Pin wire-format strings to the official Capacitor equivalent when one exists.

Phase 10: User Checkpoint

Present a short human summary alongside the YAML: complexity, blockers, warnings, manual setup, recommended output mode, and any Capacitor equivalent being mirrored. Stop and wait for confirmation if blockers or Tier 3 hooks are non-empty.

Phase 11: Invoke Downstream Skills

The downstream invocation path depends on whether ODC was confirmed in Phase 1.

Non-ODC path: Apply references/using-plugin-generator.md. Invoke capacitor-plugin-generator via the Skill tool in structured mode with the Phase 9 YAML. The generator runs its own playbook; this skill does not re-inspect Cordova source. For Complex plugins use incremental mode (one platform at a time with user checkpoints). If the generator rejects the YAML, return to Phase 9 and fix it — never hand-edit generator output.

ODC path: Follow the two-sub-phase sequence in references/using-plugin-generator.md "ODC Path":

• Phase 11a — Invoke build-actions-generator with the Phase 9 YAML and the Cordova plugin path; wait for build-actions/ output. Note which hooks/elements it covered.
• Phase 11b — Remove build-action-covered items from migration.hooks.tier_1 (or mark status: handled_by_build_actions); add a migration.notes entry documenting this. Then invoke capacitor-plugin-generator with the annotated YAML (standard or incremental per complexity).

Phase 12: Post-Migration Cleanup

Apply references/post-migration-cleanup.md. After the generator produces a working scaffold, consolidate intermediate notes into a single MIGRATION.md at the plugin root, archive or remove the original Cordova source per the chosen output mode, and update the README with the consumer-facing breaking changes (callbacks → promises, positional → named arguments, manual native setup).

Cross-check that every migration.notes and migration.warnings entry is bucketed (plugin packaging / host-app build configuration / consumer runtime config) per the Agent Behavior rule. The MIGRATION.md should list only items that fall in buckets 2 or 3. Plugin-packaging items are transparent to consumers and do not belong in the migration trail.

Best Practices

DO

• ✅ Read plugin.xml first and ground every claim in actual XML, source paths, or hook script content. Cite line numbers for blockers.
• ✅ Treat the generator's input contract as authoritative. Build the YAML against capacitor-plugin-generator/references/input-contract.md.
• ✅ Reuse wire-format strings from an official Capacitor equivalent when one exists. Mirror enum casing, event names, and method names exactly.
• ✅ Classify hooks by reading the referenced script, not by filename.
• ✅ Default to Mode B (side-by-side). Move to Mode A only on explicit user opt-in with a writable working copy.
• ✅ Stop at the Phase 10 checkpoint if blockers or Tier 3 hooks exist.
• ✅ Capture both blockers and warnings; only blockers stop handoff.
• ✅ Note manual native setup steps consumers will need after migration (Info.plist keys, AndroidManifest entries, Podfile / Gradle additions).

DON'T

• ❌ Emit native Capacitor code (Swift, Kotlin, Java, TypeScript) from this skill. The generator owns code emission.
• ❌ Invent YAML fields or rename ones the generator already defines.
• ❌ Re-derive wire-format strings from human-friendly names when an official Capacitor equivalent exists. Read its definitions.ts.
• ❌ Classify a hook as Tier 1/2 without opening the referenced script.
• ❌ Emit a YAML plan that lists complexity: simple while hiding a proprietary AAR or interactive setup hook.
• ❌ Add Capacitor-version-specific guidance here, the generator skill owns generator-side rules (name parity, Java filename, notifyListeners visibility, etc.). Reference, don't duplicate.
• ❌ Invoke the generator silently. Phase 10 is a mandatory user checkpoint; do not skip it.
• ❌ Invoke the generator with blockers or Tier 3 hooks unresolved.
• ❌ Commit, push, or publish generator output from this skill.

Error Handling

Related Skills

• capacitor-plugin-generator (required downstream dependency): Phase 11 invokes this skill via the Skill tool in structured mode with the YAML plan produced in Phase 9. The generator's references/input-contract.md is the authoritative shape for handoff. This skill conforms and cites it but does not duplicate any generator-side rules.
• build-actions-generator (optional downstream dependency, ODC path only): Phase 11a invokes this skill when odc_target: true. It generates buildAction.json for the Capacitor plugin's build-actions/ directory, covering config-level native setup (manifest, plist, Gradle deps, entitlements) so the generator does not need to emit Capacitor hook equivalents for those items.

References

• references/output-modes.md: Mode A (in-place with .cordova-archive/) vs Mode B (side-by-side) directory layouts and git mv patterns.
• references/unsupported-patterns.md: <config-file>, <edit-config>, <hook>, <js-module runs>, preferences, permissions, and per-pattern blocker thresholds.
• references/dependency-migration.md: CocoaPods, SPM, system frameworks, Gradle coordinates, AAR/JAR, custom Maven repos, and per-dependency blocker thresholds.
• references/hooks-migration.md: Three-tier hook classification (Tier 1 Capacitor hooks, Tier 2 npm scripts, Tier 3 blocker) with script analysis workflow.
• references/api-mappings.md: JavaScript bridge, iOS (CDVPlugin → CAPPlugin), Android (CordovaPlugin → Plugin), and plugin.xml → package.json conversion.
• references/migration-patterns.md: Callback → Promise, permission handling, multi-platform configuration, and consistent error handling across platforms.
• references/complexity-assessment.md: Scoring rubric for simple / moderate / complex / blocked and the inputs that move a plugin between buckets.
• references/using-plugin-generator.md: Building the YAML against capacitor-plugin-generator/references/input-contract.md, the migration: optional block, and the Phase 11 invocation pattern (standard vs incremental mode).
• references/post-migration-cleanup.md: Consolidating intermediate notes into MIGRATION.md, the Mode A relocation flow, archiving Cordova source, updating README, and the consumer-facing breaking-change checklist.
• references/example-analysis.md: Full worked example end-to-end, plugin.xml read, dependency analysis, hooks classification, YAML output, and generator handoff.