capgo-native-builds
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).
- Installs
- 713
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/cap-go/capgo-skills --skill capgo-native-builds- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads capgo-native-builds automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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 anybuild credentials ...subcommand. - A Capgo build fails on signing, provisioning, keystore, prescan, or store upload.
Do not use when:
- Only JavaScript/web assets change. That is an OTA release: use
capgo-release-management, orcapgo-live-updatesfor plugin wiring. - The user builds locally in Xcode or Gradle, or on their own CI runners without Capgo Build. Use
capacitor-ci-cd. - The user needs store listing, metadata, or review prep. Use
capacitor-app-storeandcapacitor-apple-review-preflight. - The user is upgrading Capacitor itself. Use
capacitor-app-upgrades.
Reference Index
Only load a reference when its topic is in play.
| File | Load when |
|---|---|
references/request-options.md | Building the exact build request flags: store submission, tracks, release notes, versioning, cache, Xcode version, prescan flags |
references/credentials-and-ci.md | Saving, updating, exporting, or migrating credentials, and pushing them into CI secrets |
Secrets and Confirmation
- Never ask the user to paste a Capgo API key, signing password,
.p8key, keystore, or service-account JSON into the chat. Ask them to runnpx @capgo/cli@latest loginthemselves (it opens the browser or asks for the key in a masked prompt), or to setCAPGO_TOKENin their shell or CI secret store. - Do not put secrets in command arguments: they end up in shell history and process lists. Use environment variables, the saved login, or the CLI's interactive prompts.
- If a secret appears in the conversation anyway, do not repeat it, do not write it to a file, and tell the user to revoke it and create a new one.
npx @capgo/cli@latestdownloads and runs the newest CLI from npm. Run it only inside the user's project and with their go-ahead. In CI, pin an exact version.- Ask before any command that changes remote state: uploading a bundle, changing or promoting a channel, deleting apps, bundles, channels, or keys, requesting a build that uploads to a store, and exporting or deleting credentials. Say what will change and for which app and channel.
Operating Rules
- Use
npx @capgo/cli@latestin user-facing commands. - API keys, P12 passwords, keystore passwords,
.p8keys, and Play service-account JSON are secrets. Use placeholders in examples. Never ask for them in the chat and never echo them back. If one is pasted into the chat, tell the user to revoke it and create a new one. - Credentials are stored locally (
~/.capgo-credentials/credentials.json, or.capgo-credentials.jsonwith--local). They are uploaded only for the build job, and the temporary server copies are deleted when the build finishes. Never commit either file. - Confirm these before requesting: platform, app ID, project path, flavor or scheme, and destination (store upload, download link, or both).
Auth and API-key precedence
The CLI resolves the key in this order:
-a, --apikey <key>on the command- The
CAPGO_TOKENenvironment variable ~/.capgo, the global key saved bynpx @capgo/cli@latest login./.capgo, the project key saved bylogin --local
Trap: a global key wins over a project-local key. If a repository must use a different org's key, set CAPGO_TOKEN. Make sure .capgo is git-ignored.
Procedure
1. Inspect
ls ios androidand confirm the target native folder exists andnpx cap sync <platform>has run.- Read
capacitor.config.*forappId. It must match the iOS bundle ID and AndroidapplicationId(prescan checkshared/bundle-id-consistency). - iOS: check the Xcode scheme and target names (default
App) and any extensions that need their own provisioning profiles. - Android: check
android/app/build.gradleforproductFlavors. If there is more than one flavor,--android-flavoris required. - Check that the app exists:
npx @capgo/cli@latest app list. Add it withnpx @capgo/cli@latest app add com.example.app.
2. Decide whether a native build is needed at all
npx @capgo/cli@latest build needed com.example.app --channel production
# prints "yes" and exits 1 -> native build required
# prints "no" and exits 0 -> ship OTA instead
# exits 2 -> the command itself failed
It compares native package metadata only. Raw edits under ios/ or android/ still need a native build.
3. Set up credentials
First build, interactive (preferred):
npx @capgo/cli@latest build init # alias: build onboarding
- iOS: verifies or creates the App Store Connect API key, then creates or reuses the certificate, bundle ID, and App Store provisioning profiles. It saves everything locally and can fire the first build. Progress persists under
~/.capgo-credentials/onboarding/, so the user can resume. - Android: sets up the keystore. Google OAuth then provisions a GCP service account and sends the Play Console invite.
- macOS helper for the
.p8key:npx @capgo/cli@latest build credentials apple-key --appId com.example.app.
When the user already has signing files, use build credentials save instead. See references/credentials-and-ci.md.
4. Pre-flight
npx @capgo/cli@latest build prescan com.example.app --platform ios
Prescan runs automatically inside build request. Run it alone to fix problems before you upload anything. If one finding is intentional, skip only that check: --prescan-skip <check-id>. Avoid --no-prescan.
5. Request the build
# App Store / TestFlight (default ios distribution app_store)
npx @capgo/cli@latest build request com.example.app --platform ios --path .
# Android to Play internal track (default track internal, status draft)
npx @capgo/cli@latest build request com.example.app --platform android --path .
# Artifact only, no store upload
npx @capgo/cli@latest build request com.example.app --platform ios --ios-distribution ad_hoc --output-upload --output-retention 2d
npx @capgo/cli@latest build request com.example.app --platform android --no-playstore-upload --output-upload
The --output-retention range is 1h to 7d. The default TTL saved in credentials is 1h.
Traps
- Xcode / Capacitor 9: the Capgo Build docs list macOS Tahoe 26.2 with Xcode 26.2. You can pin with
--xcode-version <major[.minor]>(orCAPGO_IOS_XCODE_VERSION). Capacitor 9 needs Xcode 27+. Capgo's docs and CLI 8.77 do not confirm an Xcode 27 builder. Before promising a Capacitor 9 iOS cloud build, check with--xcode-version 27or current docs. --no-playstore-uploadrequires--output-upload. Otherwise the build has no destination.- Ad hoc iOS skips the store. Use it with
--output-uploadwhen the App Store record does not exist yet. --submit-to-store-reviewchanges the Android defaults to theproductiontrack with statuscompleted. Confirm with the user before you add it.- Build numbers auto-increment by default. If the project owns build numbers, add
--skip-build-number-bump. Marketing versions can also auto-bump (--skip-marketing-version-bumpturns this off). - Build timeout defaults to 15 minutes. Raise it with
npx @capgo/cli@latest app set com.example.app --build-timeout-minutes 60(range 5 to 360). server.urlleft incapacitor.config(live reload) fails prescanios/capacitor-server-url-shippedfor store builds. Remove it rather than skipping the check.
Verification
npx @capgo/cli@latest build credentials list --appId com.example.appshows masked credentials for the target platform.npx @capgo/cli@latest build prescan com.example.app --platform <p> --fail-on-warningsexits 0.build requestends with a success status. With--output-uploadit prints a download link and QR code. With--output-record /tmp/build.json, checknpx @capgo/cli@latest build last-output --path /tmp/build.json --field outputUrl.- Store path: the build appears in TestFlight or the Play Console track you chose.
- Install the artifact on a device and check the version and build number.
Error Handling
| String / symptom | Fix |
|---|---|
No Capgo API key found. Run ... first, then retry this command. | The user runs npx @capgo/cli@latest login, or sets CAPGO_TOKEN |
Insufficient permissions for <key> / prescan shared/apikey-permission | The key's role cannot request native builds for this app or org. Use a key with build rights |
Missing required argument: --platform <ios|android> | Add --platform ios or --platform android |
❌ No credentials found for this app and platform | Run build init or build credentials save --appId <id> --platform <p> .... Check --local versus the global store |
Legacy provisioning profile format detected. Run: npx @capgo/cli build credentials migrate --platform ios | Run npx @capgo/cli@latest build credentials migrate --platform ios |
Missing argument, you need to provide a appId, or be in a capacitor project | Pass the app ID positionally or run from the app root |
output-retention must be a number with optional unit: s, m, h, d | Use 1h, 6h, 2d, and so on (max 7d) |
Prescan ios/cert-profile-pairing / ios/profile-type-vs-mode | The profile does not embed the certificate or does not match app_store/ad_hoc. Regenerate it with build credentials ios-provisioning |
Prescan ios/targets-covered | An extension has no profile. Add --ios-provisioning-profile <bundleId>=<path> |
| Android "Key alias not found" / wrong password | Check the alias and passwords. If they differ, pass both --keystore-key-password and --keystore-store-password |
| Multiple flavors error | Add --android-flavor <flavor> |
| Need diagnosis | Re-run with --verbose. --ai-analytics sends the failure logs to Capgo AI. --send-logs-to-support sends them to support |
More fixes: https://capgo.app/docs/builder/troubleshooting/
Supporting Docs
- Build reference: https://capgo.app/docs/cli/reference/build/
- Getting started: https://capgo.app/docs/builder/getting-started/
- iOS: https://capgo.app/docs/builder/ios/ · Android: https://capgo.app/docs/builder/android/
- Credentials: https://capgo.app/docs/builder/credentials/ · Prescan: https://capgo.app/docs/builder/prescan/
- OTA vs native in CI: https://capgo.app/docs/builder/ci-ota-or-native/
FAQ
What does the capgo-native-builds skill do?
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).
How do I install capgo-native-builds?
Run npx skills add https://github.com/cap-go/capgo-skills --skill capgo-native-builds in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/capgo-native-builds/ (personal) or .claude/skills/capgo-native-builds/ (project).
Which AI agents can use capgo-native-builds?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is capgo-native-builds safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains capgo-native-builds?
It is published by cap-go in cap-go/capgo-skills. It has 713 recorded installs.
More from cap-go/capgo-skills
capacitor-best-practices
cap-go/capgo-skills
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 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).
ionic-design
cap-go/capgo-skills
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).
capacitor-plugins
cap-go/capgo-skills
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).
debugging-capacitor
cap-go/capgo-skills
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::ERRCLEARTEXTNOTPERMITTED, 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 openurlprivacypush, xcrun devicectl device process launchopenURL, 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).
capacitor-testing
cap-go/capgo-skills
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 NATIVEAPP / 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
safe-area-handling
cap-go/capgo-skills
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).
Popular mobile skills
design-mobile-apps
designed-by-ai/skills
Design mobile app screens with Sleek, edit Sleek projects, and implement their designs in React Native or HTML.
ios-design
uizze.sh
Design and review iOS UI/UX for iPhone apps in SwiftUI, UIKit, or React Native. Use for mobile app design, screen redesigns, navigation flows, typography, forms, keyboard and safe-area layout, and accessibility checks. Apply Apple Human Interface Guidelines and consult real product references through the optional Uizze connection.
vercel-react-native-skills
vercel-labs/agent-skills
React Native and Expo best practices for building performant mobile apps. Use when building React Native components, optimizing list performance, implementing animations, or working with native modules. Triggers on tasks involving React Native, Expo, mobile performance, or native platform APIs.
animate-expo
emilkowalski/skills
Build animations in React Native and Expo, making the decisions in the order that determines whether they feel right — should it animate, which thread it runs on, which properties, spring or timing, how the gesture hands off, how it degrades. Writes the implementation with Reanimated, Gesture Handler, Expo Router and expo-haptics. Use when animating anything in an Expo app, adding gestures, sheets, screen transitions, press feedback or haptics, or fixing motion that stutters on device. For web animation use animate.
xcode-project-setup
firebase/agent-skills
Safely modifies Xcode projects (.pbxproj) to add Swift Packages and link files. Use this skill whenever an iOS project needs dependencies installed (e.g. Firebase, Alamofire).
firebase-remote-config-basics
firebase/agent-skills
Manages Firebase Remote Config templates, feature flags, loading strategies, and SDKs (Android, iOS). Use when downloading/deploying remoteconfig JSON templates, managing version history/feature flags, setting in-app defaults, fetchAndActivate(), real-time listeners, or SDK setup. Don't use for Firebase Hosting, Auth, Firestore, Data Connect, Crashlytics, or App Hosting.