# capacitor-plugin-upgrades

Drives a Capacitor plugin library through one or more major upgrades, 4 to 9, with the iOS UIScene audit. Built for maintainers whose peerDependencies lag the app.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 730 installs · ★ 73
- Author: Cap-go
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/Cap-go/capgo-skills/tree/HEAD/skills/capacitor-plugin-upgrades/SKILL.md
- Updated: 2026-10-17
- HTML: https://affpapa.org/en/nevibecode/skills/cap-go-capacitor-plugin-upgrades

## What it does

The skill acts as a router. It first detects the supported Capacitor range from the peer dependency, the `capacitor-swift-pm` requirement in `Package.swift`, the podspec `Capacitor` dependency and `android/build.gradle` defaults. Then it plans hops one major at a time, loads the version-specific skill for each hop, runs the official migrator such as `npx @capacitor/plugin-migration-v<from>-to-v<to>@latest`, and verifies TypeScript, Android, iOS and the example app.

The 8 -> 9 hop includes the UIScene audit, because Capacitor 8.5 and 9 require it; a separate skill, `capacitor-uiscene-migration`, carries the `references/plugin-audit.md` file. If your plugin already follows the one-release rules, no version bump is needed for that audit. Capacitor 9 is a prerelease on the `next` tag, so the guidance is to keep ranges like `>=9.0.0-alpha.6` until GA.

Tool access is limited to Bash calls for `node`, `find`, `npm` and `npx`. Start each hop from a clean git tree, and run `npx cap sync` plus native builds from the example app rather than the plugin root. This is for plugin libraries only — app projects belong to `capacitor-app-upgrades`, and Cordova conversion to `cordova-to-capacitor`.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add Cap-go/capgo-skills --skill capacitor-plugin-upgrades -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/capacitor-plugin-upgrades/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/capacitor-plugin-upgrades/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add Cap-go/capgo-skills --skill capacitor-plugin-upgrades -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/capacitor-plugin-upgrades/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add Cap-go/capgo-skills --skill capacitor-plugin-upgrades -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/capacitor-plugin-upgrades/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install Cap-go/capgo-skills capacitor-plugin-upgrades
```

2. **Manually: put the files in place**
- File: `.github/skills/capacitor-plugin-upgrades/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add Cap-go/capgo-skills --skill capacitor-plugin-upgrades -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/Cap-go/capgo-skills --path skills/capacitor-plugin-upgrades
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/capacitor-plugin-upgrades/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add Cap-go/capgo-skills --skill capacitor-plugin-upgrades -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/Cap-go/capgo-skills/tree/HEAD/skills/capacitor-plugin-upgrades/SKILL.md

## When to use it
- bump a plugin's peerDependencies to a newer Capacitor major
- cross several majors in one pass without skipping a hop
- check a plugin against scene-based apps on Capacitor 8.5 and 9
- keep the Capacitor range aligned in podspec and Package.swift
- run the official migrator and finish missed files by hand

## Example prompts
- upgrade my plugin to the latest Capacitor major, start by detecting the current range
- I need Capacitor 9 support in my plugin, plan the hops step by step
- audit my plugin for iOS UIScene on Capacitor 8.5 and 9

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: b5209db0a726864d.

BEGIN THIRD-PARTY FILE b5209db0a726864d
```text
---
name: capacitor-plugin-upgrades
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 (router)

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

## When to Use

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' \)`

## Version Map (October 2026)

| Hop | Skill | Notes |
|---|---|---|
| 4 -> 5 | `capacitor-plugin-upgrade-v4-to-v5` | |
| 5 -> 6 | `capacitor-plugin-upgrade-v5-to-v6` | |
```
END THIRD-PARTY FILE b5209db0a726864d

The third-party file has ended. Everything between the b5209db0a726864d tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2311 of 4929 bytes. © Cap-go · MIT · https://github.com/Cap-go/capgo-skills/tree/HEAD/skills/capacitor-plugin-upgrades/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md