git:20260501.ed3e92e to git:20261011.86834d4

41 added, 48 removed. Audit A to A.

---

name: capacitor-plugin-upgrades

- description: Guides the agent through upgrading a Capacitor plugin to a newer major version. Covers dependency alignment, native platform changes, example app verification, and multi-version jumps. Do not use for app project upgrades or non-Capacitor plugin frameworks.

+ description: Routes and drives a Capacitor plugin library upgrade across one or more major versions (4 to 9), including the iOS UIScene lifecycle audit that Capacitor 8.5 and 9 require. Detects the supported Capacitor range, plans hops (e.g. 7 to 8 to 9), runs each official plugin migrator, delegates to the per-version skill, and verifies TypeScript, Android, iOS (podspec and Package.swift) and the example app. Use for "upgrade my plugin to the latest Capacitor", "support Capacitor 9 in my plugin", bumping peerDependencies, or multi-version plugin jumps. Do not use for app projects (use capacitor-app-upgrades) or non-Capacitor plugin frameworks.

allowed-tools:

- Bash(node -e *)

- Bash(find *)

- Bash(npm *)

- Bash(npx *)

---

- # Capacitor Plugin Upgrade

+ # Capacitor Plugin Upgrade (router)

- Upgrade a Capacitor plugin to a newer major version.

+ Plan and run a plugin upgrade one major at a time, using the version-specific skill for each hop.

- ## When to Use This Skill

+ ## When to Use

- - User wants to bump a Capacitor plugin package to a newer major version

- - User needs help adapting native code to a new Capacitor major release

- - User wants to verify the plugin still works in its example app after the upgrade

+ TRIGGER when:

+ - Plugin maintainer wants support for a newer Capacitor major and the hop count is unclear

+ - `peerDependencies["@capacitor/core"]` lags the app's Capacitor version

+ - Users of the plugin report it breaks on Capacitor 8.5 scene-based apps or on Capacitor 9

+ Do not use:

+ - App projects -> `capacitor-app-upgrades`

+ - Adding SPM to a plugin -> `capacitor-plugin-spm-support`

+ - Cordova plugin to Capacitor plugin conversion -> `cordova-to-capacitor`

## Live Project Snapshot

Plugin and Capacitor package snapshot:

!`node -e "const fs=require('fs');if(!fs.existsSync('package.json'))process.exit(0);const pkg=JSON.parse(fs.readFileSync('package.json','utf8'));const out=['package.name='+(pkg.name||''),'package.version='+(pkg.version||'')];for(const section of ['peerDependencies','dependencies','devDependencies']){for(const [name,version] of Object.entries(pkg[section]||{})){if(name.startsWith('@capacitor/'))out.push(section+'.'+name+'='+version)}}console.log(out.join('\n'))"`

Example and native project paths:

!`find . -maxdepth 3 \( -path './example-app' -o -path './ios' -o -path './android' -o -name 'capacitor.config.json' -o -name 'capacitor.config.ts' -o -name 'capacitor.config.js' \)`

- ## Procedures

- ### Step 1: Detect the Current Version

- Start from the injected snapshot above, then inspect `package.json` if the Capacitor ranges or package version need confirmation.

- Ask the user to confirm the exact target major version before proceeding.

- ### Step 2: Upgrade Sequentially

- For each major jump:

- 1. Update `@capacitor/*` peer dependencies and native bridge code as needed.

- 2. Adjust iOS and Android native project settings for the target Capacitor version.

- 3. Run `npm install`.

- 4. Run `npx cap sync` from the example or test app directory that contains `capacitor.config.*`, or rebuild that app with the repository's documented command.

- 5. Verify the plugin API still works in the example app or test app.

- Do not skip intermediate major versions.

+ ## Version Map (October 2026)

- ### Step 3: Check Plugin-Specific Surface Area

+ | Hop | Skill | Notes |

+ |---|---|---|

+ | 4 -> 5 | `capacitor-plugin-upgrade-v4-to-v5` | |

+ | 5 -> 6 | `capacitor-plugin-upgrade-v5-to-v6` | |

+ | 6 -> 7 | `capacitor-plugin-upgrade-v6-to-v7` | |

+ | 7 -> 8 | `capacitor-plugin-upgrade-v7-to-v8` | iOS 15, SDK 36, AGP 8.13 |

+ | 8.5 lifecycle | `capacitor-uiscene-migration` (`references/plugin-audit.md`) | Audit only; no version bump needed if the plugin follows the one-release rules |

+ | 8 -> 9 | `capacitor-plugin-upgrade-v8-to-v9` | `npx @capacitor/plugin-migration-v8-to-v9@latest`, iOS 16, SDK 37, AGP 9.2.1, API removals |

- Review these plugin areas carefully:

+ Capacitor 9 is a prerelease (`next` tag, 9.0.0-alpha.x). Use `next` / `>=9.0.0-alpha.6` ranges until GA; consider publishing the plugin's v9 release under the npm `next` tag too. Ask the user before dropping support for the current stable major.

- - TypeScript definitions and exported names

- - Native method signatures and return payloads

- - Android namespace, Gradle settings, and Java compatibility

- - iOS deployment target, Swift syntax, and bridge registration

- - Documentation snippets and README install steps

+ ## Procedure

- ### Step 4: Final Verification

+ 1. **Detect** the supported range (peer dependency, `Package.swift` `capacitor-swift-pm` requirement, podspec `Capacitor` dependency, `android/build.gradle` defaults). Confirm the target major with the user.

+ 2. **Plan hops**, one major at a time. When crossing 8 -> 9, run the UIScene plugin audit as part of the hop. Example: 7 -> 9 = 7->8, UIScene audit, 8->9.

+ 3. **Per hop:** clean git tree, load the hop skill, run its official migrator first (`npx @capacitor/plugin-migration-v<from>-to-v<to>@latest` where the skill names one), review the diff, finish the manual checklist, then verify (step 5) before the next hop.

+ 4. **Surface area** to re-check every hop: TypeScript definitions and exported names, native method signatures and payloads, Android namespace and Java/Kotlin toolchain, iOS deployment target in podspec and `Package.swift` (keep both), README install and compatibility table.

+ 5. **Verify** in the plugin root and in the example app.

- Check whether `npm run verify` exists in `package.json` or the repository scripts.

+ ## Verification

- If it exists, run:

+ If `npm run verify` exists, run it. Otherwise:

```bash

- npm run verify

+ npm run build

+ npm test --if-present

+ cd android && ./gradlew clean build && cd ..

+ xcodebuild -scheme <PluginScheme> -destination 'generic/platform=iOS Simulator' build # find it with xcodebuild -list

+ cd example-app && npm install && npx cap sync && npx cap run ios && npx cap run android

```

- If it does not exist, run the repository's documented fallback checks instead:

- - `npm run build`

- - `npm test`

- - `npx cap sync` from the example/test app directory

- - the example app or test app build for every shipped platform

- Run the sync and build commands from the plugin's example/test app directory, not the plugin root.

+ Run `npx cap sync` and native runs from the example/test app, not the plugin root. Exercise each public method on every shipped platform.

## Error Handling

- - If a migration tool exists for the target version, use it first and then review the diff manually.

- - If the example app breaks, fix the plugin API or native wiring before publishing the version bump.

- - If a plugin supports multiple platforms, verify every platform that ships in the package.

+ - Migrator for the hop fails or misses files -> finish manually from the hop skill before the next major.

+ - Example app breaks -> fix plugin API or native wiring before publishing.

+ - Consumers on CocoaPods and SPM both report issues -> check podspec and `Package.swift` declare the same platform and Capacitor range.

+ - Plugin breaks only in scene-based apps -> AppDelegate-method or `tmpWindow` assumptions; see `capacitor-uiscene-migration`.