Come usare gli agenti AI nello sviluppo di app Capacitor

Per usare agenti AI nello sviluppo di app Capacitor, devi dare all'agente due cose che gli mancano di default: la conoscenza procedurale del lato nativo di Capacitor, tramite skill installabili skills, e tool live, tramite server MCP e un CLI che può eseguire. Con le skill Capacitor open-source di Capgo e i server MCP Capgo, un agente come Claude Code, Codex o Cursor può aggiungere plugin con la giusta configurazione nativa, debuggare build iOS e Android, richiedere cloud build e fare l'upload di live update.

Questa guida spiega perché gli agenti generalisti sbagliano con Capacitor, come configurare skill e MCP con pochi comandi, i prompt per ogni fase del ciclo di vita dell'app e i guardrail che ne garantiscono la sicurezza.

Perché gli agenti generalisti faticano con Capacitor

Gli agenti sono forti sul web code. Un progetto Capacitor aggiunge una seconda metà che cambia ogni anno:

• Disallineamento delle versioni. Capacitor ha modificato 8 livelli di SDK Android, usa Swift Package Manager di default per nuovi progetti iOS e richiede Xcode 26 per gli upload su App Store. I dati di training mixano Capacitor da 3 a 8 consigli.
• Configurazione nativa tra i file. Un singolo plugin può richiedere Info.plist chiavi, entitlements, AndroidManifest.xml permessi, modifiche Gradle e un cap syncSpesso gli agenti fanno solo la parte JavaScript.
• Scelta dei plugin. Molti plugin della community non sono più mantenuti. Un agente sceglie ciò che ha visto più spesso, non ciò che funziona su Capacitor 8.
• Errori invisibili. Gli errori si trovano in Xcode, Logcat o nei log della CI, non nell'editor.

Lo risolvi con contesto che l'agente può caricare on demand e tool che può chiamare invece di tirare a indovinare.

Il toolkit: skill, MCP e CLI

Installa le skill

bunx skills add Cap-go/capgo-skills

L'installer rileva gli agenti supportati e posiziona le skill dove ciascuno le cerca. Il set include la selezione dei plugin, best practice, Capacitor upgrade principali di app e plugin (incluso da v7 a v8), migrazione da CocoaPods a SPM, debugging, log iOS e Android, notifiche push, deep link, safe areas, scansione di sicurezza, testing, CI/CD, preflight App Store, migrazioni da Cordova e web app, Capgo live updates e Capgo Native Build. La pagina delle skill elenca ogni singola skill.

In Claude Code puoi anche usare il marketplace dei plugin:

claude plugin marketplace add Cap-go/capgo-skills
claude plugin install capgo-cloud@capgo-skills

Connetti i server MCP

Il server ospitato non richiede installazione. Aggiungilo a Claude Code e accedi tramite OAuth quando richiesto:

claude mcp add --transport http capgo https://api.capgo.app/mcp

Il server CLI gira localmente via stdio e usa il tuo login Capgo, quindi effettua prima l'accesso:

bunx @capgo/cli@latest login
claude mcp add capgo -- bunx @capgo/cli@latest mcp

Per gli editor che usano una config JSON (Cursor, Windsurf, Claude Desktop), l'equivalente è:

{
  "mcpServers": {
    "capgo": {
      "command": "bunx",
      "args": ["@capgo/cli@latest", "mcp"]
    }
  }
}

L'MCP CLI espone tool come capgo_upload_bundle, capgo_list_channels, capgo_update_channel, capgo_check_compatibility, capgo_request_build, capgo_doctor, e capgo_get_stats. L'elenco completo è nella Riferimento MCP CLI, e il pagina MCP spiega quale server utilizzare e quando.

Utilizzo degli agenti durante l'intero ciclo di vita Capacitor

Specifica la skill nel prompt. In questo modo l'agente caricherà la procedura corretta invece di improvvisare.

1. Trasforma una web app in un'app Capacitor

Use the webapp-to-capacitor skill to add Capacitor 8 with iOS and Android
to this Vite + React app. Keep the existing build output folder.

L'agente installa @capacitor/core e il CLI, imposta webDir, aggiunge le piattaforme ed esegue la prima sincronizzazione. Per i progetti Cordova esistenti, usa cordova-to-capacitor. Per Next.js, Nuxt o simili, usa framework-to-capacitor, che gestisce le impostazioni di export statico.

2. Aggiungi funzionalità native con il plugin corretto

Use the capacitor-plugins skill to add biometric login.
Pick a plugin that supports Capacitor 8, configure iOS and Android,
and show me the usage code.

L'IA conosce i canali ufficiali @capacitor/* package e il directory dei plugin di Capgo, così l'agente sceglie un plugin mantenuto e aggiunge le Info.plist string di utilizzo, permessi Android e passaggio di sincronizzazione. Esamina la diff come una normale pull request.

3. Debug con log reali

Use the ios-android-logs skill to capture Logcat while I reproduce the crash
on the connected Android device, then use debugging-capacitor to find the cause.

La skill dei log fornisce all'agente gli esatti adb e i comandi Xcode per streamare e filtrare i log del dispositivo, così legge lo stack trace reale invece di tirare a indovinare dal codice.

4. Aggiorna Capacitor e migra a SPM

Use the capacitor-app-upgrade-v7-to-v8 skill to upgrade this app.
Stop and show me the plan before changing native files.

Poi, se il tuo progetto iOS usa ancora CocoaPods:

Use the cocoapods-to-spm skill to move the iOS project to Swift Package Manager.

Chiedere prima un piano è una buona abitudine per ogni modifica che tocca ios/ o android/. Per la versione manuale dello stesso lavoro, consulta la nostra guida all'aggiornamento a Capacitor 8 e il Guida alla migrazione SPM.

5. Verifica sicurezza e prontezza per lo store

Use the capacitor-security skill to scan this project and fix high severity issues.
Then run the capacitor-apple-review-preflight skill before I submit.

I preflight check verificano le cause più comuni di rifiuto: stringhe di utilizzo mancanti, lacune nel privacy manifest, requisiti Sign in with Apple e problemi di metadati.

6. Build iOS e Android nel cloud

Salva le tue credenziali di firma una sola volta, non tramite l'agente:

bunx @capgo/cli@latest build credentials save --platform ios \
  --certificate ./cert.p12 --p12-password "..." \
  --ios-provisioning-profile ./profile.mobileprovision \
  --apple-key ./AuthKey.p8 --apple-key-id "KEY_ID" \
  --apple-issuer-id "ISSUER_ID" --apple-team-id "TEAM_ID"

Le credenziali sono salvate localmente in ~/.capgo-credentials/credentials.json (o .capgo-credentials.json con --local, che dovresti aggiungere al .gitignore), inviate per la build e cancellate da Capgo al termine della build. A quel punto l'agent può lavorare in autonomia:

Use the capgo-native-builds skill to request an iOS release build from the
current working directory, then read the logs and fix any build error.

Che corrisponde a:

bunx @capgo/cli@latest build request com.example.app --platform ios --path .

Perché --path . carica la working tree, l'agente può iterare su un errore di build iOS da Windows o Linux senza committare fix speculativi. Maggiori info su Build Capgo. Se ti servono prima i certificati, Generatore di certificati iOS ti aiuta.

7. Distribuisci una hotfix come live update

Use the capgo-live-updates skill to build the web app and upload it to the
beta channel. Check native compatibility first.

L'agente esegue la build, quindi:

bunx @capgo/cli@latest bundle upload --channel=beta

Il controllo di compatibilità confronta le dipendenze native con quelle installate sui dispositivi, evitando che l'agente carichi un bundle che richiede un plugin nativo assente nella build dello store. Passa alla produzione solo dopo i test in beta. Vedi come funzionano gli Capgo live updates.

Guardrail per garantire la sicurezza dell'agente

• Pianifica prima di apportare modifiche native. Chiedi un piano e un diff per tutto ciò che riguarda ios/ e android/.
• Tieni i segreti fuori dalla conversazione. Salva tu stesso le credenziali di build e le chiavi API, escludi i file delle credenziali da git e non incollare mai chiavi nei prompt.
• Usa i canali come rete di sicurezza. Lascia che l'agente faccia l'upload su un canale beta o interno. Promuovi tu in produzione.
• Affidati al rollback. Capgo riporta il dispositivo all'ultimo bundle funzionante se quello nuovo non si avvia, limitando i danni di un upload sbagliato.
• Preferisci comandi verificabili. I comandi CLI qui sopra sono facili da leggere nei log dell'agente. Se non sei sicuro di cosa abbia fatto uno strumento MCP, chiedi all'agente di mostrarti il comando CLI equivalente.
• Lascia le submission agli store a una persona. Gli agenti possono preparare build e metadati. L'invio in revisione e le risposte ai reviewer devono restare in mano a una persona.

Risoluzione problemi

L'agente ignora la skill. Specificala nel prompt e verifica che sia stata installata per quell'agente (riesegui bunx skills add Cap-go/capgo-skills).

Mancano gli strumenti MCP. Per il server CLI, conferma che bunx @capgo/cli@latest login abbia avuto successo nello stesso ambiente in cui gira l'agente. Riavvia l'agente dopo aver aggiunto un server.

L'agente suggerisce API Capacitor obsolete. Comunica la tua versione di Capacitor e fagli cercare nella documentazione tramite lo strumento capgo_search_docs MCP ospitato.

La build cloud fallisce in fase di signing. Le credenziali mancano o il provisioning profile non corrisponde al bundle ID. Salva nuovamente le credenziali e riesegui la richiesta di build.

Upload rifiutato per incompatibilità. Il bundle richiede modifiche native. Pubblica prima una build per lo store, poi il live update.

In sintesi

Gli agenti AI diventano utili per Capacitor quando smettono di tirare a indovinare. Installa le skill Capacitor così seguono le procedure corrette, connetti il Capgo MCP pubblico per la documentazione e il CLI MCP per le azioni sull'account, e mantieni alcuni guardrail su modifiche native, segreti e canali di produzione. Per saperne di più su come integrare funzionalità AI nell'app stessa, leggi perché Capacitor è ideale per le app mobile AI.