# capacitor-app-spm-migration

A skill that walks the agent through moving a Capacitor app's iOS dependencies from CocoaPods to Swift Package Manager. Useful once your ios/ folder holds custom files.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 687 installs · ★ 51
- Author: capawesome-team
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/capawesome-team/skills/tree/HEAD/skills/capacitor-app-spm-migration/SKILL.md
- Updated: 2026-10-20
- HTML: https://affpapa.org/en/nevibecode/skills/capacitor-app-spm-migration

## What it does

The skill runs the migration step by step. It first confirms the project is a Capacitor app rather than a plugin, that `ios/App/Podfile` exists, and that the Git working tree is clean. Then the agent inventories installed plugins by prefix — `@capacitor/*`, `@capawesome/*`, `@capacitor-community/*` and others — so they can be checked against SPM later.

Before anything is deleted, the skill builds a checklist of files holding your edits: `Info.plist`, `AppDelegate.swift`, `Assets.xcassets`, `Base.lproj`, `App.entitlements`, `GoogleService-Info.plist`, `.xcconfig`, plus any other `.swift` files and targets such as a Notification Service Extension. Those get copied into `.spm-migration-backup/`, and signing values and version numbers are read out of `project.pbxproj`. The `ios/` folder is then removed and re-scaffolded with `npx cap add ios --packagemanager SPM`.

The migration is destructive, so an uncommitted tree leaves you nothing to roll back to — hence the clean `git status --porcelain` check. You need Node.js 18+, npm, Xcode 15+ on macOS and CocoaPods installed to verify the old setup. The interactive `npx cap spm-migration-assistant` is deliberately skipped; every step runs manually. Capacitor plugin projects, apps already on SPM and non-Capacitor frameworks are out of scope.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add capawesome-team/skills --skill capacitor-app-spm-migration -a claude-code
```

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

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add capawesome-team/skills --skill capacitor-app-spm-migration -a codex
```

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

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add capawesome-team/skills --skill capacitor-app-spm-migration -a cursor
```

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

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install capawesome-team/skills capacitor-app-spm-migration
```

2. **Manually: put the files in place**
- File: `.github/skills/capacitor-app-spm-migration/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add capawesome-team/skills --skill capacitor-app-spm-migration -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/capawesome-team/skills --path skills/capacitor-app-spm-migration
```

### Windsurf (Devin Desktop)

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

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add capawesome-team/skills --skill capacitor-app-spm-migration -a opencode
```

### Claude.ai

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

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/capawesome-team/skills/tree/HEAD/skills/capacitor-app-spm-migration/SKILL.md

## When to use it
- move a Capacitor app's iOS dependencies from CocoaPods to SPM
- keep custom `Info.plist` and `AppDelegate.swift` through the `ios/` rebuild
- pull signing and bundle settings out of the old `project.pbxproj`
- check that every installed plugin resolves under SPM
- roll back a failed migration with Git

## Example prompts
- Run the capacitor-app-spm-migration skill on this Capacitor app and move it from CocoaPods to SPM
- List the `ios/` files you'll back up first, then delete the folder
- After `npx cap add ios --packagemanager SPM`, restore files from `.spm-migration-backup/` and verify the build

## Source text · SKILL.md · MIT

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

BEGIN THIRD-PARTY FILE 6460c450117e52b2
```text
---
name: capacitor-app-spm-migration
description: "Guides the agent through migrating an existing Capacitor app project from CocoaPods to Swift Package Manager (SPM) for iOS dependency management. Covers prerequisite checks, inventorying installed Capacitor plugins, backing up customized iOS project files (Info.plist, AppDelegate.swift, Assets.xcassets, Base.lproj, App.entitlements, GoogleService-Info.plist, .xcconfig files, signing configuration), deleting the existing `ios/` folder, re-scaffolding with `npx cap add ios --packagemanager SPM`, restoring preserved files, re-syncing plugins, and verifying the build. Performs all migration steps manually — does not use the interactive `npx cap spm-migration-assistant` command. Do not use for Capacitor plugin projects, app projects already on SPM, app projects without an existing `ios/` folder, or non-Capacitor mobile frameworks."
license: MIT
compatibility: "Requires Node.js 18+, npm, and Xcode 15+ on macOS. CocoaPods must be installed to verify the existing setup, and Git is used to keep the migration reversible."
metadata:
  author: capawesome-team
  source: https://github.com/capawesome-team/skills/tree/main/skills/capacitor-app-spm-migration
---

# Capacitor App: CocoaPods → SPM Migration

Migrate an existing Capacitor app project's iOS dependency management from CocoaPods to Swift Package Manager (SPM). The migration is destructive — the existing `ios/` folder is deleted and re-scaffolded, then user-authored files are restored from a temporary backup.

## Prerequisites

| Requirement | Version |
| ----------- | ------- |
| Capacitor   | 6+      |
| Node.js     | 18+     |
| Xcode       | 15+     |
| CocoaPods   | installed (only used for verification before deletion) |

The project must be a Capacitor **app** (not a plugin) and must currently use CocoaPods (`ios/App/Podfile` exists).

## Procedures

### Step 1: Verify Project State
```
END THIRD-PARTY FILE 6460c450117e52b2

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

First 1924 of 15899 bytes. © capawesome-team · MIT · https://github.com/capawesome-team/skills/tree/HEAD/skills/capacitor-app-spm-migration/SKILL.md

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

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