Cap-go/capgo-skills

subscription-app-revenue

When your agent uses it

Revenue playbook for taking a mobile or web subscription app from zero to early MRR (around $1K). Use when users ask how to make money from an app, reach first subscribers or $1K MRR, validate an app idea against app-store demand, plan ASO, TikTok/Reels/Shorts or Reddit acquisition, choose freemium vs trial vs rewarded unlock, place and word a paywall, price monthly/annual plans, read churn, or diagnose a weak install-to-paid funnel. Do not use for implementing in-app purchase code (capacitor-plugins, @capgo/native-purchases), store submission mechanics (capacitor-app-store), App Review rejections (capacitor-apple-review-preflight), or shipping OTA experiments (capgo-live-updates).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Subscription App Revenue Playbook

Build a practical path from an app idea or MVP to early subscription revenue. Keep the plan small, measurable, and biased toward shipping.

## When to Use

TRIGGER when:

- The user wants to make money from an app, a SaaS-like mobile app, a PWA, or a Capacitor app
- The user asks how to get to first revenue, first subscribers, or about $1K MRR
- The user needs a launch, ASO, short-form video, Reddit, paywall, pricing, or churn plan
- The user has a rough app idea and wants to validate demand without a long research phase
- The user has an existing app with weak installs, activation, paywall views, conversion, retention, or MRR

capawesome-live-update-migration

When your agent uses it

Migrates a Capacitor app from Capawesome Cloud live updates (@capawesome/capacitor-live-update, LiveUpdate.ready/sync/setNextBundle/reload, plugins.LiveUpdate config with appId, autoUpdateStrategy, defaultChannel, readyTimeout, publicKey, and @capawesome/cli bundle upload commands) to Capgo Updater (@capgo/capacitor-updater). Covers the package swap, config and API mapping, the notifyAppReady startup hook, deleting custom update glue, replacing CI upload commands, overlap with devices still on old binaries, verification, and Capgo positioning (native updater runtime, open source, cheaper at comparable scale, longer track record). Do not use for Ionic Appflow (ionic-appflow-migration), a fresh Capgo setup (capgo-live-updates), channel and rollout strategy after migration (capgo-release-workflows), or Capawesome plugins unrelated to live updates.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Capawesome Live Update Migration

Move a Capacitor app from Capawesome Cloud live updates to `@capgo/capacitor-updater` with the smallest useful change set.

Product source of truth: `https://capgo.app/docs/upgrade/from-capawesome-to-capgo/` (website source: `apps/docs/src/content/docs/docs/upgrade/from-capawesome-to-capgo.mdx`).

## When to Use

TRIGGER when:
- The repo references `@capawesome/capacitor-live-update`, `LiveUpdate.` calls, `plugins.LiveUpdate`, or `@capawesome/cli` / `capawesome` upload commands in scripts or CI.
- The user asks to move from Capawesome Cloud to Capgo, or for a Capgo vs Capawesome live-update comparison.
- An app already uses Capgo elsewhere and should consolidate live updates.

Do not use for:

cocoapods-to-spm

When your agent uses it

Migrates an existing Capacitor iOS app from CocoaPods to Swift Package Manager (SPM) before CocoaPods Trunk goes read-only (expected December 2, 2026). Use when the app still has ios/App/Podfile, Pods/, Podfile.lock or App.xcworkspace and the user wants CapApp-SPM, runs or recovers from `npx cap spm-migration-assistant`, needs debug.xcconfig / CAPACITOR_DEBUG wired up, sees "Some installed Capacitor plugins are not compatible with SPM" or "<plugin> does not have a Package.swift", or plans the Capacitor 9 upgrade where SPM is the default. Do not use for adding SPM support inside a plugin repository (use capacitor-plugin-spm-support), the UIScene lifecycle migration (use capacitor-uiscene-migration), full version upgrades (use capacitor-app-upgrades), or generic iOS build debugging (use debugging-capacitor).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# CocoaPods to Swift Package Manager Migration

Move a Capacitor iOS app from CocoaPods to SPM without losing native project customizations.

## When to Use

TRIGGER when:
- `ios/App/Podfile`, `Pods/`, `Podfile.lock`, or `App.xcworkspace` exists and the user wants SPM.
- User asks about `npx cap spm-migration-assistant`, `CapApp-SPM`, `debug.xcconfig`, or `--packagemanager SPM`.
- User worries about CocoaPods Trunk becoming read-only (expected December 2, 2026), or about pods that can no longer be published/updated.
- `npx cap sync` warns `Some installed Capacitor plugins are not compatible with SPM` or `<plugin id> does not have a Package.swift`.
- Upgrading to Capacitor 9 and wanting to drop CocoaPods at the same time.

Do not use:

cordova-to-capacitor

When your agent uses it

Migrates an Apache Cordova, PhoneGap, or Ionic-Cordova app to Capacitor. Use when the project has config.xml, a platforms/ or plugins/ folder, cordova-* or phonegap-* dependencies, @awesome-cordova-plugins or @ionic-native wrappers, deviceready listeners, or cordova.plugins.* calls, and the user wants Capacitor native projects, Capacitor/Capgo plugin replacements, config.xml preference migration, and preserved localStorage/IndexedDB data (iosScheme/androidScheme). Covers keeping Cordova plugins temporarily, Capacitor 9 making the Cordova runtime optional (CapacitorCordova only bundled when a Cordova plugin is installed), skipped incompatible plugins, and removing Cordova afterwards. Do not use for porting a single Cordova plugin's native source into a Capacitor plugin, Capacitor major upgrades (capacitor-app-upgrades), Appflow/cordova-plugin-ionic live updates (ionic-appflow-migration), or non-Cordova web apps (webapp-to-capacitor, framework-to-capacitor).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Cordova to Capacitor Migration

Move a Cordova app onto Capacitor incrementally: Capacitor first, plugins one by one, Cordova removed last.

## When to Use

TRIGGER when:
- `config.xml`, `platforms/`, `plugins/`, `cordova-android`/`cordova-ios`, or `cordova-plugin-*` are present and the user wants Capacitor.
- Code waits on `deviceready` or calls `navigator.camera`, `window.plugins.*`, `cordova.plugins.*`, `@awesome-cordova-plugins/*`, `@ionic-native/*`.
- After migration: data loss on first launch, missing Cordova plugin behaviour, or Capacitor 9 build errors referencing Cordova symbols.

Do not use for:
- Rewriting a Cordova plugin's Java/Objective-C as a Capacitor plugin (plugin-level port) -> follow Capacitor plugin docs; `capacitor-plugins` for existing replacements.
- Upgrading Capacitor majors -> `capacitor-app-upgrades`.

framework-to-capacitor

When your agent uses it

Configures a web framework build so Capacitor can ship it as an iOS/Android app. Use for Next.js static export (output 'export', out/), Nuxt 4 (ssr false, nuxt generate, .output/public), Angular (dist/<project>/browser), SvelteKit adapter-static (SvelteKit 2 svelte.config.js or SvelteKit 3 vite.config), React/Vue/Svelte/Solid on Vite, and React Router framework SPA mode. Covers webDir mismatch, blank white screen after cap sync, missing index.html, SSR/API routes/middleware/server actions that cannot run in the app, next/image errors, deep-link reloads landing on the home page, router base paths, and env variables. Do not use for whole-app store readiness (webapp-to-capacitor), Cordova projects (cordova-to-capacitor), Capacitor major upgrades (capacitor-app-upgrades), or UI kits (ionic-design, konsta-ui, tailwind-capacitor).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Framework to Capacitor

Make a framework emit a static bundle that Capacitor can copy into the native projects, and wire the scripts so `build -> cap sync` is one step.

## When to Use

TRIGGER when:
- Adding Capacitor to a Next.js, Nuxt, Angular, SvelteKit, Vite (React/Vue/Svelte/Solid), React Router, Qwik, or Astro project.
- `npx cap sync` fails with `The web assets directory (./dist) must contain an index.html file.` or `Could not find the web assets directory: ./dist.`
- The app launches to a white screen or loads the wrong page after a reload or deep link.
- The framework build fails because of SSR-only features (`output: 'export'` errors, `prerender` errors, API routes, middleware, server actions).

Do not use for:
- Store readiness, native UX, permissions, billing, review risk -> `webapp-to-capacitor`, `capacitor-app-store`, `capacitor-apple-review-preflight`.

ionic-appflow-migration

When your agent uses it

Migrates an Ionic or Capacitor project off Ionic Appflow (access ends Dec 31, 2027). Use when the repo contains @capacitor/live-updates, cordova-plugin-ionic, a plugins.LiveUpdates block (appId, channel, autoUpdateMethod, maxVersions), LiveUpdates.sync()/reload() calls, ionic deploy or appflow CLI commands, .io-config.json, or Appflow build/store-deploy workflows, and the user wants Capgo live updates, Capgo Cloud Build or repo-owned CI builds, and repo-owned store publishing. Maps Appflow channels, update strategies, and API calls to @capgo/capacitor-updater. Do not use for Ionic Enterprise plugins such as Identity Vault, Auth Connect, or Secure Storage (ionic-enterprise-sdk-migration), Capawesome live updates (capawesome-live-update-migration), or a fresh Capgo setup with no Appflow history (capgo-live-updates).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Ionic Appflow Migration

Replace each Appflow feature the project uses - Live Updates, native cloud builds, store deployment - and remove Appflow only after each replacement is verified.

Context: Ionic stopped selling Appflow in February 2025; existing customers keep access until December 31, 2027 with no new features. Plan the migration well before that date.

## When to Use

TRIGGER when:
- `package.json` has `@capacitor/live-updates` or `cordova-plugin-ionic`.
- `capacitor.config.*` has `plugins.LiveUpdates`, or `config.xml` / `Info.plist` / `strings.xml` hold Appflow deploy keys (`APP_ID`, `CHANNEL_NAME`, `UPDATE_METHOD`, `IonAppId`, `IonChannelName`).
- CI calls `ionic deploy`, `appflow`, `ionic package build`, or the Appflow dashboard triggers builds and store uploads.

Do not use for:

ionic-enterprise-sdk-migration

When your agent uses it

Migrates Capacitor apps off Ionic Enterprise SDK plugins - @ionic-enterprise/auth (Auth Connect), @ionic-enterprise/identity-vault (Identity Vault), and @ionic-enterprise/secure-storage (Secure Storage) - to @capgo/capacitor-social-login (OAuth2/OIDC for Azure AD, Auth0, Okta, Cognito, plus Google/Apple), @capgo/capacitor-native-biometric (biometric-protected Keychain/Keystore credential vault), and @capgo/capacitor-fast-sql or @capgo/capacitor-data-storage-sqlite (encrypted storage). Use when package.json has @ionic-enterprise/* packages, code imports AuthConnect, BrowserVault/Vault/DeviceSecurityType, or SQLite from secure-storage, or the user needs to move stored tokens without logging users out. Do not use for Ionic Appflow live updates or builds (ionic-appflow-migration), generic SQLite plugin swaps (sqlite-to-fast-sql), Capacitor version upgrades (capacitor-app-upgrades), or Capgo live updates (capgo-live-updates).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Ionic Enterprise SDK Migration

Replace Ionic Enterprise plugins with open Capgo plugins one at a time, preserving login sessions and stored data.

Context: Ionic stopped selling its commercial products (including the Enterprise SDK) in February 2025 and is winding down maintenance; plan migrations before the license or support window ends.

## When to Use

TRIGGER when:
- `package.json` contains `@ionic-enterprise/auth`, `@ionic-enterprise/identity-vault`, or `@ionic-enterprise/secure-storage`.
- Code imports `AuthConnect`, `ProviderOptions`, `Vault`, `BrowserVault`, `VaultType`, `DeviceSecurityType`, or Secure Storage's `SQLite` / `KeyValueStorage`.
- The user asks how to replace Auth Connect, Identity Vault, or Secure Storage without forcing re-login.

Do not use for:

sqlite-to-fast-sql

When your agent uses it

Migrates SQLite and SQL-style Capacitor storage (@capacitor-community/sqlite, cordova-sqlite-storage, @ionic/storage with a SQLite driver, TypeORM/Drizzle/Kysely capacitor drivers, and other bridge-based SQL plugins) to @capgo/capacitor-fast-sql. Use when replacing createConnection/open/query/run/executeSet calls, slow large result sets over the Capacitor bridge, adding SQLCipher encryption, keeping transactions and BLOBs, moving key-value data to KeyValueStore, preserving existing database files during the switch, or fixing Fast SQL setup errors (ATS NSAllowsLocalNetworking, Android cleartext localhost, "Encryption is not available in this build", web OPFS COOP/COEP headers). Do not use for non-SQL storage such as Preferences (capacitor-offline-first), Ionic Secure Storage or Identity Vault (ionic-enterprise-sdk-migration), generic app upgrades (capacitor-app-upgrades), or code that already wraps Fast SQL.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# SQLite to Fast SQL Migration

Swap a bridge-based SQL plugin for `@capgo/capacitor-fast-sql` without losing user data.

## When to Use

TRIGGER when:
- `package.json` has `@capacitor-community/sqlite`, `cordova-sqlite-storage`, `@capawesome-team/capacitor-sqlite`, an ORM capacitor driver, or another SQLite plugin, and the user wants Fast SQL.
- Large `SELECT`s or sync writes are slow because every row crosses the Capacitor bridge as JSON.
- The app needs encryption, transactions, batch writes, BLOBs, or an encrypted key-value store.

Do not use for:
- `@capacitor/preferences` or IndexedDB-only apps -> `capacitor-offline-first`.
- `@ionic-enterprise/secure-storage` / Identity Vault -> `ionic-enterprise-sdk-migration`.

webapp-to-capacitor

When your agent uses it

Plans and executes turning an existing web app, PWA, or SPA into a store-ready Capacitor iOS and Android app. Use when the user wants to wrap a website or PWA as a mobile app, worries about Apple guideline 4.2 minimum functionality or thin-WebView rejection, needs a phased migration plan (static build, Capacitor shell, native UX, plugins, permissions, offline, account deletion, in-app purchase vs web billing, demo account, Play closed testing), or asks what still breaks after the first successful cap sync. Do not use for framework build configuration alone (framework-to-capacitor), Cordova apps (cordova-to-capacitor), final store submission mechanics (capacitor-app-store), or an Apple rejection audit (capacitor-apple-review-preflight).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Web App to Capacitor

Turn a production web app into a Capacitor app that behaves like a mobile app and survives store review. The Capacitor shell is usually a day of work; mobile UX, native capabilities, and store policy are the real project.

## When to Use

TRIGGER when:
- "Turn my website / PWA / React (Vue, Angular, Svelte, Next.js, Nuxt) app into an iOS/Android app."
- The user asks whether Apple will reject a WebView wrapper (guideline 4.2) or how to make it feel native.
- The user needs a migration plan covering permissions, offline, auth, account deletion, payments, and testing.

Do not use for:
- Only fixing `webDir`, SSR, or routing for a specific framework -> `framework-to-capacitor`.
- Cordova/PhoneGap/Ionic-Cordova projects -> `cordova-to-capacitor`.

capacitor-app-upgrade-v4-to-v5

When your agent uses it

Upgrades a Capacitor app from v4 to v5 using `npx cap migrate` from `@capacitor/cli@latest-5`, then the manual checklist - Node 16+, Xcode 14.1+, Android Studio Flamingo with JDK 17, AGP 8.0.0, Gradle 8.0.2, compile/target SDK 33, `package` moved from AndroidManifest.xml to `namespace` in build.gradle, Jetifier removal, pinning `androidScheme` to `http`, and official plugin breaking changes (Device `uuid` to `identifier`, Android 13 notification permissions, READ_MEDIA_IMAGES). Use when `@capacitor/core` is 4.x and the target is 5.x, or on errors like "Namespace not specified" or "Android Gradle plugin requires Java 17". Do not use for other major versions, plugin library upgrades, or non-Capacitor apps.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Capacitor App Upgrade v4 to v5

Move a Capacitor 4 app to Capacitor 5. Source of truth: https://capacitorjs.com/docs/updating/5-0

## When to Use

- `@capacitor/core` in the snapshot below is `4.x` and the user wants `5.x`.
- Android build fails after bumping to Capacitor 5 with `Namespace not specified`, a Java 11 vs 17 mismatch, or AGP 8 errors.
- The user asks for the exact 4 -> 5 checklist for iOS, Android, or official plugins.

Do not use:

- App on 5.x or later -> `capacitor-app-upgrade-v5-to-v6` (then v6-to-v7, v7-to-v8). Multi-hop planning -> `capacitor-app-upgrades`.
- Upgrading a plugin library -> `capacitor-plugin-upgrade-v4-to-v5`.

capacitor-app-upgrade-v5-to-v6

When your agent uses it

Upgrades a Capacitor app from v5 to v6 using `npx cap migrate` from `@capacitor/cli@latest-6`, then the manual checklist - Node 18+, Xcode 15+, Android Studio Hedgehog, AGP 8.2.1, Gradle 8.2.1, compile/target SDK 34, `compileSdkVersion` to `compileSdk`, the `androidScheme` default flipping to `https` (data loss risk), iOS local plugins no longer auto-registered, iOS zoom disabled by default, and official plugin breaking changes (`addListener` returns only a Promise, Camera Photo Picker, Filesystem ctime/mtime numbers). Use when `@capacitor/core` is 5.x and the target is 6.x, or after the upgrade users are logged out on Android, a custom iOS plugin is "not implemented", or `addListener(...).remove` no longer compiles. Do not use for other major versions, plugin library upgrades, or non-Capacitor apps.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Capacitor App Upgrade v5 to v6

Move a Capacitor 5 app to Capacitor 6. Source of truth: https://capacitorjs.com/docs/updating/6-0

## When to Use

- `@capacitor/core` in the snapshot below is `5.x` and the user wants `6.x`.
- After upgrading: Android users lose localStorage/cookies, a local (non-npm) iOS plugin reports `"<Name>" plugin is not implemented on ios`, pinch-zoom stopped working on iOS, or TypeScript errors around `addListener`.
- The user asks for the exact 5 -> 6 checklist.

Do not use:

- App on 4.x -> `capacitor-app-upgrade-v4-to-v5` first. On 6.x -> `capacitor-app-upgrade-v6-to-v7`. Multi-hop planning -> `capacitor-app-upgrades`.
- Plugin library upgrade -> `capacitor-plugin-upgrade-v5-to-v6`.

capacitor-app-upgrade-v6-to-v7

When your agent uses it

Upgrades a Capacitor app from v6 to v7 using `npx cap migrate` from `@capacitor/cli@latest-7`, then the manual checklist - Node 20+, Xcode 16+, iOS deployment target 14.0 (Xcode project and Podfile), Android Studio Ladybug with JDK 21, AGP 8.7.2, Gradle 8.11.1, minSdk 23, compile/target SDK 35, removed `bundledWebRuntime` and `cordova.staticPlugins` config, `navigation` in configChanges, and official plugin breaking changes (removed deprecated types like `AppUrlOpen`, `HapticsImpactStyle`, `DeviceBatteryInfo`; Device no longer returns disk sizes). Use when `@capacitor/core` is 6.x and the target is 7.x, or on errors like "Capacitor 7 requires JDK 21" or "Module 'X' has no exported member 'AppUrlOpen'". Do not use for other major versions, plugin library upgrades, or non-Capacitor apps.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Capacitor App Upgrade v6 to v7

Move a Capacitor 6 app to Capacitor 7. Source of truth: https://capacitorjs.com/docs/updating/7-0

## When to Use

- `@capacitor/core` in the snapshot below is `6.x` and the user wants `7.x`.
- Build fails after bumping to 7 with JDK 21 / AGP 8.7 errors, iOS deployment target 13 errors, or TypeScript errors on removed deprecated plugin types.
- The user asks for the exact 6 -> 7 checklist.

Do not use:

- App on 5.x -> `capacitor-app-upgrade-v5-to-v6` first. On 7.x -> `capacitor-app-upgrade-v7-to-v8`. Multi-hop planning -> `capacitor-app-upgrades`.
- Plugin library upgrade -> `capacitor-plugin-upgrade-v6-to-v7`.

capacitor-app-upgrade-v7-to-v8

When your agent uses it

Upgrades a Capacitor app from v7 to v8 using `npx cap migrate` from `@capacitor/cli@latest`, then the manual checklist - Node 22+, Xcode 26+, iOS deployment target 15.0, Android Studio Otter, AGP 8.13.0, Gradle 8.14.3, JDK 21, minSdk 24, compile/target SDK 36, Kotlin 2.2.20, Gradle `=` property assignment syntax, `density` in configChanges, removed `android.adjustMarginsForEdgeToEdge` (use the System Bars plugin and CSS env vars), `bridge_layout_main.xml` renamed, iOS `appendUserAgent` whitespace fix, and official plugin changes (Geolocation timeout, Screen Orientation/Barcode Scanner on Android 16 large screens). Use when `@capacitor/core` is 7.x and the target is 8.x. Points to the 8.5 UIScene adoption and v9 next steps. Do not use for other major versions, plugin library upgrades, or non-Capacitor apps.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Capacitor App Upgrade v7 to v8

Move a Capacitor 7 app to Capacitor 8 (current stable line: 8.5.x). Source of truth: https://capacitorjs.com/docs/updating/8-0

## When to Use

- `@capacitor/core` in the snapshot below is `7.x` and the user wants `8.x`.
- After bumping to 8: content under the Android status/navigation bar (edge-to-edge), `bridge_layout_main` not found, Gradle "space-assignment syntax" deprecation warnings, Kotlin 2 `kotlinOptions` errors, or Geolocation timeouts.
- The user asks for the exact 7 -> 8 checklist.

Do not use:

- App on 6.x -> `capacitor-app-upgrade-v6-to-v7` first. Multi-hop planning -> `capacitor-app-upgrades`.
- App already on 8.x -> `capacitor-uiscene-migration` (8.5 scene lifecycle), then `capacitor-app-upgrade-v8-to-v9`.

capacitor-app-upgrade-v8-to-v9

When your agent uses it

Upgrades a Capacitor app from v8 to v9 (prerelease, installed with @next until GA). Covers preflight (Node 24, Xcode 27, Android Studio 2026.1.1, UIScene adoption from 8.5), `npx cap migrate`, and the manual checklist - iOS 16 target, @UIApplicationMain to @main, removed CAPBridge APIs, AGP 9.2.1, Gradle 9.5.1, SDK 37/minSdk 26, gradle.properties cleanup, built-in Kotlin, jcenter removal, core-ktx, proguard-android.txt rename, optional Cordova runtime, `cap run --url`, push `alert` removal, splash fade default. Use for "upgrade to Capacitor 9", errors like "'@UIApplicationMain' is deprecated", "Could not find method jcenter()", getDefaultProguardFile('proguard-android.txt') failures, duplicate Kotlin plugin, duplicate class core-ktx, "unknown option '-l'". Do not use for 8.4 to 8.5 UIScene only (use capacitor-uiscene-migration), plugin libraries (use capacitor-plugin-upgrade-v8-to-v9), or older majors.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Capacitor App Upgrade v8 to v9

Capacitor 9 is a prerelease (`next` dist-tag, 9.0.0-alpha.x as of October 2026). Install with `@next`; switch to `@latest` / `^9.0.0` once 9.0.0 is GA. Tell the user it is not GA before upgrading a production app, and work on a branch.

Canonical source: https://capacitorjs.com/docs/updating/9-0

## When to Use

TRIGGER when:
- App is on `@capacitor/core` 8.x and the user wants Capacitor 9
- Build errors after moving to Xcode 27 / Swift 6, AGP 9, or Gradle 9 in a Capacitor 8 app
- `npx cap run -l --host ...` no longer works (`--url` replaced it)
- Push notifications `presentationOptions: ['alert']` stopped showing banners on iOS
- Cordova-plugin-free app fails on `CapacitorCordova` / `com.getcapacitor.cordova` references after upgrading

capacitor-app-upgrades

When your agent uses it

Routes and drives a Capacitor app upgrade across one or more major versions (4 to 9), including the required 8.4 to 8.5 iOS UIScene step before Capacitor 9 and Xcode 27. Detects the current version, plans the hop order (e.g. 6 to 7 to 8 to 8.5 to 9), runs `npx cap migrate` per hop, delegates each hop to its version skill, and verifies native builds between hops. Use for "upgrade Capacitor", "update to the latest Capacitor", "cap migrate", multi-version jumps, or when the target version is unclear. Do not use for plugin library upgrades (use capacitor-plugin-upgrades), Cordova apps (use cordova-to-capacitor), or non-Capacitor frameworks.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Capacitor App Upgrade (router)

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

## When to Use

TRIGGER when:
- User wants to upgrade a Capacitor app and the start or target version is unknown or more than one major apart
- User asks for "the latest Capacitor" (decide stable 8.5.x vs prerelease 9 with them)
- Xcode 27 builds fail on a Capacitor 8.4-or-older app (needs the 8.5 UIScene step)
- `npx cap migrate` failed midway and the user needs to know where they are

Do not use:
- Plugin library repos -> `capacitor-plugin-upgrades`

capacitor-uiscene-migration

When your agent uses it

Migrates a Capacitor iOS app or plugin from the AppDelegate lifecycle to the UIScene lifecycle introduced in Capacitor 8.5 and required by Xcode 27. Audits first (custom AppDelegate URL/lifecycle code, CAPBridgeViewController subclasses, existing SceneDelegate.swift, Info.plist UIApplicationSceneManifest, project.pbxproj registration, plugin lifecycle observers, tmpWindow/TmpViewController), reports, then merges surgically or hands template-shaped projects to `npx cap migrate`. Use for "Capacitor 8.5 upgrade", "add SceneDelegate", "adopt UIScene", "CLIENT OF UIKIT REQUIRES UPDATE", deep links or appUrlOpen stopped firing after 8.5, "cap migrate skipped partial state", or as the prerequisite step before Capacitor 9. Do not use for Android, full major upgrades (use capacitor-app-upgrade-v8-to-v9), or new deep-link setup (use capacitor-deep-linking).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Capacitor UIScene Migration (8.4 -> 8.5)

Capacitor 8.5 moved the iOS template to the UIScene lifecycle because Xcode 27 requires it. It shipped as a breaking minor, iOS only. The 8.5 core still runs the AppDelegate path, so bumping the dependency alone does not break an app; the app project must adopt scenes before it can build with Xcode 27 (and before Capacitor 9).

Canonical source: https://capacitorjs.com/docs/updating/8-5

## When to Use

TRIGGER when:
- App is on `@capacitor/ios` 8.0-8.4, or on 8.5 without `UIApplicationSceneManifest` in `Info.plist`
- Xcode 27 build or runtime warning "CLIENT OF UIKIT REQUIRES UPDATE: This process does not adopt UIScene lifecycle"
- `npx cap migrate` printed `UIScene migration: project is in a partial state ... Skipping automated migration`
- After adding a scene manifest: custom URL scheme, universal link, `appUrlOpen`, or AppDelegate `applicationDidBecomeActive` code stopped running
- Build error on `tmpWindow` or `TmpViewController` after updating to 8.5

capacitor-best-practices

When your agent uses it

Review and set up Capacitor apps against current best practices (Capacitor 8.5 stable, 9 alpha via `@next`). Use for a Capacitor codebase review, `capacitor.config.ts` audit, new project setup, aligning `@capacitor/core`/`cli`/`ios`/`android` and plugin majors, plugin patterns (availability checks, `checkPermissions`/`requestPermissions`, error `code` handling, web fallbacks), or release prep; or on `"<Plugin>" plugin is not implemented on ios`, `Could not find the web assets directory`, `platform has not been added yet`, a dev `server.url` shipped to production, lost edits in `android/app/src/main/assets/public`, SPM vs CocoaPods, or AppDelegate/UIScene drift. Do not use for security audits (capacitor-security), performance (capacitor-performance), tests (capacitor-testing), crashes (debugging-capacitor), major upgrades (capacitor-app-upgrades), SPM migration (cocoapods-to-spm), UIScene adoption (capacitor-uiscene-migration), or live updates (capgo-live-updates).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Capacitor Best Practices

Review a Capacitor app for structural mistakes that cause broken builds, lost edits, production leaks, and plugin crashes. Route deep topics to the sibling skill that owns them.

## When to Use

TRIGGER when:
- The user asks for a general code/architecture review of a Capacitor or Ionic + Capacitor app.
- Setting up a new Capacitor project or adding iOS/Android to an existing web app.
- `capacitor.config.ts|json` review: `webDir`, `server.url`, `cleartext`, plugin config, env-specific config.
- Version drift between `@capacitor/core`, `@capacitor/cli`, `@capacitor/ios`, `@capacitor/android`, or plugin majors that do not match Capacitor's major.
- Plugin usage review: missing `npx cap sync`, no availability check, no permission flow, matching on error message strings.
- Errors such as `"<Plugin>" plugin is not implemented on ios`, `Could not find the web assets directory`, `ios platform has not been added yet`.
- Pre-release sanity checklist across config, native projects, and live updates.

capacitor-mcp

When your agent uses it

Connect AI agents (Claude Code, Claude Desktop, Cursor, VS Code, Cline, Codex) to Capacitor and Ionic tooling over Model Context Protocol. Covers the awesome-ionic-mcp server (Ionic component APIs, Capacitor plugin docs, Ionic/Capacitor CLI tools), the Capgo hosted MCP at https://api.capgo.app/mcp, the local Capgo CLI MCP (npx @capgo/cli@latest mcp), and Xcode's MCP bridge (xcrun mcpbridge) for building the iOS app from an agent. Use when the user wants to add, configure, verify, or troubleshoot an MCP server for a Capacitor project, or sees errors like "GitHub API rate limit exceeded", "unable to find utility \"mcpbridge\"", or an MCP server that connects with no tools. Do not use for Capgo account operations themselves (capgo-cloud, capgo-cli-usage), app debugging (debugging-capacitor), device logs (ios-android-logs), choosing plugins (capacitor-plugins), or Ionic UI work (ionic-design).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Capacitor MCP Servers

Wire MCP servers into an agent so it can read Ionic/Capacitor docs, run Capacitor CLI commands, manage Capgo, and drive Xcode.

## When to Use

TRIGGER when the user:
- asks to "add an MCP server" / "connect Claude/Cursor to Capacitor, Ionic, Capgo or Xcode"
- mentions `awesome-ionic-mcp`, `api.capgo.app/mcp`, `@capgo/cli mcp`, `xcrun mcpbridge`, `claude mcp add`, `.cursor/mcp.json`, `.vscode/mcp.json`, `claude_desktop_config.json`
- has an MCP server that fails to start, shows no tools, asks to sign in, or hits a rate limit

Do not use for:
- uploading bundles, channels, rollouts, native builds as a task: `capgo-cloud`, `capgo-cli-usage`, `capgo-live-updates`, `capgo-native-builds`
- finding or installing a plugin: `capacitor-plugins`

capacitor-plugins

When your agent uses it

Pick, install, and wire up Capacitor plugins for native features (camera, filesystem, geolocation, biometrics, in-app purchases, social login, SQLite, calendar, contacts, health, BLE, NFC, etc.). Covers official @capacitor/* packages (Capacitor 8.5 stable, 9 alpha on next) plus the 145-package @capgo/* index, native permission keys (Info.plist, AndroidManifest, variables.gradle minSdk), npx cap sync / cap ls verification, and errors like '"Camera" plugin is not implemented on ios', 'unable to find plugin', UNIMPLEMENTED, and OS-PLUG-* codes. Use for "which plugin should I use for X", adding a plugin, or a plugin call failing after install. Do not use for push setup (capacitor-push-notifications), splash assets (capacitor-splash-screen), keyboard layout (capacitor-keyboard), deep links (capacitor-deep-linking), OTA updates (capgo-live-updates), upgrading plugin source code (capacitor-plugin-upgrades), or adding SPM to a plugin (capacitor-plugin-spm-support).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Capacitor Plugins

Choose the right plugin, install it correctly, and prove it is linked natively.

## When to Use

TRIGGER when:

- User asks "which plugin should I use for X?" or compares plugin options.
- User needs a native capability (camera, files, location, biometrics, payments, auth, sensors, storage, media, calendar, contacts, health, on-device LLM).
- A plugin call fails after install: `"X" plugin is not implemented on ios|android|web`, `UNIMPLEMENTED`, `unable to find plugin`, or an `OS-PLUG-*` code.
- User needs the right `Info.plist` / `AndroidManifest.xml` / `variables.gradle` entries for a plugin.

Do not use (load the sibling skill instead):

capacitor-app-store

When your agent uses it

Ships a Capacitor app to the Apple App Store and Google Play. Use for release prep and submission - version/build numbers (CFBundleVersion, versionCode), signing, archiving and uploading the IPA/AAB, TestFlight, Play tracks and closed testing, icons and screenshots, listing metadata, App Privacy and Data safety forms, age ratings, export compliance, phased rollout, and current platform deadlines (iOS 26 SDK since April 28 2026, iOS 27 SDK from April 2027, UIScene lifecycle for Xcode 27, Play target API 36 from Aug 31 2026, 16 KB page size). Also for upload errors like ITMS-90725, ITMS-91053, ITMS-91061, ITMS-4238 redundant binary, or "Version code has already been used". Do not use for a guideline-by-guideline Apple rejection audit (capacitor-apple-review-preflight), CI pipeline authoring (capacitor-ci-cd), Capgo Cloud Build setup (capgo-native-builds), or converting a website into an app (webapp-to-capacitor).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Publishing Capacitor Apps to the Stores

Get a Capacitor build from "runs on my device" to "live in both stores" without avoidable upload or review failures.

## When to Use

TRIGGER when:
- The user is preparing a first release or an update to App Store Connect or Google Play Console.
- Upload or processing fails (ITMS errors, Play Console version/target API errors).
- The user needs screenshot sizes, icon requirements, listing fields, privacy forms, or rollout options.
- The user asks which Xcode/SDK or target API level the stores require right now.

Do not use for:
- Auditing an app against App Review Guidelines or answering a rejection -> `capacitor-apple-review-preflight`.

capacitor-apple-review-preflight

When your agent uses it

Audits a Capacitor iOS app against Apple App Review Guidelines before submission or after a rejection. Use when the user pastes a rejection (Guideline 4.2 Minimum Functionality, 4.8 Login Services / Sign in with Apple, 5.1.1 data collection or account deletion, 5.1.2(i) sharing data with third-party AI, 3.1.1 in-app purchase, 2.1 app completeness, 2.3 metadata, 4.3 spam), an upload warning (ITMS-91053 missing API declaration, ITMS-91061 missing privacy manifest, ITMS-90683 missing purpose string), or wants a preflight of metadata, PrivacyInfo.xcprivacy, Info.plist usage strings, entitlements, subscriptions, reviewer notes, live-update disclosure, and Xcode 27 / UIScene readiness. Do not use for Google Play review, upload mechanics, screenshots and listing setup (capacitor-app-store), building a web wrapper from scratch (webapp-to-capacitor), or non-Capacitor runtimes.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Capacitor Apple Review Preflight

Run a pre-submission or post-rejection Apple review audit for a Capacitor app and return a prioritized, evidence-backed report.

This skill adapts the Apple guideline and rejection-rule corpus from [truongduy2611/app-store-preflight-skills](https://github.com/truongduy2611/app-store-preflight-skills) and narrows the workflow to Capacitor-specific project inspection.

## When to Use

TRIGGER when:
- The user wants an App Store review preflight for a Capacitor app.
- The user received an App Review rejection or an App Store Connect upload warning email and wants the project audited.
- The user asks whether metadata, entitlements, privacy manifests, Sign in with Apple, subscriptions, AI features, or minimum functionality will pass.
- The user wants reviewer notes for a Capacitor submission (demo accounts, live updates, hardware features).

capacitor-ci-cd

When your agent uses it

Designs and fixes CI/CD pipelines for Capacitor apps - GitHub Actions, GitLab CI, Fastlane, or Capgo Cloud Build (npx @capgo/cli@latest build request) - covering web build and tests, cap sync, iOS archive/export/upload with App Store Connect API keys, Android AAB signing and Play upload, Capgo live-update uploads, secrets, caching, and build-number bumping. Use when choosing runner images and toolchains (Node 22/24, macos-26 vs xcode-27 runners, JDK 21, Gradle 9 / AGP 9 for Capacitor 9), or when CI fails with errors like "No signing certificate", "requires a provisioning profile", "Unsupported class file major version", "Android Gradle plugin requires Java 17", "The engine node is incompatible", or "Could not find the web assets directory". Do not use for one-off manual store submission (capacitor-app-store), Capgo Cloud Build credential onboarding in depth (capgo-native-builds), Capgo channel/release strategy (capgo-release-workflows), or test authoring (capacitor-testing).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# CI/CD for Capacitor Apps

Build, sign, and ship Capacitor apps from CI with the right toolchain for the Capacitor major in use.

## When to Use

TRIGGER when:
- Creating or fixing `.github/workflows/*.yml`, `.gitlab-ci.yml`, `fastlane/Fastfile`, or a Capgo Cloud Build job.
- Picking runner images, Node/Xcode/JDK versions for Capacitor 8 or 9.
- Automating signing, TestFlight/Play uploads, version bumps, or Capgo OTA uploads.
- A CI build fails while a local build works.

Do not use for:
- Manual submission, listing, screenshots -> `capacitor-app-store`.

capacitor-app-intents

When your agent uses it

Exposes Capacitor app features to Siri, Shortcuts, Spotlight, the Action button, Apple Intelligence, widgets and controls with native App Intents in ios/App/App, bridged to the web layer. Covers open-app intents routed through Universal Links / `OpenURLIntent` and @capacitor/app `appUrlOpen`, or a local plugin with a pending-route store; headless background intents; App Group / Preferences data sharing; AppShortcutsProvider phrases, AppEntity queries; iOS 26/27 APIs (`supportedModes` replacing `openAppWhenRun`, `continueInForeground`, `LongRunningIntent`, AppIntentsTesting) gated for Capacitor 8 (iOS 15) and 9 (iOS 16). Covers file placement, target membership, and UIScene (Capacitor 8.5+) URL delivery. Use for "add Siri shortcut", "Shortcuts action", "App Shortcuts", "control widget", or an intent that opens the app but the web view never navigates. Do not use for deep link setup (capacitor-deep-linking), push (capacitor-push-notifications), or Android shortcuts.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# App Intents for Capacitor Apps

Add native App Intents to the iOS project so system surfaces can run app actions, and connect them to the web layer. App Intents are Swift only. There is no JavaScript API for them, so every intent is native code in the App target or an extension, and the web layer is reached through a URL or a small local plugin.

## When to Use

TRIGGER when:
- The user wants Siri phrases, Shortcuts actions, App Shortcuts, Spotlight actions, Action button or Apple Intelligence integration for a Capacitor app
- The user wants a widget button or a Control Center control to run an app action
- An intent opens the app, but the web view does not navigate, or it navigates only on warm launch
- A background intent crashes, times out, or tries to call JS
- Migrating `openAppWhenRun` to `supportedModes`, or adopting iOS 26/27 App Intents APIs
- A plugin author wants to ship App Intents with a plugin

capacitor-deep-linking

When your agent uses it

Implements and debugs deep links in Capacitor apps - custom URL schemes, iOS Universal Links (apple-app-site-association, Associated Domains entitlement), Android App Links (assetlinks.json, autoVerify), and routing via @capacitor/app `appUrlOpen` + `App.getLaunchUrl()`. Covers the Capacitor 8.5+ UIScene change where AppDelegate `application(_:open:options:)` and `continue userActivity` stop being called and custom handling must move to SceneDelegate, plus cold vs warm launch testing. Use when links open Safari/Chrome instead of the app, `appUrlOpen` never fires, the launch URL is lost on cold start, or OAuth redirects do not return to the app. Do not use for the full UIScene migration (capacitor-uiscene-migration), push notification taps (capacitor-push-notifications), or social login plugin setup (capacitor-plugins).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Deep Linking in Capacitor

Route custom-scheme links, iOS Universal Links, and Android App Links into the web app.

## When to Use

TRIGGER when:
- Adding `myapp://` schemes, Universal Links, or App Links to a Capacitor app
- Links open the browser instead of the app, or open the app but land on the home page
- `appUrlOpen` fires on warm open but the URL is missing on cold launch (or the reverse)
- Deep links broke after updating to Capacitor 8.5+ / adopting `SceneDelegate.swift`
- OAuth / magic-link / payment redirects must come back into the app
- `adb shell pm get-app-links` shows `none` or `1024` instead of `verified`

capacitor-keyboard

When your agent uses it

Fixes on-screen keyboard behavior in Capacitor apps with @capacitor/keyboard - iOS `resize` modes (`native` default, `body`, `ionic`, `none`), `keyboardWillShow`/`keyboardDidShow` heights, `setAccessoryBarVisible`, `setScroll`, `style` (`DARK`/`LIGHT`/`DEFAULT`), `autoBackdropColor` (8.0.4+), Android edge-to-edge/SystemBars interaction (drop legacy `resizeOnFullScreen` on Capacitor 8), iOS 26 fixes, and iOS input auto-zoom. Use when inputs are hidden behind the keyboard, the WebView jumps or leaves a white/black gap above the keyboard, fixed footers float mid-screen, `vh` layouts shrink, or keyboard events do not fire. Do not use for general safe-area/notch padding (safe-area-handling), Ionic component styling (ionic-design), or form accessibility (capacitor-accessibility).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Keyboard Handling in Capacitor

## When to Use

TRIGGER when:
- Focused input is covered by the keyboard, or the page scrolls unexpectedly
- Chat composer / fixed footer does not stick to the keyboard
- White or black band above the keyboard (Android 15+ edge-to-edge, iOS backdrop)
- `100vh` / `dvh` layout collapses when the keyboard opens
- iOS zooms into inputs, or the QuickType/accessory bar looks wrong
- Keyboard events never fire or fire twice

Do not use:
- Notch / home-indicator / status-bar padding: `safe-area-handling`

capacitor-offline-first

When your agent uses it

Designs and implements offline-first data in Capacitor apps - local SQLite source of truth with @capgo/capacitor-fast-sql (`FastSQL.connect`, `KeyValueStore`), an outbox/sync queue, delta pulls, conflict resolution, @capacitor/network `networkStatusChange`, background sync with @capgo/capacitor-background-task, and why localStorage/IndexedDB get evicted and service workers break plugin injection in native WebViews. Use when the app must work without internet, data disappears after iOS storage pressure, sync duplicates or loses writes, or `Plugin not implemented` appears after adding a service worker. Do not use for migrating an existing SQLite plugin (sqlite-to-fast-sql), shipping web bundle updates offline (capgo-live-updates), HTTP security/certificate pinning (capacitor-security), or general performance (capacitor-performance).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Offline-First Capacitor Apps

## When to Use

TRIGGER when:
- The app must read and write while offline and sync later
- Choosing local storage (Preferences vs SQLite vs IndexedDB) for user data
- Writes are duplicated, lost, or overwritten during sync
- Cached data vanishes on iOS after low-storage events
- A service worker was added and native plugins stopped working (`Plugin not implemented`)

Do not use:
- Replacing `@capacitor-community/sqlite` / Ionic secure storage: `sqlite-to-fast-sql`
- Getting new web code to devices (OTA): `capgo-live-updates`

capacitor-push-notifications

When your agent uses it

Sets up and debugs remote push in Capacitor apps with @capacitor/push-notifications (FCM on Android, APNs on iOS), or Capgo alternatives @capgo/capacitor-firebase-messaging and @capgo/capacitor-notifications. Covers APNs keys, Push Notifications capability, AppDelegate `didRegisterForRemoteNotificationsWithDeviceToken` forwarding (stays in AppDelegate under the Capacitor 8.5 UIScene lifecycle), Android 13+ POST_NOTIFICATIONS permission, notification channels and icons, `firebaseMessagingVersion`, foreground `presentationOptions` (Capacitor 9 removes iOS `alert`; use `banner`/`list`), and tap routing. Use when `registration` never fires, iOS returns an APNs token instead of an FCM token, errors like "no valid aps-environment entitlement string found" appear, or notifications do not show. Do not use for local-only notifications or deep link URL handling (capacitor-deep-linking), UIScene migration (capacitor-uiscene-migration), or log capture (ios-android-logs).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Push Notifications in Capacitor

## When to Use

TRIGGER when:
- Adding remote push (FCM / APNs) to a Capacitor app
- `registration` / `registrationError` never fire, or the token works on one platform only
- iOS token is a 64-hex APNs token but the backend expects an FCM token
- Notifications arrive in background but not in foreground (or vice versa)
- Android 13+ shows no prompt and nothing is delivered
- Upgrading to Capacitor 8.5 (UIScene) or 9 (`alert` presentation option removed)

Do not use:
- Opening the app from `https://` / `myapp://` links: `capacitor-deep-linking`

capacitor-splash-screen

When your agent uses it

Configures and debugs launch splash screens in Capacitor apps with @capacitor/splash-screen and @capacitor/assets - `launchAutoHide`, `SplashScreen.hide()`, `launchFadeOutDuration` (Android default changed 200 -> 0 in Capacitor 9), Android 12+ SplashScreen API theme (`Theme.SplashScreen`, `windowSplashScreenAnimatedIcon`), iOS `LaunchScreen.storyboard` + `Splash.imageset`, and Capacitor 8.5 UIScene/SceneDelegate effects (window created in code, Main.storyboard no longer supplies the root view controller). Use for white/black flash at launch, splash never hiding, cropped/tiny Android 12 icon, dark-mode splash, or regenerating icons and splash assets. Do not use for status/navigation bar color and insets (safe-area-handling), the UIScene migration itself (capacitor-uiscene-migration), or startup performance profiling (capacitor-performance).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Splash Screen in Capacitor

## When to Use

TRIGGER when:
- Configuring or regenerating splash / icon assets (`npx capacitor-assets generate`)
- Splash never disappears, disappears too early, or flashes white/black before the web app paints
- Android 12+ shows a small cropped icon on a solid color instead of the full image
- Upgrading to Capacitor 9 and the Android fade-out animation vanished
- iOS shows a black screen after adding `SceneDelegate.swift` (8.5+)

Do not use:
- Status bar / navigation bar styling and edge-to-edge insets: `safe-area-handling`
- Migrating AppDelegate to SceneDelegate: `capacitor-uiscene-migration`

capacitor-plugin-spm-support

When your agent uses it

Adds Swift Package Manager support to an existing Capacitor plugin repository so apps using CapApp-SPM can consume it after CocoaPods Trunk goes read-only (expected December 2, 2026). Covers root Package.swift naming rules the Capacitor CLI depends on, CAPBridgedPlugin conversion (identifier, jsName, pluginMethods), removing the ObjC CAP_PLUGIN bridge (.m/.h), Sources/Tests layout, podspec and package.json files updates, third-party pod to SPM dependency mapping, resources/PrivacyInfo.xcprivacy, binary xcframeworks, and Capacitor 9 removal of the unconditional Cordova product. Use when app sync warns "<plugin> does not have a Package.swift" for a plugin you own, or "plugin is not implemented on ios" only in SPM apps. Do not use for migrating an app project (use cocoapods-to-spm), version bumps of plugins (use capacitor-plugin-upgrades / capacitor-plugin-upgrade-v8-to-v9), or choosing plugins (use capacitor-plugins).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Add Swift Package Manager Support to a Capacitor Plugin

Make a plugin installable in SPM-based Capacitor apps while keeping its podspec for CocoaPods apps.

## When to Use

TRIGGER when:
- A plugin repo has `ios/Plugin/*.swift` + `*.m`/`*.h` with `CAP_PLUGIN(...)` and no root `Package.swift`.
- An app's `npx cap sync ios` prints `<plugin id> does not have a Package.swift` for a plugin the user maintains.
- A plugin works with CocoaPods but JS gets `"X" plugin is not implemented on ios` in SPM apps.
- Preparing a plugin for Capacitor 9 / CocoaPods Trunk read-only.

Do not use:
- App-side CocoaPods removal -> `cocoapods-to-spm`.

capacitor-plugin-upgrade-v4-to-v5

When your agent uses it

Upgrades a Capacitor plugin library from v4 to v5 using `npx @capacitor/plugin-migration-v4-to-v5@latest`, then the manual checklist - `@capacitor/*` dev deps to `latest-5`, compile/target SDK 33 defaults, AGP 8.0.0, Gradle 8.0.2, `namespace` in build.gradle instead of manifest `package`, Java 17, Jetifier removal, Kotlin 1.8.20 with `kotlin-stdlib`, plus code changes - `CAPBridgedPlugin` requirements moved to instance level (`pluginId` -> `identifier`, `pluginMethods` typed `[CAPPluginMethod]`) and Android `PluginCall.getObject()` / `getArray()` may return null. Use when a plugin's peer dependency is Capacitor 4 and it must support 5, or apps on v5 fail with "Namespace not specified" in the plugin module. Do not use for app upgrades, other major versions, or non-Capacitor libraries.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Capacitor Plugin Upgrade v4 to v5

Move a plugin library to Capacitor 5. Source of truth: https://capacitorjs.com/docs/updating/plugins/5-0

## When to Use

- Snapshot shows `@capacitor/core` 4.x in peer/dev deps and the plugin must work in Capacitor 5 apps.
- A Capacitor 5 app fails building this plugin with `Namespace not specified` or Java 17 errors.
- The plugin manually conforms to `CAPBridgedPlugin` or calls `getObject()` / `getArray()`.

Do not use:

- Upgrading an app -> `capacitor-app-upgrade-v4-to-v5`.
- Plugin already on 5 -> `capacitor-plugin-upgrade-v5-to-v6`. Multi-hop -> `capacitor-plugin-upgrades`.

capacitor-plugin-upgrade-v5-to-v6

When your agent uses it

Upgrades a Capacitor plugin library from v5 to v6 using `npx @capacitor/plugin-migration-v5-to-v6@latest`, then the manual checklist - `@capacitor/*` dev deps to `latest-6`, `compileSdkVersion` replaced by `compileSdk`, compile/target SDK 34 defaults, AGP 8.2.1, Gradle 8.2.1, Kotlin 1.9.10, plus code changes - `addListener` in `definitions.ts` returns only `Promise<PluginListenerHandle>` (drop `& PluginListenerHandle`), remove `CAP_PLUGIN_METHOD(removeAllListeners, ...)` from the `.m` file, and optional experimental SPM support via `Package.swift`. Use when a plugin targets Capacitor 5 and must support 6. Do not use for app upgrades, other major versions, or non-Capacitor libraries.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Capacitor Plugin Upgrade v5 to v6

Move a plugin library to Capacitor 6. Source of truth: https://capacitorjs.com/docs/updating/plugins/6-0

## When to Use

- Snapshot shows `@capacitor/core` 5.x and the plugin must work in Capacitor 6 apps.
- `definitions.ts` still declares `Promise<PluginListenerHandle> & PluginListenerHandle`.
- The user wants to add SPM support while moving to 6.

Do not use:

- Upgrading an app -> `capacitor-app-upgrade-v5-to-v6`.
- Plugin on 4.x -> `capacitor-plugin-upgrade-v4-to-v5` first; on 6.x -> `capacitor-plugin-upgrade-v6-to-v7`. Multi-hop -> `capacitor-plugin-upgrades`.

capacitor-plugin-upgrade-v6-to-v7

When your agent uses it

Upgrades a Capacitor plugin library from v6 to v7 using `npx @capacitor/plugin-migration-v6-to-v7@latest`, then the manual checklist - dev deps `^7.0.0` and peer `@capacitor/core` `>=7.0.0`, tooling bumps (eslint, swiftlint, prettier 3 with prettier-plugin-java, rollup 4 with `rollup.config.mjs`, rimraf 6, docgen 0.3), minSdk 23 and compile/target SDK 35 defaults, AGP 8.7.2, Gradle 8.11.1, Java 21, Kotlin 1.9.25, iOS 14 in podspec and `Package.swift`, pinned `capacitor-swift-pm` `from: "7.0.0"`, plus removed APIs - `call.success()` / `call.error()` (use `resolve` / `reject`), `registerWebPlugin`, `Capacitor.platform` / `isNative`, Android `BridgeFragment`. Use when a plugin targets Capacitor 6 and must support 7. Do not use for app upgrades, other major versions, or non-Capacitor libraries.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Capacitor Plugin Upgrade v6 to v7

Move a plugin library to Capacitor 7. Source of truth: https://capacitorjs.com/docs/updating/plugins/7-0

## When to Use

- Snapshot shows `@capacitor/core` 6.x and the plugin must work in Capacitor 7 apps.
- Plugin code still calls `call.success()`, `call.error()`, `registerWebPlugin`, `Capacitor.platform`, `Capacitor.isNative`, or uses `BridgeFragment`.
- `Package.swift` points `capacitor-swift-pm` at `branch: "main"`.

Do not use:

- Upgrading an app -> `capacitor-app-upgrade-v6-to-v7`.
- Plugin on 5.x -> `capacitor-plugin-upgrade-v5-to-v6` first; on 7.x -> `capacitor-plugin-upgrade-v7-to-v8`. Multi-hop -> `capacitor-plugin-upgrades`.

capacitor-plugin-upgrade-v7-to-v8

When your agent uses it

Upgrades a Capacitor plugin library from v7 to v8 using `npx @capacitor/plugin-migration-v7-to-v8@latest`, then the manual checklist - dev deps `^8.0.0` and peer `@capacitor/core` `>=8.0.0`, minSdk 24 and compile/target SDK 36 defaults, AndroidX dependency defaults, AGP 8.13.0, Gradle 8.14.3, Gradle `=` property assignment syntax, Java 21, Kotlin 2.2.20 (`kotlinOptions` to `compilerOptions`, no `kotlin-android-extensions`), google-services 4.4.4, iOS 15 in podspec and `Package.swift`, `capacitor-swift-pm` `from: "8.0.0"`, and the renamed `capacitor_bridge_layout_main` resource. Use when a plugin targets Capacitor 7 and must support 8, or on Kotlin 2 / Gradle space-assignment errors. Points to the v8-to-v9 next step. Do not use for app upgrades, other major versions, or non-Capacitor libraries.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Capacitor Plugin Upgrade v7 to v8

Move a plugin library to Capacitor 8. Source of truth: https://capacitorjs.com/docs/updating/plugins/8-0

## When to Use

- Snapshot shows `@capacitor/core` 7.x and the plugin must work in Capacitor 8 apps.
- Building the plugin against Kotlin 2.2 fails on `kotlinOptions` or `kotlin-android-extensions`.
- Gradle warns `Properties should be assigned using the 'propName = value' syntax`.

Do not use:

- Upgrading an app -> `capacitor-app-upgrade-v7-to-v8`.
- Plugin on 6.x -> `capacitor-plugin-upgrade-v6-to-v7` first. Multi-hop -> `capacitor-plugin-upgrades`.

capacitor-plugin-upgrade-v8-to-v9

When your agent uses it

Upgrades a Capacitor plugin library from v8 to v9 (prerelease, @next until GA). Runs `npx @capacitor/plugin-migration-v8-to-v9@latest`, then the manual checklist - peer/dev dependency ranges, removed Android APIs (@NativePlugin, saveCall, pluginRequestPermission, int-code startActivityForResult, CapConfig getters, PluginCall.save/isSaved/hasOption), removed iOS APIs (CAPBridge class, getWebView, isSimulator, presentVC, CAPNotifications), AGP 9.2.1 / Gradle 9.5.1 build.gradle edits (compileSdk 37, minSdk 26, no targetSdk, built-in Kotlin, core-ktx to core, unique namespace, no jcenter, proguard-android-optimize.txt), iOS 16 in podspec and Package.swift, dropping the Cordova SPM product, and UIScene lifecycle observers. Use for "update my plugin to Capacitor 9", "Cannot find 'CAPBridge' in scope", NativePlugin compile errors, AGP 9 namespace collisions. Do not use for apps (use capacitor-app-upgrade-v8-to-v9), the 8.5 UIScene app step (use capacitor-uiscene-migration), or older majors.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Capacitor Plugin Upgrade v8 to v9

Capacitor 9 is a prerelease (`next` dist-tag, 9.0.0-alpha.x as of October 2026). Dependency ranges below target the prerelease; after 9.0.0 GA use `^9.0.0` / `from: "9.0.0"`. Tell the user before publishing a stable plugin release that only supports a prerelease core; a common choice is to publish it under an npm `next` tag.

Canonical source: https://capacitorjs.com/docs/updating/plugins/9-0

## When to Use

TRIGGER when:
- Plugin repo with `peerDependencies["@capacitor/core"]` at `^8` or `>=8` and the user wants Capacitor 9 support
- Plugin fails to compile against Capacitor 9 on removed APIs (`CAPBridge`, `@NativePlugin`, `saveCall`, `getWebView()`, `isSimulator()`)
- Plugin's `android/build.gradle` fails under AGP 9 / Gradle 9 (`jcenter()`, `kotlin-android`, `proguard-android.txt`, namespace collision)
- A consuming app without Cordova plugins fails on the plugin's `Cordova` SPM product or `com.getcapacitor.cordova` imports

capacitor-plugin-upgrades

When your agent uses it

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.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# 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`

capacitor-uiscene-migration

When your agent uses it

Migrates a Capacitor iOS app or plugin from the AppDelegate lifecycle to the UIScene lifecycle introduced in Capacitor 8.5 and required by Xcode 27. Audits first (custom AppDelegate URL/lifecycle code, CAPBridgeViewController subclasses, existing SceneDelegate.swift, Info.plist UIApplicationSceneManifest, project.pbxproj registration, plugin lifecycle observers, tmpWindow/TmpViewController), reports, then merges surgically or hands template-shaped projects to `npx cap migrate`. Use for "Capacitor 8.5 upgrade", "add SceneDelegate", "adopt UIScene", "CLIENT OF UIKIT REQUIRES UPDATE", deep links or appUrlOpen stopped firing after 8.5, "cap migrate skipped partial state", or as the prerequisite step before Capacitor 9. Do not use for Android, full major upgrades (use capacitor-app-upgrade-v8-to-v9), or new deep-link setup (use capacitor-deep-linking).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Capacitor UIScene Migration (8.4 -> 8.5)

Capacitor 8.5 moved the iOS template to the UIScene lifecycle because Xcode 27 requires it. It shipped as a breaking minor, iOS only. The 8.5 core still runs the AppDelegate path, so bumping the dependency alone does not break an app; the app project must adopt scenes before it can build with Xcode 27 (and before Capacitor 9).

Canonical source: https://capacitorjs.com/docs/updating/8-5

## When to Use

TRIGGER when:
- App is on `@capacitor/ios` 8.0-8.4, or on 8.5 without `UIApplicationSceneManifest` in `Info.plist`
- Xcode 27 build or runtime warning "CLIENT OF UIKIT REQUIRES UPDATE: This process does not adopt UIScene lifecycle"
- `npx cap migrate` printed `UIScene migration: project is in a partial state ... Skipping automated migration`
- After adding a scene manifest: custom URL scheme, universal link, `appUrlOpen`, or AppDelegate `applicationDidBecomeActive` code stopped running
- Build error on `tmpWindow` or `TmpViewController` after updating to 8.5

capacitor-accessibility

When your agent uses it

Makes Capacitor apps work with VoiceOver, TalkBack, Dynamic Type / Android font scale, Switch Control, hardware keyboards, Reduce Motion and Increase Contrast. Covers Capacitor-specific gaps - WKWebView not following iOS Dynamic Type, Android WebView text zoom breaking layouts, zoomEnabled/user-scalable, SPA route changes not announced, native views under the WebView (maps, camera preview) being unreachable, @capacitor/screen-reader (isEnabled, speak, stateChange) and @capacitor/text-zoom (getPreferred, set) - plus testing with Accessibility Inspector, simctl content_size, adb font_scale, TalkBack and axe-core, mapped to WCAG 2.2. Do not use for Ionic component styling (use ionic-design), notch/home-indicator layout (use safe-area-handling), keyboard overlap bugs (use capacitor-keyboard), automated test framework setup (use capacitor-testing), or App Store metadata (use capacitor-app-store).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Accessibility in Capacitor Apps

The UI is web content inside WKWebView / Android WebView, so standard semantic HTML and ARIA do most of the work. This skill covers where the WebView and native layers behave differently from a browser.

## When to Use

TRIGGER when:
- User asks for VoiceOver/TalkBack support, an accessibility audit, WCAG 2.2 / EAA / ADA compliance.
- Text does not grow with iOS Larger Text, or the layout breaks at large Android font sizes.
- Screen reader does not announce page changes, toasts, or loading states.
- A native view (map, camera preview, video player) cannot be reached by the screen reader.
- User wants `@capacitor/screen-reader` or `@capacitor/text-zoom`.

Do not use:

capacitor-ios-security-hardening

When your agent uses it

Audits and progressively hardens Xcode security build settings for a Capacitor iOS app (ios/App/App.xcodeproj, scheme App) and native plugin code (Swift/ObjC/C, Package.swift, podspec). Covers `xcodebuild -showBuildSettings -json`, security compiler warnings, static analyzer checkers (`xcodebuild analyze`), Xcode Enhanced Security (ENABLE_ENHANCED_SECURITY, com.apple.security.hardened-process entitlements, pointer authentication / arm64e, memory tagging soft mode), what is safe for a WKWebView hybrid app vs what breaks CocoaPods, SPM binary xcframeworks or Cordova plugins, staged adoption, and a decision log. Use for "harden my iOS build", "enable Enhanced Security", security build settings audit, arm64e link errors after enabling pointer authentication, or Build and Analyze setup. Do not use for ATS/TLS, signing, secrets or WebView rules (capacitor-security), or App Store review (capacitor-apple-review-preflight).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Capacitor iOS Security Hardening

Audit the security-relevant Xcode build settings of a Capacitor app and its native plugins, then enable them in stages the user approves. This skill changes build settings and entitlements only. It never touches web code, ATS, signing, or secrets.

## When to Use

TRIGGER when:
- The user wants to audit or harden the iOS build configuration of a Capacitor app
- The user asks about Enhanced Security, `ENABLE_ENHANCED_SECURITY`, hardened-process entitlements, pointer authentication, arm64e, or memory tagging
- After enabling Enhanced Security, the link step fails with errors that mention `arm64e`
- A plugin author wants stricter warnings or static analysis for plugin Swift/ObjC/C code
- The user wants "Build and Analyze" / `xcodebuild analyze` in CI

Do not use:

capacitor-performance

When your agent uses it

Diagnoses and fixes performance problems specific to Capacitor apps - slow cold start or long splash, white screen after camera/backgrounding (WKWebView "WebView process terminated" reload, Android onRenderProcessGone), large base64 payloads over the native bridge (Camera, Filesystem.readFile, CapacitorHttp), jank in the WebView, memory growth from unremoved plugin listeners, oversized Preferences storage, slow Android WebView versions, and debug logging left on in release. Covers profiling with Safari Web Inspector, chrome://inspect, Xcode Instruments, Android Studio Profiler, and adb timing commands. Do not use for crash/stack-trace debugging (use debugging-capacitor or capacitor-native-observability), device log capture (use ios-android-logs), offline data architecture (use capacitor-offline-first / sqlite-to-fast-sql), splash configuration details (use capacitor-splash-screen), or generic web performance unrelated to Capacitor.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Capacitor Performance

Find the bottleneck first (WebView JS, bridge, native, or network), then fix the specific cause. Generic web advice (code splitting, image compression, virtual lists) still applies; this skill focuses on what is different inside Capacitor.

## When to Use

TRIGGER when:
- Cold start is slow, splash stays long, or the first screen is blank for seconds.
- App "restarts" or shows a white screen after taking a photo, opening a big file, or returning from background.
- Native calls feel slow, especially with images, files, or large HTTP responses.
- Scrolling/animations jank only on device (often older Android WebView).
- Memory grows over time; listeners pile up.

Do not use:

capacitor-security

When your agent uses it

App-level security audit and hardening for Capacitor apps. Use when the user wants a security review, OWASP MASVS check, or pentest fixes; runs the Capgo scanner (`npx @capgo/capgo-sec scan`, `capsec`, rule IDs like SEC001, NET003, CAP004); finds API keys or `.env` values in the web bundle; stores tokens in `@capacitor/preferences` or `localStorage`; needs Keychain/Keystore storage, certificate pinning, CSP, or root/jailbreak detection; or sees `server.cleartext`, `allowNavigation`, `webContentsDebuggingEnabled`, `NSAllowsArbitraryLoads`, `android:usesCleartextTraffic`, `android:allowBackup`, `net::ERR_CLEARTEXT_NOT_PERMITTED`, or ATS "requires the use of a secure connection" errors. Do not use for Xcode build-setting hardening (use capacitor-ios-security-hardening), deep link setup (capacitor-deep-linking), App Store review (capacitor-apple-review-preflight), CI design (capacitor-ci-cd), or live update setup (capgo-live-updates).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Capacitor Security

Audit and harden the app layer of a Capacitor app: secrets in the bundle, on-device storage, network transport, WebView and native bridge exposure, and platform manifests.

## When to Use

TRIGGER when:
- The user asks for a security audit, OWASP Mobile Top 10 / MASVS review, or wants to fix pentest findings.
- The user wants to run or interpret `@capgo/capgo-sec` (`capsec`) results, rule IDs such as `SEC001`, `STO002`, `NET003`, `CAP004`, `AND004`, `IOS001`.
- API keys, service-role keys, or `.env` values appear in `src/`, `dist/`, `www/`, or `capacitor.config.*`.
- Auth tokens are stored with `Preferences.set`, `localStorage`, IndexedDB, or plain SQLite.
- `capacitor.config.*` contains `server.cleartext: true`, `server.url`, broad `server.allowNavigation`, `android.allowMixedContent`, or `webContentsDebuggingEnabled: true`.
- Native files contain `NSAllowsArbitraryLoads`, `android:usesCleartextTraffic="true"`, `android:allowBackup="true"`, `android:debuggable`, or exported components without permissions.
- The user needs certificate pinning, a Content Security Policy, screenshot protection, or root/jailbreak detection.

capacitor-testing

When your agent uses it

Testing guide for Capacitor apps and plugins. Covers web-layer unit and component tests with Vitest and mocked Capacitor plugins (`vi.mock('@capacitor/core')`, `registerPlugin`), Playwright for the web build, Appium E2E with NATIVE_APP / WEBVIEW context switching, native plugin unit tests with Swift Testing vs XCTest (what can migrate, `CAPPluginCall` patterns, `xcodebuild test` on a simulator) and Android JUnit, plus an agent-driven verification loop on simulators and devices (build, install, launch, screenshot, UI hierarchy, tap, logs) with `xcrun simctl`, `xcrun devicectl`, `adb`, Xcode MCP device tools, and live reload via `npx cap run --url` (Capacitor 9) or `-l --host --port` (Capacitor 8). Use when adding tests, mocking plugins, "does it work on device", verifying a UI change on a simulator, migrating XCTest to Swift Testing, or setting up test CI. Do not use for crash log capture (ios-android-logs), WebView debugging sessions (debugging-capacitor), or build pipelines (capacitor-ci-cd).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Testing Capacitor Apps and Plugins

A Capacitor app has three layers to test: the web app (most logic), the native bridge and plugins (Swift/Kotlin), and the running app on a device. Pick the cheapest layer that can catch the bug.

## When to Use

TRIGGER when:
- Adding unit, component or E2E tests to a Capacitor app
- Mocking Capacitor or plugin APIs in Vitest / Jest
- Writing or modernizing native unit tests for a plugin (Swift Testing, XCTest, JUnit)
- Verifying a change on a simulator, emulator or device ("test this", "does it work", "check on device")
- E2E tests that cannot find web elements in the app (WebView context)
- Setting up test jobs in CI

debugging-capacitor

When your agent uses it

Diagnoses and fixes runtime bugs in Capacitor iOS/Android apps - white/blank screen on launch, startup crashes, `"X" plugin is not implemented on ios/android`, `net::ERR_CLEARTEXT_NOT_PERMITTED`, App Transport Security blocks, CORS on capacitor://localhost, permission denials, live reload not connecting, and Capacitor 8.5+ UIScene regressions (appUrlOpen, universal links, pause/resume silent because AppDelegate callbacks stopped). Covers Safari Web Inspector, chrome://inspect, Xcode/LLDB, Android Studio, `npx cap run --url` (Capacitor 9) vs `-l --host` (8), `xcrun simctl openurl|privacy|push`, `xcrun devicectl device process launch|openURL`, `xctrace`. Do not use for only reading device logs (ios-android-logs), the UIScene migration itself (capacitor-uiscene-migration), deep-link setup (capacitor-deep-linking), speed (capacitor-performance), crash SDKs (capacitor-native-observability), tests (capacitor-testing), or upgrades/build errors (capacitor-app-upgrades, cocoapods-to-spm).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Debugging Capacitor Apps

Find which layer is broken (web, bridge, native, OS config), prove it with the right inspector, then fix the smallest thing.

## When to Use

TRIGGER when:
- App shows a white/blank screen, crashes on launch, or freezes after a native call.
- Error `"<Name>" plugin is not implemented on ios|android` or `"<Name>.<method>()" is not implemented on ...`.
- Network calls fail on device only: `net::ERR_CLEARTEXT_NOT_PERMITTED`, ATS "requires the use of a secure connection", CORS errors.
- Permission prompts never appear or always deny.
- Live reload (`cap run --url`, `server.url`) shows a blank page or "Webpage not available".
- After updating to Capacitor 8.5+ / Xcode 27: `appUrlOpen` silent, universal links open the app but do nothing, JS `pause`/`resume` or custom AppDelegate code no longer runs.
- User asks "how do I debug / inspect my Capacitor app".

ios-android-logs

When your agent uses it

Gets, filters, streams, and saves logs and crash reports from Capacitor apps on iOS Simulator, iPhone, Android emulator and devices. Explains where Capacitor output goes (iOS bridge and mirrored JS console lines are stdout-only, so missing from Console.app and `log stream`; Android tags `Capacitor` and `Capacitor/Console`). Covers `xcrun simctl spawn booted log stream --predicate`, `simctl launch --console-pty`, `xcrun devicectl device process launch --console`, `log collect --device-udid`, Console.app, devicectl `systemCrashLogs`, `adb logcat --pid`, `-b crash`, Android Studio `package:mine`, tombstones, ANRs, `adb bugreport`. Use for "how do I see logs", "console.log not showing on device", "no logs in Console.app", "get the crash log", "logcat too noisy". Do not use for diagnosing the bug once logs are in hand (debugging-capacitor), production crash SDKs (capacitor-native-observability), MCP log tooling (capacitor-mcp), or profiling (capacitor-performance).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# iOS and Android Logs for Capacitor Apps

Pick the log channel that actually carries the message you need, filter to the app, capture to a file, hand off to diagnosis.

## When to Use

TRIGGER when:
- User asks how to view, stream, filter, or save device/simulator logs.
- `console.log` output or `⚡<U+FE0F>` Capacitor lines are missing on iOS/Android.
- User needs a crash report (`.ips`, tombstone, ANR) from a device or simulator.
- Logcat or the unified log is too noisy; user wants only their app or plugin.
- A log command fails or misbehaves: `--level error` still shows everything, `unable to find utility "devicectl"`, `Error: Unexpected argument 'log'`, `adb: no devices/emulators found`.

Do not use:

capacitor-ios-resizability

When your agent uses it

Makes a Capacitor iOS app work in windows that resize while running (iPad Split View, Slide Over, Stage Manager, windowed apps, the foldable iPhone). Audits the web layer (viewport, `100vh`, device sniffing, `screen.width`, `window.orientation`, cached safe-area insets) and native code in the app and node_modules plugins (`UIScreen.main`, `interfaceOrientation`, `userInterfaceIdiom`, `keyWindow`, AppDelegate lifecycle, hard-coded bar heights), then applies trait-, window- and scene-based replacements. Checks Info.plist `UIRequiresFullScreen` (ignored on iOS 27, TN3192), iPad orientations, launch screen (ITMS-90870) and the UIScene lifecycle (Capacitor 8.5+). Use for "support iPad multitasking", "Stage Manager layout broken", "app does not resize", "foldable iPhone", or a plugin overlay mis-sized in split view. Do not use for notch padding only (safe-area-handling) or the SceneDelegate migration (capacitor-uiscene-migration).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Resizable Windows for Capacitor iOS Apps

A Capacitor app is a full-window `WKWebView` in `CAPBridgeViewController`. The web view follows its window. The work is to make the web layout respond to width changes, and to remove native code (app, custom code, plugins) that assumes one full-screen window.

## When to Use

TRIGGER when:
- Preparing an app for iPad multitasking, Stage Manager, windowed iPad apps, the foldable iPhone, or external displays
- The layout breaks or does not update when the window is resized
- A native overlay from a plugin (scanner, camera preview, custom sheet) is the wrong size or position in split view
- Xcode or App Store Connect warns about `UIRequiresFullScreen`, missing iPad orientations, or launch screen requirements
- The user asks to remove `UIScreen.main`, `userInterfaceIdiom`, `interfaceOrientation` or AppDelegate lifecycle use

Do not use:

ionic-design

When your agent uses it

Builds and reviews Ionic Framework UI in Capacitor apps (Ionic 9 current, Ionic 8 still common) - page structure (`ion-header`/`ion-content`/`ion-footer`), lists, modern form syntax (`label`/`labelPlacement` on `ion-input`/`ion-select`), sheet modals, tabs + `ion-router-outlet`, CSS variable theming, dark palettes (`palettes/dark.system.css`, `.ion-palette-dark`), iOS vs MD mode, and Ionic 8 -> 9 breaking changes (React Router 6, Vue Router 5, Angular 18-22 zoneless, removed `ion-picker-legacy`, boolean `autocorrect`, `npx @ionic/migrate`). Use when writing Ionic components, theming an Ionic app, fixing platform-mode styling, or upgrading @ionic/react, @ionic/vue, @ionic/angular. Do not use for Konsta UI (konsta-ui), Tailwind setup (tailwind-capacitor), raw safe-area CSS (safe-area-handling), keyboard resize (capacitor-keyboard), or Ionic Appflow/Enterprise migrations (ionic-appflow-migration, ionic-enterprise-sdk-migration).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Ionic Framework Design

## When to Use

TRIGGER when:
- Writing or reviewing `Ion*` / `ion-*` components in a Capacitor app
- Theming: `--ion-color-*`, dark mode, high contrast, per-platform styles
- iOS vs Material Design mode looks wrong, or `mode` overrides misbehave
- Upgrading Ionic 7/8 -> 9, or errors after `npm i @ionic/*@latest`
- Choosing Ionic vs another UI kit for a new Capacitor app

Do not use:
- Konsta UI components: `konsta-ui`
- Tailwind v4 install / config: `tailwind-capacitor`

konsta-ui

When your agent uses it

Builds Capacitor app UI with Konsta UI v5 (Tailwind CSS v4-based iOS and Material components for React 19, Vue 3, Svelte 5) - CSS-first setup (`@import 'tailwindcss'; @import 'konsta/react/theme.css';`), `--color-brand-*` colors in `@theme`, `<App theme="ios|material|parent" safeAreas dark>`, `KonstaProvider` when mixing with Ionic, `ios:`/`material:` variants, `pt-safe`/`no-safe-areas` utilities, `k-md-vibrant`/`k-md-monochrome`, and migrating from Konsta v3/v4 `konstaConfig` in `tailwind.config.js`. Use when installing or upgrading Konsta, components render unstyled, theme or dark mode does not switch, or Navbar/Tabbar overlap system bars. Do not use for Ionic components (ionic-design), plain Tailwind setup without Konsta (tailwind-capacitor), or native safe-area/edge-to-edge config (safe-area-handling).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Konsta UI for Capacitor

## When to Use

TRIGGER when:
- Adding Konsta UI to a Capacitor app or choosing it over Ionic
- Upgrading Konsta v3/v4 (Tailwind v3 `konstaConfig`) to v5 (Tailwind v4)
- Components unstyled, colors ignored, `ios:`/`material:` classes do nothing
- Navbar / Tabbar under the status bar or gesture bar
- Theme should follow platform (`ios` on iPhone, `material` on Android)

Do not use:
- Ionic Framework components or theming: `ionic-design`
- Tailwind install/config without Konsta: `tailwind-capacitor`

safe-area-handling

When your agent uses it

Fixes notch, Dynamic Island, home indicator, display cutout, and system bar overlap in Capacitor apps. Covers `viewport-fit=cover` + `env(safe-area-inset-*)`, the Capacitor 8 SystemBars core plugin (`insetsHandling`, injected `--safe-area-inset-*` CSS variables for Android WebView < 140, removal of `android.adjustMarginsForEdgeToEdge`), Android 15/16 enforced edge-to-edge (`overlaysWebView` and `backgroundColor` of @capacitor/status-bar no longer work at targetSdk 36), iOS `contentInset`, and insets that change at runtime on rotation, iPad/foldable resizable windows. Use when headers sit under the status bar, tab bars hide behind the gesture bar, `env()` returns 0 on Android, or layout broke after upgrading to Capacitor 8 / targetSdk 35+. Do not use for keyboard overlap (capacitor-keyboard), Ionic/Konsta component theming (ionic-design, konsta-ui), Tailwind utility setup (tailwind-capacitor), or iOS multi-window/resizability adoption (capacitor-ios-resizability).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Safe Area Handling in Capacitor

## When to Use

TRIGGER when:
- Content renders under the status bar, notch, Dynamic Island, cutout, home indicator, or Android navigation/gesture bar
- `env(safe-area-inset-*)` is `0px` on Android, or correct only after rotation
- Layout broke after Capacitor 8 upgrade or raising `targetSdkVersion` to 35/36
- `StatusBar.setOverlaysWebView` / `setBackgroundColor` stopped working on Android
- Landscape / split-screen / iPad windowed layouts have wrong side padding

Do not use:
- Keyboard covering inputs: `capacitor-keyboard`
- Ionic `ion-header`/`ion-toolbar` theming: `ionic-design`; Konsta `safeAreas`: `konsta-ui`

tailwind-capacitor

When your agent uses it

Sets up and uses Tailwind CSS v4 in Capacitor apps - CSS-first config (`@import "tailwindcss"`, `@theme`, `@utility`, `@custom-variant`, `@source`, `@plugin`), `@tailwindcss/vite` / `@tailwindcss/postcss`, upgrading from v3 `tailwind.config.js` with `npx @tailwindcss/upgrade`, WebView browser floor (Safari 16.4+ / Chrome 111+ vs Capacitor iOS 15/16 targets), safe-area utilities built on `env(safe-area-inset-*)`, platform variants (`ios:`/`android:` via a root class), class-based dark mode, `pointer-coarse:` touch targets, and hover-on-touch behavior. Use when installing Tailwind in a Capacitor project, styles do not apply after upgrading to v4, colors look wrong on older iPhones, or building mobile layouts with Tailwind. Do not use for Konsta UI components (konsta-ui), Ionic theming (ionic-design), native system bar / edge-to-edge config (safe-area-handling), or keyboard overlap (capacitor-keyboard).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Tailwind CSS in Capacitor Apps

## When to Use

TRIGGER when:
- Adding Tailwind to a Capacitor app (Vite, Angular, Next static export, etc.)
- Upgrading Tailwind v3 -> v4, or a v4 install produces no styles
- `tailwind.config.js` edits have no effect (v4 is CSS-first)
- Colors / gradients broken or transparent on older iOS devices
- Safe-area, dark mode, platform-specific, or touch-target utilities

Do not use:
- Konsta UI setup/components: `konsta-ui`
- Ionic components and `--ion-*` variables: `ionic-design`

capgo-cli-usage

When your agent uses it

Entry point for the Capgo CLI (`npx @capgo/cli@latest`). Maps the full command surface (init, login, doctor, probe, app, bundle, channel, key, account, organization, build, observe, get-qr, notifications, run device, mcp), explains API-key precedence (--apikey, CAPGO_TOKEN, ~/.capgo, ./.capgo), connects agents to Capgo through the hosted MCP (https://api.capgo.app/mcp) or the local CLI MCP, and routes to the narrower Capgo skill. Use when the user asks generally how to use the Capgo CLI, which command to run, how to authenticate it, how to connect Claude or another agent to Capgo, or gets "No Capgo API key found". Do not use when a specific Capgo skill already matches (capgo-live-updates, capgo-release-management, capgo-native-builds, capgo-organization-management).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Capgo CLI Usage

Route Capgo CLI requests, authenticate the CLI, and connect agents to Capgo.

Facts below were checked against `@capgo/cli` 8.77 (October 2026). Always run `npx @capgo/cli@latest <command> --help` before you rely on a rarely used flag.

## When to Use

TRIGGER when:

- The user asks "how do I use the Capgo CLI", "which Capgo command does X", or asks about CLI login or auth.
- The user wants Claude, Cursor, ChatGPT, or another agent connected to their Capgo account (MCP).
- The request spans several Capgo areas and the right sub-skill is not clear yet.
- The CLI fails before doing any work (auth, wrong directory, missing `appId`).

capgo-cloud

When your agent uses it

Umbrella skill for multi-product Capgo Cloud work in Capacitor apps, combining Capgo Build native binaries, Capgo live updates (OTA), store submission, organization setup, and agent access via the hosted Capgo MCP. Use when the user asks for a Capgo equivalent of a hosted mobile cloud (builds, live updates, and publishing together), wants to plan which Capgo products to use, or needs the order of operations across them. Do not use once the request narrows to one area. Switch to capgo-native-builds, capgo-release-management, capgo-live-updates, capgo-organization-management, or capgo-cli-usage.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Capgo Cloud

Plan and sequence Capgo Cloud work that spans native builds, OTA releases, store publishing, and org administration.

## When to Use

TRIGGER when:

- The user wants "a hosted mobile cloud" for a Capacitor app: native builds, live updates, and publishing together.
- The user is replacing a hosted build-and-deploy service and needs the Capgo product mapping.
- The user asks which Capgo pieces they need and in what order.

Do not use when the request is already about one area:

capgo-live-updates

When your agent uses it

Sets up and debugs Capgo live (OTA) updates in a Capacitor app with @capgo/capacitor-updater. Use when the user wants to ship web-layer fixes without app store review, install or configure the updater plugin, choose an autoUpdate mode, call notifyAppReady, wire manual download/next/set flows, set channels from the app, or debug updates that never apply, roll back, or report codes such as no_new_version_available, disable_auto_update_to_major, cannot_update_via_private_channel, or on_premise_app. Do not use for CLI-only bundle/channel operations (capgo-release-management), Capgo Cloud native builds (capgo-native-builds), or migrations from another OTA vendor.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Capgo Live Updates

Wire `@capgo/capacitor-updater` into a Capacitor app, ship the first bundle, and keep rollback safe.

Facts below were checked against `@capgo/capacitor-updater` 8.52 and `@capgo/cli` 8.77 (October 2026).

## When to Use

TRIGGER when:

- The user wants OTA / live updates, hotfixes without store review, or "Capgo" in a Capacitor app.
- The updater plugin needs installing, upgrading, or configuring in `capacitor.config.*`.
- The user asks about `notifyAppReady`, `autoUpdate` modes, `directUpdate`, `autoSplashscreen`, `setChannel`, `getLatest`, `download`, `next`, `set`, or `reset`.
- Updates upload fine but devices never get them, roll back, or loop.

capgo-native-builds

When your agent uses it

Use for Capgo Cloud Build (Capgo Build) native iOS and Android workflows, including CLI login and API-key precedence, `build init` onboarding, signing credential save/update/export, `build request` with TestFlight, App Store, or Play upload, temporary IPA/APK/AAB download links (`--output-upload`), prescan failures, `build needed` OTA-vs-native gating, and CI secrets. Use when errors mention "No credentials found for this app and platform", "Legacy provisioning profile format detected", "Missing required argument: --platform", or prescan check ids. Do not use for OTA bundle uploads (capgo-release-management), updater plugin setup (capgo-live-updates), or local Xcode/Gradle builds and generic CI runners (capacitor-ci-cd).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Capgo Native Builds

Build signed iOS and Android binaries on Capgo Cloud Build and deliver them to the stores or to a temporary download link.

Facts below were checked against `@capgo/cli` 8.77 and https://capgo.app/docs/builder/ (October 2026). The CLI describes native cloud builds as "limited beta".

## When to Use

TRIGGER when:

- The user asks for a Capgo Cloud Build, a native build in the cloud, a signed IPA/APK/AAB, a TestFlight, App Store, or Play upload through Capgo, or a temporary build download link or QR code.
- The user runs or asks about `build init`, `build request`, `build prescan`, `build needed`, `build last-output`, `build sync-ios-version`, or any `build credentials ...` subcommand.
- A Capgo build fails on signing, provisioning, keystore, prescan, or store upload.

capgo-organization-management

When your agent uses it

Guides Capgo account lookup and organization administration with the CLI, including `account whoami`, `organization list/add/members/set/delete`, 2FA enforcement, password policy, API-key expiration and hashed-key policy, and apps per organization. Use when listing or creating Capgo organizations, auditing members' 2FA before enforcing it, tightening org security settings, or resolving "Access Denied: Two-Factor Authentication Required" or "Insufficient permissions". Do not use for OTA bundle or channel work (capgo-release-management), native builds (capgo-native-builds), or app-side updater code (capgo-live-updates).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Capgo Organization Management

Administer Capgo accounts and organizations safely from the CLI.

Facts below were checked against `@capgo/cli` 8.77 (October 2026). All commands accept `-a, --apikey`.

## When to Use

TRIGGER when:

- The user needs their Capgo account ID or email for support (`account whoami`).
- The user lists, creates, renames, or deletes organizations.
- The user audits members or 2FA status, or enforces 2FA, a password policy, API-key expiration, or hashed API keys.
- The user needs to know which org owns an app (`app list --show-org --show-org-id`).

capgo-release-management

When your agent uses it

Runs Capgo OTA release operations with the CLI, including `bundle upload` (channels, delta, rollout, encryption, version bumps), `bundle compatibility` and `releaseType` checks, `channel add/set/promote/currentBundle/delete`, progressive rollouts and rollback, `bundle cleanup`, preview QR codes, and `key create/save` encryption setup. Use when the user ships, promotes, rolls back, or cleans up Capgo bundles, or hits upload errors such as "Version X already exists", "Bundle NOT compatible with <channel> channel", or "Cannot upload the same bundle content". Do not use for updater plugin wiring in app code (capgo-live-updates), native binaries (capgo-native-builds), or org/member administration (capgo-organization-management).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Capgo Release Management

Ship, promote, roll back, and clean up Capgo OTA bundles from the CLI.

Facts below were checked against `@capgo/cli` 8.77 (October 2026). Every command accepts `-a, --apikey`. The `appId` can be omitted inside a Capacitor project.

## When to Use

TRIGGER when:

- The user uploads, lists, deletes, or cleans up bundles, or asks which version a channel serves.
- The user creates or configures channels, promotes staging to production, starts, pauses, or rolls back a progressive rollout, or rolls back a bad release.
- The user asks whether a change is OTA-safe (`bundle compatibility`, `bundle releaseType`).
- The user sets up bundle encryption (`key create`, `key save`, `--key-v2`).

capgo-release-workflows

When your agent uses it

Designs repository-owned release pipelines for Capacitor apps that combine Capgo live updates, native builds (Capgo Build or the team's own CI runners), and App Store / Play publishing, with an automatic OTA-vs-native gate (`bundle releaseType`, `build needed`), staged channels, and rollback. Use when the user wants one release system covering OTA, builds, and store publishing, is replacing a hosted release service with CI they own, or asks how CI should decide between a live update and a store build. Do not use for single-step tasks (capgo-release-management, capgo-native-builds, capgo-live-updates), non-Capacitor apps, or Ionic Enterprise plugin migration (ionic-enterprise-sdk-migration).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Capgo Release Workflows

Set up an end-to-end release system: Capgo OTA for web changes, native builds for binary changes, store publishing, and a CI gate that picks the right path.

## When to Use

TRIGGER when:

- The user wants a single release pipeline covering live updates, native builds, and store publishing.
- The user is moving off a hosted release service (Appflow-style) to CI they own.
- The user asks "how does CI know if this needs a store release?"

Do not use when:

skill-creator

When your agent uses it

Guides authoring, reviewing, and validating agent skills (SKILL.md + metadata.json + references/ + scripts/) in this Capgo skills repository and similar ones. Covers trigger and negative-trigger design, lean SKILL.md with a when-to-load reference index, traps over basics, verification and error-handling sections, version tagging of facts, subagent-oriented skills (main-agent vs subagent split), optional when_to_use frontmatter, inline snapshots with allowed-tools, skillgrade evals, and this repo's canonical skills/ to plugins/ mirroring and registration. Use when creating a new skill, tightening a skill's description or triggers, splitting a long skill into references, or fixing `bun run lint-skills` failures. Do not use for app documentation, README or marketing copy, or library code that is not a skill.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Skill Authoring

Write skills that load at the right moment, teach what the model does not already know, and prove their own results.

## When to Use

TRIGGER when:

- The user creates a skill directory, or asks to improve, review, or split an existing skill.
- A skill triggers too often, too rarely, or collides with a sibling skill.
- `bun run lint-skills` fails, or a skill must be registered in a plugin or the marketplace.
- The user wants a skillgrade eval for a skill.

Do not use when:

When your agent uses it

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

name: BrokenSkill
description: Skill docs.

# Broken Skill

This draft is intentionally poor.

capacitor-accessibility

When your agent uses it

Makes Capacitor apps work with VoiceOver, TalkBack, Dynamic Type / Android font scale, Switch Control, hardware keyboards, Reduce Motion and Increase Contrast. Covers Capacitor-specific gaps - WKWebView not following iOS Dynamic Type, Android WebView text zoom breaking layouts, zoomEnabled/user-scalable, SPA route changes not announced, native views under the WebView (maps, camera preview) being unreachable, @capacitor/screen-reader (isEnabled, speak, stateChange) and @capacitor/text-zoom (getPreferred, set) - plus testing with Accessibility Inspector, simctl content_size, adb font_scale, TalkBack and axe-core, mapped to WCAG 2.2. Do not use for Ionic component styling (use ionic-design), notch/home-indicator layout (use safe-area-handling), keyboard overlap bugs (use capacitor-keyboard), automated test framework setup (use capacitor-testing), or App Store metadata (use capacitor-app-store).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Accessibility in Capacitor Apps

The UI is web content inside WKWebView / Android WebView, so standard semantic HTML and ARIA do most of the work. This skill covers where the WebView and native layers behave differently from a browser.

## When to Use

TRIGGER when:
- User asks for VoiceOver/TalkBack support, an accessibility audit, WCAG 2.2 / EAA / ADA compliance.
- Text does not grow with iOS Larger Text, or the layout breaks at large Android font sizes.
- Screen reader does not announce page changes, toasts, or loading states.
- A native view (map, camera preview, video player) cannot be reached by the screen reader.
- User wants `@capacitor/screen-reader` or `@capacitor/text-zoom`.

Do not use:

capacitor-app-intents

When your agent uses it

Exposes Capacitor app features to Siri, Shortcuts, Spotlight, the Action button, Apple Intelligence, widgets and controls with native App Intents in ios/App/App, bridged to the web layer. Covers open-app intents routed through Universal Links / `OpenURLIntent` and @capacitor/app `appUrlOpen`, or a local plugin with a pending-route store; headless background intents; App Group / Preferences data sharing; AppShortcutsProvider phrases, AppEntity queries; iOS 26/27 APIs (`supportedModes` replacing `openAppWhenRun`, `continueInForeground`, `LongRunningIntent`, AppIntentsTesting) gated for Capacitor 8 (iOS 15) and 9 (iOS 16). Covers file placement, target membership, and UIScene (Capacitor 8.5+) URL delivery. Use for "add Siri shortcut", "Shortcuts action", "App Shortcuts", "control widget", or an intent that opens the app but the web view never navigates. Do not use for deep link setup (capacitor-deep-linking), push (capacitor-push-notifications), or Android shortcuts.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# App Intents for Capacitor Apps

Add native App Intents to the iOS project so system surfaces can run app actions, and connect them to the web layer. App Intents are Swift only. There is no JavaScript API for them, so every intent is native code in the App target or an extension, and the web layer is reached through a URL or a small local plugin.

## When to Use

TRIGGER when:
- The user wants Siri phrases, Shortcuts actions, App Shortcuts, Spotlight actions, Action button or Apple Intelligence integration for a Capacitor app
- The user wants a widget button or a Control Center control to run an app action
- An intent opens the app, but the web view does not navigate, or it navigates only on warm launch
- A background intent crashes, times out, or tries to call JS
- Migrating `openAppWhenRun` to `supportedModes`, or adopting iOS 26/27 App Intents APIs
- A plugin author wants to ship App Intents with a plugin

capacitor-app-store

When your agent uses it

Ships a Capacitor app to the Apple App Store and Google Play. Use for release prep and submission - version/build numbers (CFBundleVersion, versionCode), signing, archiving and uploading the IPA/AAB, TestFlight, Play tracks and closed testing, icons and screenshots, listing metadata, App Privacy and Data safety forms, age ratings, export compliance, phased rollout, and current platform deadlines (iOS 26 SDK since April 28 2026, iOS 27 SDK from April 2027, UIScene lifecycle for Xcode 27, Play target API 36 from Aug 31 2026, 16 KB page size). Also for upload errors like ITMS-90725, ITMS-91053, ITMS-91061, ITMS-4238 redundant binary, or "Version code has already been used". Do not use for a guideline-by-guideline Apple rejection audit (capacitor-apple-review-preflight), CI pipeline authoring (capacitor-ci-cd), Capgo Cloud Build setup (capgo-native-builds), or converting a website into an app (webapp-to-capacitor).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Publishing Capacitor Apps to the Stores

Get a Capacitor build from "runs on my device" to "live in both stores" without avoidable upload or review failures.

## When to Use

TRIGGER when:
- The user is preparing a first release or an update to App Store Connect or Google Play Console.
- Upload or processing fails (ITMS errors, Play Console version/target API errors).
- The user needs screenshot sizes, icon requirements, listing fields, privacy forms, or rollout options.
- The user asks which Xcode/SDK or target API level the stores require right now.

Do not use for:
- Auditing an app against App Review Guidelines or answering a rejection -> `capacitor-apple-review-preflight`.

capacitor-app-upgrade-v4-to-v5

When your agent uses it

Upgrades a Capacitor app from v4 to v5 using `npx cap migrate` from `@capacitor/cli@latest-5`, then the manual checklist - Node 16+, Xcode 14.1+, Android Studio Flamingo with JDK 17, AGP 8.0.0, Gradle 8.0.2, compile/target SDK 33, `package` moved from AndroidManifest.xml to `namespace` in build.gradle, Jetifier removal, pinning `androidScheme` to `http`, and official plugin breaking changes (Device `uuid` to `identifier`, Android 13 notification permissions, READ_MEDIA_IMAGES). Use when `@capacitor/core` is 4.x and the target is 5.x, or on errors like "Namespace not specified" or "Android Gradle plugin requires Java 17". Do not use for other major versions, plugin library upgrades, or non-Capacitor apps.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Capacitor App Upgrade v4 to v5

Move a Capacitor 4 app to Capacitor 5. Source of truth: https://capacitorjs.com/docs/updating/5-0

## When to Use

- `@capacitor/core` in the snapshot below is `4.x` and the user wants `5.x`.
- Android build fails after bumping to Capacitor 5 with `Namespace not specified`, a Java 11 vs 17 mismatch, or AGP 8 errors.
- The user asks for the exact 4 -> 5 checklist for iOS, Android, or official plugins.

Do not use:

- App on 5.x or later -> `capacitor-app-upgrade-v5-to-v6` (then v6-to-v7, v7-to-v8). Multi-hop planning -> `capacitor-app-upgrades`.
- Upgrading a plugin library -> `capacitor-plugin-upgrade-v4-to-v5`.

capacitor-app-upgrade-v5-to-v6

When your agent uses it

Upgrades a Capacitor app from v5 to v6 using `npx cap migrate` from `@capacitor/cli@latest-6`, then the manual checklist - Node 18+, Xcode 15+, Android Studio Hedgehog, AGP 8.2.1, Gradle 8.2.1, compile/target SDK 34, `compileSdkVersion` to `compileSdk`, the `androidScheme` default flipping to `https` (data loss risk), iOS local plugins no longer auto-registered, iOS zoom disabled by default, and official plugin breaking changes (`addListener` returns only a Promise, Camera Photo Picker, Filesystem ctime/mtime numbers). Use when `@capacitor/core` is 5.x and the target is 6.x, or after the upgrade users are logged out on Android, a custom iOS plugin is "not implemented", or `addListener(...).remove` no longer compiles. Do not use for other major versions, plugin library upgrades, or non-Capacitor apps.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Capacitor App Upgrade v5 to v6

Move a Capacitor 5 app to Capacitor 6. Source of truth: https://capacitorjs.com/docs/updating/6-0

## When to Use

- `@capacitor/core` in the snapshot below is `5.x` and the user wants `6.x`.
- After upgrading: Android users lose localStorage/cookies, a local (non-npm) iOS plugin reports `"<Name>" plugin is not implemented on ios`, pinch-zoom stopped working on iOS, or TypeScript errors around `addListener`.
- The user asks for the exact 5 -> 6 checklist.

Do not use:

- App on 4.x -> `capacitor-app-upgrade-v4-to-v5` first. On 6.x -> `capacitor-app-upgrade-v6-to-v7`. Multi-hop planning -> `capacitor-app-upgrades`.
- Plugin library upgrade -> `capacitor-plugin-upgrade-v5-to-v6`.

capacitor-app-upgrade-v6-to-v7

When your agent uses it

Upgrades a Capacitor app from v6 to v7 using `npx cap migrate` from `@capacitor/cli@latest-7`, then the manual checklist - Node 20+, Xcode 16+, iOS deployment target 14.0 (Xcode project and Podfile), Android Studio Ladybug with JDK 21, AGP 8.7.2, Gradle 8.11.1, minSdk 23, compile/target SDK 35, removed `bundledWebRuntime` and `cordova.staticPlugins` config, `navigation` in configChanges, and official plugin breaking changes (removed deprecated types like `AppUrlOpen`, `HapticsImpactStyle`, `DeviceBatteryInfo`; Device no longer returns disk sizes). Use when `@capacitor/core` is 6.x and the target is 7.x, or on errors like "Capacitor 7 requires JDK 21" or "Module 'X' has no exported member 'AppUrlOpen'". Do not use for other major versions, plugin library upgrades, or non-Capacitor apps.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Capacitor App Upgrade v6 to v7

Move a Capacitor 6 app to Capacitor 7. Source of truth: https://capacitorjs.com/docs/updating/7-0

## When to Use

- `@capacitor/core` in the snapshot below is `6.x` and the user wants `7.x`.
- Build fails after bumping to 7 with JDK 21 / AGP 8.7 errors, iOS deployment target 13 errors, or TypeScript errors on removed deprecated plugin types.
- The user asks for the exact 6 -> 7 checklist.

Do not use:

- App on 5.x -> `capacitor-app-upgrade-v5-to-v6` first. On 7.x -> `capacitor-app-upgrade-v7-to-v8`. Multi-hop planning -> `capacitor-app-upgrades`.
- Plugin library upgrade -> `capacitor-plugin-upgrade-v6-to-v7`.

capacitor-app-upgrade-v7-to-v8

When your agent uses it

Upgrades a Capacitor app from v7 to v8 using `npx cap migrate` from `@capacitor/cli@latest`, then the manual checklist - Node 22+, Xcode 26+, iOS deployment target 15.0, Android Studio Otter, AGP 8.13.0, Gradle 8.14.3, JDK 21, minSdk 24, compile/target SDK 36, Kotlin 2.2.20, Gradle `=` property assignment syntax, `density` in configChanges, removed `android.adjustMarginsForEdgeToEdge` (use the System Bars plugin and CSS env vars), `bridge_layout_main.xml` renamed, iOS `appendUserAgent` whitespace fix, and official plugin changes (Geolocation timeout, Screen Orientation/Barcode Scanner on Android 16 large screens). Use when `@capacitor/core` is 7.x and the target is 8.x. Points to the 8.5 UIScene adoption and v9 next steps. Do not use for other major versions, plugin library upgrades, or non-Capacitor apps.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Capacitor App Upgrade v7 to v8

Move a Capacitor 7 app to Capacitor 8 (current stable line: 8.5.x). Source of truth: https://capacitorjs.com/docs/updating/8-0

## When to Use

- `@capacitor/core` in the snapshot below is `7.x` and the user wants `8.x`.
- After bumping to 8: content under the Android status/navigation bar (edge-to-edge), `bridge_layout_main` not found, Gradle "space-assignment syntax" deprecation warnings, Kotlin 2 `kotlinOptions` errors, or Geolocation timeouts.
- The user asks for the exact 7 -> 8 checklist.

Do not use:

- App on 6.x -> `capacitor-app-upgrade-v6-to-v7` first. Multi-hop planning -> `capacitor-app-upgrades`.
- App already on 8.x -> `capacitor-uiscene-migration` (8.5 scene lifecycle), then `capacitor-app-upgrade-v8-to-v9`.

capacitor-app-upgrade-v8-to-v9

When your agent uses it

Upgrades a Capacitor app from v8 to v9 (prerelease, installed with @next until GA). Covers preflight (Node 24, Xcode 27, Android Studio 2026.1.1, UIScene adoption from 8.5), `npx cap migrate`, and the manual checklist - iOS 16 target, @UIApplicationMain to @main, removed CAPBridge APIs, AGP 9.2.1, Gradle 9.5.1, SDK 37/minSdk 26, gradle.properties cleanup, built-in Kotlin, jcenter removal, core-ktx, proguard-android.txt rename, optional Cordova runtime, `cap run --url`, push `alert` removal, splash fade default. Use for "upgrade to Capacitor 9", errors like "'@UIApplicationMain' is deprecated", "Could not find method jcenter()", getDefaultProguardFile('proguard-android.txt') failures, duplicate Kotlin plugin, duplicate class core-ktx, "unknown option '-l'". Do not use for 8.4 to 8.5 UIScene only (use capacitor-uiscene-migration), plugin libraries (use capacitor-plugin-upgrade-v8-to-v9), or older majors.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Capacitor App Upgrade v8 to v9

Capacitor 9 is a prerelease (`next` dist-tag, 9.0.0-alpha.x as of October 2026). Install with `@next`; switch to `@latest` / `^9.0.0` once 9.0.0 is GA. Tell the user it is not GA before upgrading a production app, and work on a branch.

Canonical source: https://capacitorjs.com/docs/updating/9-0

## When to Use

TRIGGER when:
- App is on `@capacitor/core` 8.x and the user wants Capacitor 9
- Build errors after moving to Xcode 27 / Swift 6, AGP 9, or Gradle 9 in a Capacitor 8 app
- `npx cap run -l --host ...` no longer works (`--url` replaced it)
- Push notifications `presentationOptions: ['alert']` stopped showing banners on iOS
- Cordova-plugin-free app fails on `CapacitorCordova` / `com.getcapacitor.cordova` references after upgrading

capacitor-app-upgrades

When your agent uses it

Routes and drives a Capacitor app upgrade across one or more major versions (4 to 9), including the required 8.4 to 8.5 iOS UIScene step before Capacitor 9 and Xcode 27. Detects the current version, plans the hop order (e.g. 6 to 7 to 8 to 8.5 to 9), runs `npx cap migrate` per hop, delegates each hop to its version skill, and verifies native builds between hops. Use for "upgrade Capacitor", "update to the latest Capacitor", "cap migrate", multi-version jumps, or when the target version is unclear. Do not use for plugin library upgrades (use capacitor-plugin-upgrades), Cordova apps (use cordova-to-capacitor), or non-Capacitor frameworks.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Capacitor App Upgrade (router)

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

## When to Use

TRIGGER when:
- User wants to upgrade a Capacitor app and the start or target version is unknown or more than one major apart
- User asks for "the latest Capacitor" (decide stable 8.5.x vs prerelease 9 with them)
- Xcode 27 builds fail on a Capacitor 8.4-or-older app (needs the 8.5 UIScene step)
- `npx cap migrate` failed midway and the user needs to know where they are

Do not use:
- Plugin library repos -> `capacitor-plugin-upgrades`

capacitor-apple-review-preflight

When your agent uses it

Audits a Capacitor iOS app against Apple App Review Guidelines before submission or after a rejection. Use when the user pastes a rejection (Guideline 4.2 Minimum Functionality, 4.8 Login Services / Sign in with Apple, 5.1.1 data collection or account deletion, 5.1.2(i) sharing data with third-party AI, 3.1.1 in-app purchase, 2.1 app completeness, 2.3 metadata, 4.3 spam), an upload warning (ITMS-91053 missing API declaration, ITMS-91061 missing privacy manifest, ITMS-90683 missing purpose string), or wants a preflight of metadata, PrivacyInfo.xcprivacy, Info.plist usage strings, entitlements, subscriptions, reviewer notes, live-update disclosure, and Xcode 27 / UIScene readiness. Do not use for Google Play review, upload mechanics, screenshots and listing setup (capacitor-app-store), building a web wrapper from scratch (webapp-to-capacitor), or non-Capacitor runtimes.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Capacitor Apple Review Preflight

Run a pre-submission or post-rejection Apple review audit for a Capacitor app and return a prioritized, evidence-backed report.

This skill adapts the Apple guideline and rejection-rule corpus from [truongduy2611/app-store-preflight-skills](https://github.com/truongduy2611/app-store-preflight-skills) and narrows the workflow to Capacitor-specific project inspection.

## When to Use

TRIGGER when:
- The user wants an App Store review preflight for a Capacitor app.
- The user received an App Review rejection or an App Store Connect upload warning email and wants the project audited.
- The user asks whether metadata, entitlements, privacy manifests, Sign in with Apple, subscriptions, AI features, or minimum functionality will pass.
- The user wants reviewer notes for a Capacitor submission (demo accounts, live updates, hardware features).

capacitor-best-practices

When your agent uses it

Review and set up Capacitor apps against current best practices (Capacitor 8.5 stable, 9 alpha via `@next`). Use for a Capacitor codebase review, `capacitor.config.ts` audit, new project setup, aligning `@capacitor/core`/`cli`/`ios`/`android` and plugin majors, plugin patterns (availability checks, `checkPermissions`/`requestPermissions`, error `code` handling, web fallbacks), or release prep; or on `"<Plugin>" plugin is not implemented on ios`, `Could not find the web assets directory`, `platform has not been added yet`, a dev `server.url` shipped to production, lost edits in `android/app/src/main/assets/public`, SPM vs CocoaPods, or AppDelegate/UIScene drift. Do not use for security audits (capacitor-security), performance (capacitor-performance), tests (capacitor-testing), crashes (debugging-capacitor), major upgrades (capacitor-app-upgrades), SPM migration (cocoapods-to-spm), UIScene adoption (capacitor-uiscene-migration), or live updates (capgo-live-updates).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Capacitor Best Practices

Review a Capacitor app for structural mistakes that cause broken builds, lost edits, production leaks, and plugin crashes. Route deep topics to the sibling skill that owns them.

## When to Use

TRIGGER when:
- The user asks for a general code/architecture review of a Capacitor or Ionic + Capacitor app.
- Setting up a new Capacitor project or adding iOS/Android to an existing web app.
- `capacitor.config.ts|json` review: `webDir`, `server.url`, `cleartext`, plugin config, env-specific config.
- Version drift between `@capacitor/core`, `@capacitor/cli`, `@capacitor/ios`, `@capacitor/android`, or plugin majors that do not match Capacitor's major.
- Plugin usage review: missing `npx cap sync`, no availability check, no permission flow, matching on error message strings.
- Errors such as `"<Plugin>" plugin is not implemented on ios`, `Could not find the web assets directory`, `ios platform has not been added yet`.
- Pre-release sanity checklist across config, native projects, and live updates.

capacitor-ci-cd

When your agent uses it

Designs and fixes CI/CD pipelines for Capacitor apps - GitHub Actions, GitLab CI, Fastlane, or Capgo Cloud Build (npx @capgo/cli@latest build request) - covering web build and tests, cap sync, iOS archive/export/upload with App Store Connect API keys, Android AAB signing and Play upload, Capgo live-update uploads, secrets, caching, and build-number bumping. Use when choosing runner images and toolchains (Node 22/24, macos-26 vs xcode-27 runners, JDK 21, Gradle 9 / AGP 9 for Capacitor 9), or when CI fails with errors like "No signing certificate", "requires a provisioning profile", "Unsupported class file major version", "Android Gradle plugin requires Java 17", "The engine node is incompatible", or "Could not find the web assets directory". Do not use for one-off manual store submission (capacitor-app-store), Capgo Cloud Build credential onboarding in depth (capgo-native-builds), Capgo channel/release strategy (capgo-release-workflows), or test authoring (capacitor-testing).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# CI/CD for Capacitor Apps

Build, sign, and ship Capacitor apps from CI with the right toolchain for the Capacitor major in use.

## When to Use

TRIGGER when:
- Creating or fixing `.github/workflows/*.yml`, `.gitlab-ci.yml`, `fastlane/Fastfile`, or a Capgo Cloud Build job.
- Picking runner images, Node/Xcode/JDK versions for Capacitor 8 or 9.
- Automating signing, TestFlight/Play uploads, version bumps, or Capgo OTA uploads.
- A CI build fails while a local build works.

Do not use for:
- Manual submission, listing, screenshots -> `capacitor-app-store`.

capacitor-deep-linking

When your agent uses it

Implements and debugs deep links in Capacitor apps - custom URL schemes, iOS Universal Links (apple-app-site-association, Associated Domains entitlement), Android App Links (assetlinks.json, autoVerify), and routing via @capacitor/app `appUrlOpen` + `App.getLaunchUrl()`. Covers the Capacitor 8.5+ UIScene change where AppDelegate `application(_:open:options:)` and `continue userActivity` stop being called and custom handling must move to SceneDelegate, plus cold vs warm launch testing. Use when links open Safari/Chrome instead of the app, `appUrlOpen` never fires, the launch URL is lost on cold start, or OAuth redirects do not return to the app. Do not use for the full UIScene migration (capacitor-uiscene-migration), push notification taps (capacitor-push-notifications), or social login plugin setup (capacitor-plugins).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Deep Linking in Capacitor

Route custom-scheme links, iOS Universal Links, and Android App Links into the web app.

## When to Use

TRIGGER when:
- Adding `myapp://` schemes, Universal Links, or App Links to a Capacitor app
- Links open the browser instead of the app, or open the app but land on the home page
- `appUrlOpen` fires on warm open but the URL is missing on cold launch (or the reverse)
- Deep links broke after updating to Capacitor 8.5+ / adopting `SceneDelegate.swift`
- OAuth / magic-link / payment redirects must come back into the app
- `adb shell pm get-app-links` shows `none` or `1024` instead of `verified`

capacitor-ios-resizability

When your agent uses it

Makes a Capacitor iOS app work in windows that resize while running (iPad Split View, Slide Over, Stage Manager, windowed apps, the foldable iPhone). Audits the web layer (viewport, `100vh`, device sniffing, `screen.width`, `window.orientation`, cached safe-area insets) and native code in the app and node_modules plugins (`UIScreen.main`, `interfaceOrientation`, `userInterfaceIdiom`, `keyWindow`, AppDelegate lifecycle, hard-coded bar heights), then applies trait-, window- and scene-based replacements. Checks Info.plist `UIRequiresFullScreen` (ignored on iOS 27, TN3192), iPad orientations, launch screen (ITMS-90870) and the UIScene lifecycle (Capacitor 8.5+). Use for "support iPad multitasking", "Stage Manager layout broken", "app does not resize", "foldable iPhone", or a plugin overlay mis-sized in split view. Do not use for notch padding only (safe-area-handling) or the SceneDelegate migration (capacitor-uiscene-migration).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Resizable Windows for Capacitor iOS Apps

A Capacitor app is a full-window `WKWebView` in `CAPBridgeViewController`. The web view follows its window. The work is to make the web layout respond to width changes, and to remove native code (app, custom code, plugins) that assumes one full-screen window.

## When to Use

TRIGGER when:
- Preparing an app for iPad multitasking, Stage Manager, windowed iPad apps, the foldable iPhone, or external displays
- The layout breaks or does not update when the window is resized
- A native overlay from a plugin (scanner, camera preview, custom sheet) is the wrong size or position in split view
- Xcode or App Store Connect warns about `UIRequiresFullScreen`, missing iPad orientations, or launch screen requirements
- The user asks to remove `UIScreen.main`, `userInterfaceIdiom`, `interfaceOrientation` or AppDelegate lifecycle use

Do not use:

capacitor-ios-security-hardening

When your agent uses it

Audits and progressively hardens Xcode security build settings for a Capacitor iOS app (ios/App/App.xcodeproj, scheme App) and native plugin code (Swift/ObjC/C, Package.swift, podspec). Covers `xcodebuild -showBuildSettings -json`, security compiler warnings, static analyzer checkers (`xcodebuild analyze`), Xcode Enhanced Security (ENABLE_ENHANCED_SECURITY, com.apple.security.hardened-process entitlements, pointer authentication / arm64e, memory tagging soft mode), what is safe for a WKWebView hybrid app vs what breaks CocoaPods, SPM binary xcframeworks or Cordova plugins, staged adoption, and a decision log. Use for "harden my iOS build", "enable Enhanced Security", security build settings audit, arm64e link errors after enabling pointer authentication, or Build and Analyze setup. Do not use for ATS/TLS, signing, secrets or WebView rules (capacitor-security), or App Store review (capacitor-apple-review-preflight).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Capacitor iOS Security Hardening

Audit the security-relevant Xcode build settings of a Capacitor app and its native plugins, then enable them in stages the user approves. This skill changes build settings and entitlements only. It never touches web code, ATS, signing, or secrets.

## When to Use

TRIGGER when:
- The user wants to audit or harden the iOS build configuration of a Capacitor app
- The user asks about Enhanced Security, `ENABLE_ENHANCED_SECURITY`, hardened-process entitlements, pointer authentication, arm64e, or memory tagging
- After enabling Enhanced Security, the link step fails with errors that mention `arm64e`
- A plugin author wants stricter warnings or static analysis for plugin Swift/ObjC/C code
- The user wants "Build and Analyze" / `xcodebuild analyze` in CI

Do not use:

capacitor-keyboard

When your agent uses it

Fixes on-screen keyboard behavior in Capacitor apps with @capacitor/keyboard - iOS `resize` modes (`native` default, `body`, `ionic`, `none`), `keyboardWillShow`/`keyboardDidShow` heights, `setAccessoryBarVisible`, `setScroll`, `style` (`DARK`/`LIGHT`/`DEFAULT`), `autoBackdropColor` (8.0.4+), Android edge-to-edge/SystemBars interaction (drop legacy `resizeOnFullScreen` on Capacitor 8), iOS 26 fixes, and iOS input auto-zoom. Use when inputs are hidden behind the keyboard, the WebView jumps or leaves a white/black gap above the keyboard, fixed footers float mid-screen, `vh` layouts shrink, or keyboard events do not fire. Do not use for general safe-area/notch padding (safe-area-handling), Ionic component styling (ionic-design), or form accessibility (capacitor-accessibility).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Keyboard Handling in Capacitor

## When to Use

TRIGGER when:
- Focused input is covered by the keyboard, or the page scrolls unexpectedly
- Chat composer / fixed footer does not stick to the keyboard
- White or black band above the keyboard (Android 15+ edge-to-edge, iOS backdrop)
- `100vh` / `dvh` layout collapses when the keyboard opens
- iOS zooms into inputs, or the QuickType/accessory bar looks wrong
- Keyboard events never fire or fire twice

Do not use:
- Notch / home-indicator / status-bar padding: `safe-area-handling`

capacitor-mcp

When your agent uses it

Connect AI agents (Claude Code, Claude Desktop, Cursor, VS Code, Cline, Codex) to Capacitor and Ionic tooling over Model Context Protocol. Covers the awesome-ionic-mcp server (Ionic component APIs, Capacitor plugin docs, Ionic/Capacitor CLI tools), the Capgo hosted MCP at https://api.capgo.app/mcp, the local Capgo CLI MCP (npx @capgo/cli@latest mcp), and Xcode's MCP bridge (xcrun mcpbridge) for building the iOS app from an agent. Use when the user wants to add, configure, verify, or troubleshoot an MCP server for a Capacitor project, or sees errors like "GitHub API rate limit exceeded", "unable to find utility \"mcpbridge\"", or an MCP server that connects with no tools. Do not use for Capgo account operations themselves (capgo-cloud, capgo-cli-usage), app debugging (debugging-capacitor), device logs (ios-android-logs), choosing plugins (capacitor-plugins), or Ionic UI work (ionic-design).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

# Capacitor MCP Servers

Wire MCP servers into an agent so it can read Ionic/Capacitor docs, run Capacitor CLI commands, manage Capgo, and drive Xcode.

## When to Use

TRIGGER when the user:
- asks to "add an MCP server" / "connect Claude/Cursor to Capacitor, Ionic, Capgo or Xcode"
- mentions `awesome-ionic-mcp`, `api.capgo.app/mcp`, `@capgo/cli mcp`, `xcrun mcpbridge`, `claude mcp add`, `.cursor/mcp.json`, `.vscode/mcp.json`, `claude_desktop_config.json`
- has an MCP server that fails to start, shows no tools, asks to sign in, or hits a rate limit

Do not use for:
- uploading bundles, channels, rollouts, native builds as a task: `capgo-cloud`, `capgo-cli-usage`, `capgo-live-updates`, `capgo-native-builds`
- finding or installing a plugin: `capacitor-plugins`

capacitor-offline-first

When your agent uses it

Designs and implements offline-first data in Capacitor apps - local SQLite source of truth with @capgo/capacitor-fast-sql (`FastSQL.connect`, `KeyValueStore`), an outbox/sync queue, delta pulls, conflict resolution, @capacitor/network `networkStatusChange`, background sync with @capgo/capacitor-background-task, and why localStorage/IndexedDB get evicted and service workers break plugin injection in native WebViews. Use when the app must work without internet, data disappears after iOS storage pressure, sync duplicates or loses writes, or `Plugin not implemented` appears after adding a service worker. Do not use for migrating an existing SQLite plugin (sqlite-to-fast-sql), shipping web bundle updates offline (capgo-live-updates), HTTP security/certificate pinning (capacitor-security), or general performance (capacitor-performance).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.