Mobile Development

Use this skill for platform choice, cross-platform tradeoffs, and shared mobile concerns such as authentication, notifications, deep linking, release readiness, and policy checks. For deep native iOS implementation or rewrite work, route to software-ios-native. For native iOS build, install, packaging, or stale-app debugging, route to software-ios-runtime-debugging. For native Android implementation, route to software-android-native.

Quick Reference

When to Use This Skill

Use this skill when you need:

• Platform selection between native iOS, native Android, React Native, Flutter, Kotlin Multiplatform, and wrapper shells
• Cross-platform decisions across React Native, Expo, Flutter, Kotlin Multiplatform, and WebView shells
• Mobile auth, passkeys, push notifications, offline-first sync, deep links, and app-store release preparation

When NOT to Use This Skill

Platform Selection

Need to ship mobile product?
    │
    ├─ Single platform only?
    │   ├─ iOS → SwiftUI for new code, UIKit interop where needed
    │   └─ Android → Jetpack Compose for new code, Views interop where needed
    │
    ├─ Both iOS and Android?
    │   ├─ Native integrations / performance / platform fidelity dominate? → Separate native apps
    │   ├─ JS/TS team and fastest shared delivery? → React Native + Expo-managed for greenfield
    │   ├─ Fully shared rendering and custom UI control? → Flutter
    │   └─ Kotlin team, shared logic, native UI? → Kotlin Multiplatform
    │
    └─ Existing web app wrapper?
        ├─ Low-complexity shell → WebView / Capacitor
        └─ Meaningful native features → React Native or native modules

Cross-Platform Defaults

Workflow

1. Confirm product scope, platform targets, native requirements, and release constraints.
2. Route web-only, backend, or iOS-native deep dives to adjacent skills.
3. Choose the stack from the selection guidance above.
4. Apply guidance for auth, push, offline behavior, release gates, and testing.
   • For iOS push: prove the local sandbox path and the production path separately.
   • Treat push signoff as two gates: transport proof (notification accepted and shown) and open-path proof (tapping from cold start and warm start does not freeze or crash).
5. Re-check current platform-policy and framework facts before final recommendations.

Platform-Choice Proof Gate

Before committing to native, React Native, Flutter, or KMP, list the product's hardest likely capability: background execution, camera/media pipeline, Bluetooth/hardware SDK, widgets/extensions, deep links, offline conflict resolution, payments, accessibility, or platform-specific UI. Rank each candidate's uncertainty and consequence. Reuse existing evidence when it covers the same framework and version range, native dependency, release configuration, capability, and representative device class; record its date and owner.

Run a time-boxed spike only for serious finalists with a material unresolved native, performance, lifecycle, accessibility, or packaging risk. Define pass/fail before it: build and package, native SDK integration, cold-start and interaction budget, accessibility behavior, offline/recovery behavior, and maintainer skill. Use the real release configuration and the oldest device class relevant to that risk. If the spike consumes paid services, signing capacity, scarce devices, or shared CI quota outside the agreed task budget, obtain authorization for that resource use first. For low-risk products, a documented decision with applicable production evidence and explicit assumptions is sufficient. If the hardest capability fails or requires a permanent bespoke native module, include that module's two-platform ownership cost in the decision; if no hard capability exists, favor the stack that reduces duplicated product work.

Capability and Native Escape Hatches

Load cross-platform-comparison.md when weighing shared delivery against native ownership. Use this catalog to identify the native work the chosen stack still needs:

KMP iOS toolchain gate. Apple final binaries require a macOS host and Xcode even when business logic is shared. Read the Kotlin/Gradle/AGP/Xcode compatibility matrix for the project's Kotlin plugin and supported targets/hosts for device/simulator architectures. Choose direct Xcode integration or dependency-manager integration according to existing CocoaPods dependencies and module distribution needs; prove both a simulator build and a signed device archive.

Attestation gate. For sensitive server actions, evaluate App Attest and Play Integrity through the stack's native module/plugin. Verify results on the server and bind them to a fresh challenge or request content. Check device/API availability and release distribution before enforcing; define behavior for unsupported devices and outages. Attestation is an abuse signal, alongside authentication and authorization, and is not a universal store-submission requirement. Detailed threat modeling and secure storage belong to software-security-appsec.

Platform Delivery Gates

• iOS: Route architecture, state, concurrency and performance to software-ios-native. Check privacy manifests, required-reason APIs and SDK compliance before submission. Validate APNs transport and notification opening for each install environment; inspect the distribution archive's aps-environment entitlement and keep its token routing aligned with that environment.
• Android: Route Compose, state, background work and performance to software-android-native. Read the current Play target-API requirements for app type and release track, then verify Data safety, signing and background restrictions. Evaluate Play Integrity when abuse risk warrants it.

Release Operations, Traps, and Judgment Calls

iOS release-operation gates (TestFlight channels, upload path, backend-only fixes, real-device smoke proof, minimum Xcode/SDK for upload), known iOS and Android runtime traps, expert judgment calls, and the anti-pattern table live in references/platform-traps-and-judgment.md. Load it before a release cut, a push/open-path investigation, or a platform-choice recommendation.

• Before any archive/upload, check developer.apple.com/news/upcoming-requirements for the minimum Xcode/SDK; a passing local build can still be rejected at ingestion.
• Review account deletion, login-service requirements and subscription disclosures/cancellation under the applicable App Review clauses; auth alone does not make Sign in with Apple mandatory.

OTA Updates and External Payments

Both are store-policy decisions that change often. Decision logic, operating rules, and primary-page links are in references/store-update-and-payment-policy.md.

• OTA / code push. Check Apple Guideline 2.5.2 and its interpreted-code license clause separately from Google Play's interpreter exception. A JS bundle is not blanket permission to change functionality. Default to a store build for native changes or new features; use an OTA only after checking the applicable policy, runtime compatibility, staged rollout and rollback in the reference.
• External payments / anti-steering. US-storefront link-outs and regional alternative-billing or external-offer programs exist on both stores. Eligibility, entitlements, disclosure UI, and remaining fees vary by storefront and change after rulings. Decide per storefront from the Apple guidelines/StoreKit External Purchase pages and the Google Play Payments/billing-program pages at decision time. Branch server-side on the store-reported storefront and keep a kill switch back to store billing. Never quote a fee or date from memory.

Release Readiness Checklist

iOS App Store

• Icons, launch assets, and permission copy are complete
• Privacy manifest and required-reason APIs are correct for app targets and listed SDKs
• Third-party SDK compliance matches Apple's current requirements
• Accessibility, deep links, and push flows tested on current devices
• App Store metadata, privacy policy, and TestFlight coverage ready
• Full App Store Connect preparation — see references/app-store-connect-checklist.md

Google Play

• Target SDK meets the current Play target-API requirement (read the level and deadline on the Play target-SDK page; it moves every year)
• Privacy policy, content rating, and Data safety complete
• Signing, auth and background behavior tested under modern Android constraints; attestation tested if used
• Internal/closed/open tracks configured appropriately

Known Traps

• Assuming one mobile framework decision solves release, entitlement, deep-link, and push behavior without platform-specific proof
• Validating auth, push, or deep links only in local debug builds and treating that as production readiness
• Mixing sandbox, staging, and production mobile backends until install-specific behavior becomes impossible to reproduce
• Using emulator or simulator success as proof for background execution, notification delivery, or device-specific lifecycle
• Choosing a cross-platform stack before listing native integrations, extension points, and store-policy constraints that can force native escape hatches

Navigation

References

• references/ios-best-practices.md — native iOS owner pointers; load when handing off implementation
• references/android-best-practices.md — native Android owner pointers; load when handing off implementation
• references/cross-platform-comparison.md — React Native / Flutter / KMP / native tradeoffs
• references/deep-linking-guide.md — Universal Links, App Links, Expo Router, post-Dynamic-Links
• Mobile testing (layers, device matrix, snapshot/UI/E2E, flakes) is owned by qa-testing-mobile; start at test-layers-and-suite-anti-patterns.md
• references/offline-first-architecture.md — local-first storage, sync, conflict resolution
• references/push-notifications-guide.md — APNs, FCM, permissions, channels, analytics
• references/operational-playbook.md — release operations, decision tables, centralized patterns
• references/app-store-connect-checklist.md — App Store Connect field-by-field checklist
• references/store-update-and-payment-policy.md — OTA/code-push policy and external-payment / anti-steering decisions
• references/platform-traps-and-judgment.md — iOS release operations, platform traps, judgment calls, anti-patterns
• data/sources.json — current official and curated external sources

Shared Checklists And Utilities

• ../software-clean-code-standard/assets/checklists/mobile-release-checklist.md
• ../software-clean-code-standard/references/auth-utilities.md
• ../software-clean-code-standard/references/error-handling.md
• ../software-clean-code-standard/references/resilience-utilities.md
• ../software-clean-code-standard/references/testing-utilities.md
• ../software-clean-code-standard/references/clean-code-standard.md

Templates

• Cross-platform: assets/cross-platform/template-webview.md (WebView wrapper, iOS + Android)
• Native code lives with the native skills. For iOS, see networking-and-data-loading.md and swiftui-composition-patterns.md. For Android, see coroutine-and-compose-recipes.md. For Keychain and Keystore storage, see template-mobile-security.md.

Related Skills

• software-ios-native — Native iOS 17+ implementation, rewrites, and agent workflows
• software-ios-ai-engine — Apple Foundation Models, local AI engines, on-device retrieval
• software-ios-runtime-debugging — Build/install/launch proof, simulator drift, packaging triage
• software-ios-design — Native iOS visual hierarchy, HIG, screenshot review
• software-android-native — Native Android, Kotlin, Jetpack Compose, agent workflows
• software-android-design — Material Design 3, screenshot review
• software-android-runtime-debugging — Android build/install/launch proof, emulator drift
• software-frontend — Web UI and shared product surfaces
• software-backend — API design, auth, backend contracts
• software-baas-platforms — Supabase, Firebase, Appwrite, PocketBase
• qa-testing-strategy — CI gates, reliability, release confidence
• qa-resilience — Network resilience and failure-mode design
• qa-testing-ios — iOS-specific testing
• software-ui-ux-design — Mobile UX and accessibility

Release Lookups

Before a release recommendation, read Apple's upload/SDK and third-party SDK requirements, Google's target-API policy, and the installed framework's upgrade notes using data/sources.json. An unreachable submission gate is unverified and blocks a readiness claim. Source-list edit dates do not establish that every page was checked.

Learnings Loop

When prior decisions or pitfalls are relevant, consult learnings.consolidated.md if present; use learnings.md only for needed history or as the available fallback. Otherwise skip both.

After applying it, if you encountered a pattern worth remembering, a mistake worth preventing, or a domain fact that surprised you, append one dated bullet to learnings.md via agents-skills-feedback-loop/scripts/append_learning.py. Do not modify SKILL.md itself.