software-ios-native

Native iOS Development

Use this skill for native iOS work only. It is the default shared-skill entrypoint for SwiftUI-first iOS 17+ apps, bounded rewrites from older codebases, and agent-assisted workflows in Xcode, Codex, and Claude Code.

Quick Reference

When to Use This Skill

SwiftUI-first iOS 17+ screens, app skeletons, UIKit bounded rewrites, agent-assisted Xcode/Codex/Claude Code workflows, Swift Concurrency, SwiftData/Core Data persistence, Xcode build optimization, privacy manifests, release gates, and native iOS code review.

Defaults

• UI: SwiftUI-first; UIKit interop only where Apple APIs require it.
• State: @Observable + main actor isolation (iOS 17+).
• New projects: SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor (Xcode 26+); nonisolated/@concurrent only when breaking out.
• Async: structured concurrency + async/await; detached tasks only when intentionally breaking inheritance.
• Tests: Swift Testing for unit/integration; XCTest/XCUITest for UI automation.
• Release gates: privacy manifests, required-reason APIs, SDK compliance, accessibility, real-device verification — non-optional. Verify minimum Xcode version at developer.apple.com/news/releases each release cycle.

Version Currency (check every session)

• Current stable (verify at each session): iOS/iPadOS 26.x, Xcode 26.6, Swift 6.3. App Store Connect has rejected uploads not built with the iOS 26 SDK since 2026-04-28 — this gate does not change your deployment target, only the build SDK.
• Announced, not shipped: WWDC26 (June 2026) previewed iOS/iPadOS/macOS 27 and Xcode 27 (Swift 6.4, on-device AI code completion, agent skills bundled with Xcode). As of this session Xcode 27 is beta-only. Do not recommend Xcode 27/iOS 27 APIs for anything shipping to the App Store; treat every "iOS 27" claim as provisional until Apple's GA release notes confirm it, and re-verify the current stable/beta split before quoting a specific point release — these move every few weeks.
• Point releases (26.2 vs 26.4 vs 26.6) drift fast; treat any specific point-release number in this skill as the value observed at last validation, not a permanent fact.

Expert Judgment Calls

• SwiftUI vs UIKit: default to SwiftUI. Reach for UIKit interop only for a named capability gap (e.g., precise text-kit control, certain camera/AR compositions, legacy UICollectionView compositional layouts not yet matched in SwiftUI) — not because a contributor is more comfortable in UIKit. Re-evaluate the gap list each Xcode cycle; SwiftUI closes gaps yearly and yesterday's justified UIKit escape hatch is often removable.
• Strict concurrency adoption: for a new project, take the Xcode 26 defaults (Approachable Concurrency on, SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor, Strict Concurrency Checking = Complete) — migration pain is close to zero because there is no legacy code to fight. For an existing pre-Swift-6 codebase, do not flip strict concurrency in one PR: enable it module-by-module or file-by-file, starting from leaf types with no dependents, and budget real calendar time — the Swift Forums "explosion of isolation violations" reports are the normal experience, not a sign something is wrong. Never bulk-silence with @preconcurrency as a substitute for doing the migration.
• Dependency management: Swift Package Manager is the default for every new dependency and for new projects outright. Only keep CocoaPods where an existing project already depends on it and the migration cost (Pods with no SPM manifest, deeply nested transitive Pod dependencies) currently exceeds the maintenance tax of running two package managers. Don't introduce a new CocoaPods dependency into an SPM-only project to save a day of integration work — it reintroduces the exact tooling fragmentation SPM removed.
• Modularization threshold: don't split into SPM modules pre-emptively. Splitting pays off once a target exceeds roughly 150-200 files, once independent teams need to build/test in isolation, or once agent-driven workflows need a bounded package to avoid loading the whole app graph for one feature. Below that, module boundaries add build-graph and API-surface overhead without a compiler-enforced win. See xcode-build-optimization.md → SPM Dependency Analysis for the build-time tradeoffs either way.
• TestFlight and phased release discipline: never promote straight from internal build to a 100% production release. Run at least one external TestFlight wave sized to catch device/OS-version variance, then use phased release (7-day ramp) for production so a bad build caps its blast radius before full rollout. Treat a skipped phased release as a release-risk finding worth calling out, not a minor process nit.

ASCII Flow

iOS native task
  -> Confirm app shape: SwiftUI, UIKit interop, service, or release gate
  -> Prove Xcode, simulator/device, build, install, and launch reality
  -> Choose architecture: Observation, concurrency, persistence, navigation
  -> For reusable skeletons, add iCloud data, App Intents, local AI/retrieval hooks, and release gates
  -> Implement bounded slice with tests and privacy/accessibility checks
  -> Check Swift, StoreKit, signing, privacy, and App Store traps
  -> Build, run, inspect logs/screenshots, and report proof

Runtime Truth And Prompting

Proof-first: verify tool reality (Xcode assistant → XcodeBuildMCP → Apple CLI), prove build+launch before UI diagnosis, require bounded slices with explicit proof artifacts. Load references/runtime-proof-and-prompts.md for agent defaults, proof rules, execution loop, and prompt shape.

Rewrite Workflow

1. Lock the baseline: existing app behavior, minimum OS, device classes, external integrations, and non-goals.
2. Choose the target defaults: SwiftUI-first, iOS 17+, Observation, Swift Concurrency, Swift Testing, XCTest/XCUITest.
3. Slice the rewrite into bounded vertical features: app shell, auth/session, core navigation, feature flows, integrations, release surfaces. XcodeGen: run scripts/generate-xcodeproj.sh after adding new files. .pbxproj projects: register new files in target membership explicitly.
4. For each slice, require evidence: build success, run success, targeted tests, parity notes, and known gaps.
5. Keep release-only concerns visible throughout: privacy manifests, entitlement changes, required-reason APIs, push, store metadata. Push QA: sign off sandbox (device) and production (TestFlight) paths separately; validate cold-start tap, warm resume, and normal reopen.
6. End every batch with a handoff: changed behavior, validation performed, residual risk, next slice.
7. When a backend change eliminates an error class, immediately remove the now-impossible error types, decoders, and UI states from the iOS client.

Specialized Patterns

Load references/ui-and-integration-patterns.md for Canvas/gesture/immersive surfaces, auth/onboarding/Supabase integration gotchas, and StoreKit 2 billing + server-notification rules.

Release Signing And Distribution

• Release signing gate: disable auto-signing, set Signing Certificate = Apple Distribution + App Store Connect provisioning profile. Turning auto-signing off alone doesn't fix archive.
• Valid distribution archive must show aps-environment = production, get-task-allow = false, beta-reports-active = true. Still see development or get-task-allow = true → archive is dev-signed; not ready for TestFlight.
• Inspect the exact newest .xcarchive; don't use a generic find ... .app that can hit an older one.
• In Organizer choose App Store Connect for TestFlight/App Review — not Release Testing.
• Validation can fail on generated Info.plist (e.g., missing UISupportedInterfaceOrientations~ipad); review generated plist, not just UI.
• Encryption prompt: Apple/system crypto only → None of the algorithms mentioned above. Suppress with ITSAppUsesNonExemptEncryption = NO in plist.

Known iOS Traps

Full trap table (31 rows) in references/ios-traps-and-scenarios.md. Top traps by crash frequency and silent-failure risk:

Web-search _performBlockAfterCATransactionCommitSynchronizes: before code review (private symbol). dataCorrupted + <!DOCTYPE html> = API routing/auth bug, not push crash. Never bulk-silence Swift 6 errors with @preconcurrency. Detailed recipes in swift-concurrency-crash-triage.md.

When NOT to Use This Skill

Use a different skill when:

• Cross-platform or platform-choice decisions → software-mobile
• iOS build/install/launch failures, stale installs, simulator drift, XcodeGen issues → software-ios-runtime-debugging
• iOS test execution, simulator flake control, xcresult triage → qa-testing-ios
• Web UI or browser app implementation → software-frontend
• General architecture without iOS-specific constraints → software-architecture-design
• iOS visual design, HIG layout/typography, dark mode design, dashboard patterns → software-ios-design

Scenarios

Full recipes (S1–S5) in references/ios-traps-and-scenarios.md.

Navigation

References

Templates

Related Skills

Freshness Protocol

Freshness-check before final answers on Xcode/SwiftUI/Swift Testing changes, XcodeBuildMCP setup, iOS privacy manifests, App Store requirements, or any "is X still the default?" question. Start from data/sources.json, then Apple Developer docs and WWDC sessions.

Fact-Checking

Version-specific crashes, regressions, and workarounds must be verified against current primary sources. Prefer Apple docs/release notes for Xcode/SwiftUI/privacy/store; official Anthropic/OpenAI docs for Codex/Claude Code; XcodeBuildMCP repo for tool names and config. Remove claims that are not source-backed.

Learnings Loop

Before non-trivial tasks: read learnings.consolidated.md (and learnings.md if present). After: append one dated bullet to learnings.md via agents-skills-feedback-loop/scripts/append_learning.py. Do not modify SKILL.md.