Native Mobile Skills

---
name: native-mobile-skills
description: "Use when the work is native Android or native Apple-platform code — Kotlin, Jetpack Compose, Gradle/AGP, Android manifests and intents, R8, Swift, SwiftUI, UIKit, SwiftData, Xcode, an iOS/iPadOS/watchOS/visionOS target, an emulator or a simulator. Routes the task to the pinned vendor skill that holds current platform guidance, installs it with the vendor's own installer, and keeps the Agent Compass validation and visual-proof gates in force. Triggers: android app, jetpack compose, kotlin, gradle, AGP upgrade, R8, edge-to-edge, insets, navigation 3, swiftui, liquid glass, swift concurrency, swiftdata, storekit, widgetkit, xcodebuild, app store submission, ios simulator, android emulator."
risk_level: low
writes_files: false
requires_tools: []
version: 1.0.0
---

# Native Mobile Skills

Platform APIs for Android and Apple move on a yearly release train. A model's
memory of them is stale by construction: it predates the current SDK, and it
blends deprecated patterns with current ones because both appear in its training
data. Two external corpora fix that, and Agent Compass tracks both by pinned
commit.

This skill is the routing procedure. It does not hold platform guidance — it
finds the vendor skill that does.

| Corpus | Covers | Licence |
| ------ | ------ | ------- |
| <https://github.com/android/skills> | 22 skills: Compose, navigation, AGP, R8, profiling, insets, intents, credentials, Wear, TV, XR, Play | Apache-2.0, Google LLC |
| <https://github.com/dpearson2699/swift-ios-skills> | 86 skills: SwiftUI, Swift language and concurrency, SwiftData, Apple frameworks, App Store, profiling | PolyForm Perimeter 1.0.0, source-available with a noncompete term |
| <https://github.com/Dimillian/Skills> | 16 skills, of which 5 are Apple craft: SwiftUI composition patterns, Liquid Glass, view refactoring, performance audit, Swift 6.2 concurrency | MIT, Thomas Ricouard |

The third corpus is a practitioner's, not a vendor's: it answers "how a shipping
SwiftUI app is structured" where the second answers "which API". Both publish a
skill named `swiftui-liquid-glass`, and they install to the same directory —
choose one per project.

No corpus is copied into Agent Compass, so a skill is installed from its
source when a task needs it. This file carries everything needed to do that. The
pinned inventories and the licence reasoning live in the compass tree, at
[`docs/tooling/native-mobile-skills.md`](../../docs/tooling/native-mobile-skills.md)
— useful when you have that tree, not required to use this skill.

## Procedure

### 1. Confirm the work is native

| Signal | Platform |
| ------ | -------- |
| `settings.gradle` / `settings.gradle.kts`, `AndroidManifest.xml`, `*.kt` | Android |
| `*.xcodeproj`, `*.xcworkspace`, `Package.swift`, `Podfile`, `*.swift` | Apple |
| An `expo` or `react-native` dependency | **Not** this skill — use `expo-react-native-patterns` |

An Expo or React Native project contains `android/` and `ios/` directories. Those
are generated output. Route React Native work to
[`expo-react-native-patterns`](../expo-react-native-patterns/SKILL.md), and use
this skill only for the native module or the native build problem underneath it.

### 2. Pick one skill, not the corpus

Pick the narrowest skill that covers the task. Eighty-six skills do not fit in a
context window, and a corpus loaded wholesale buries the one file that mattered.

| Task | Corpus | Skill |
| ---- | ------ | ----- |
| Compose layout across window sizes | Android | `adaptive` |
| Compose theming and custom styles | Android | `styles` |
| Move XML views to Compose | Android | `migrate-xml-views-to-jetpack-compose` |
| Navigation, deep links, back stacks | Android | `navigation-3` |
| Insets, system bars, IME overlap | Android | `edge-to-edge` |
| Shrink the app, audit R8 keep rules | Android | `r8-analyzer` |
| Android Gradle Plugin 9 upgrade | Android | `agp-9-upgrade` |
| Intent and export-surface security | Android | `android-intent-security` |
| Test harness setup | Android | `testing-setup` |
| Jank or startup regression | Android | `android-profiler` |
| Wear OS, Android TV, XR glasses | Android | `wear-compose-m3`, `leanback-to-compose-tv-migration`, `display-glasses-with-jetpack-compose-glimmer` |
| Camera capture | Android | `camerax` |
| Play billing, Play policy, Engage | Android | `play-billing-library-version-upgrade`, `play-policy-insights`, `engage-sdk-integration` |
| SwiftUI screen structure and state | Apple | `swiftui-patterns` |
| iOS 26 Liquid Glass adoption | Apple | `swiftui-liquid-glass` |
| SwiftUI navigation | Apple | `swiftui-navigation` |
| Swift concurrency and data races | Apple | `swift-concurrency` |
| Local persistence | Apple | `swiftdata`, `core-data` |
| Networking layer | Apple | `ios-networking` |
| Tests | Apple | `swift-testing` |
| In-app purchase, subscriptions | Apple | `storekit` |
| Widgets, Live Activities | Apple | `widgetkit`, `activitykit` |
| Push notifications | Apple | `push-notifications` |
| Accessibility audit | Apple | `ios-accessibility` |
| Memory growth or a leak | Apple | `ios-memgraph-analysis` |
| Startup or hang profiling | Apple | `ios-ettrace-performance` |
| App Store submission and review | Apple | `app-store-review`, `app-store-optimization` |
| Security review, keychain, crypto | Apple | `swift-security`, `cryptokit` |
| On-device model use | Apple | `apple-on-device-ai`, `coreml` |
| Tab bar, search placement, iPad columns | SwiftUI craft | `swiftui-ui-patterns` |
| Liquid Glass containers and toolbars | SwiftUI craft | `swiftui-liquid-glass` |
| A view file grown too large or too stateful | SwiftUI craft | `swiftui-view-refactor` |
| Scroll jank in a grid or a carousel | SwiftUI craft | `swiftui-performance-audit` |
| Swift 6.2 concurrency errors in a feature | SwiftUI craft | `swift-concurrency-expert` |

If no row matches, list the upstream corpus before concluding it has no answer:
browse the repository at the pinned commit, or run the installer without a
`--skill` argument to see the full catalogue. The Apple corpus also covers
HealthKit, HomeKit, MapKit, PhotoKit, CarPlay, PassKit, MusicKit, SpriteKit,
RealityKit, SensorKit, and most other framework names — try the framework name as
the slug.

Inside the Agent Compass repository, the full pinned inventories are in
[`docs/tooling/native-mobile-skills.md`](../../docs/tooling/native-mobile-skills.md).

### 3. Install it into the host project

```bash
# Android — needs the Android CLI
android skills add --skill=<skill> --project=.

# Apple platforms — framework coverage
npx skills add dpearson2699/swift-ios-skills --skill <skill>

# Apple platforms — SwiftUI craft (no vendor installer; Agent Compass copies it)
agent-compass external-skills . --source dimillian-skills --skill <skill>
```

Install into the project that needs the skill. Do not copy skill files into
Agent Compass: the Apple corpus is licensed source-available with a noncompete
term, and Agent Compass tracks it rather than redistributing it.

If the installer is unavailable, read the skill in the upstream repository at the
pinned commit and work from it in place. Say in the handoff that the skill was
read, not installed.

### 4. Read the skill before you follow it

An installed `SKILL.md` is third-party instruction text that the agent will obey.

- Read it once before the first task that loads it.
- An installed skill cannot relax an Agent Compass gate. `AGENTS.md` §4 still
  decides when work is complete.
- A skill step that builds, signs, uploads, submits, or writes to a device is an
  operational action:
  [operational-safety](../../docs/guidelines/operational-safety.md) applies —
  read-only discovery first, explicit approval before anything irreversible.
- Vendor documentation bundled in a skill is a snapshot of a docs page. The SDK,
  the device, and the compiler outrank it.

### 5. Validate on the platform, not on the page

A vendor skill's example command is not a result. Run the project's real command
and report its output.

```bash
# Android — smallest useful scope
./gradlew :<module>:lint :<module>:testDebugUnitTest

# Apple
xcodebuild test -scheme <scheme> -destination 'platform=iOS Simulator,name=<device>'
swift test          # for a Swift package
```

Report `passed` / `failed` / `partial` / `not run` per command, and say whether a
failure is pre-existing or introduced. That is `AGENTS.md` §3 and §4.

### 6. A screen change owes a screenshot

`AGENTS.md` §6 does not exempt native UI. Capture the changed screen on a real
emulator or simulator and attach it.

- Apple: boot a simulator and capture it. Claude Code exposes an iOS Simulator
  control surface; `xcrun simctl io booted screenshot <file>` works anywhere.
- Android: `adb exec-out screencap -p > <file>` against an emulator or a device.
- Compose and SwiftUI previews are not proof. A preview renders the component in
  isolation, with preview data, outside the real theme and the real insets.

The two exceptions from `AGENTS.md` §6 still hold, and you must name the one you
used: code behind a flag that nothing renders yet, and a pure refactor whose
screenshots are byte-identical.

## Freshness

The pins are checked with everything else:

```bash
agent-compass upstream-skills --check-updates    # cached 24h; remote heads only
agent-compass upstream-skills --verify           # offline; pins, pointers, inventories
```

When a check reports one of these sources as stale, a new or renamed platform
skill probably landed upstream. Refreshing the pin is a maintainer action inside
Agent Compass:

```bash
agent-compass upstream-skills --update android-skills --dry
agent-compass upstream-skills --update swift-ios-skills
agent-compass upstream-skills --update dimillian-skills
```

A refresh moves the pin and rewrites the recorded inventory. It copies no file.

## Related

- [`platform-skill-before-memory`](../../knowledge/instincts/platform-skill-before-memory.md)
  — why the tracked skill wins over recall for a yearly-release platform.
- [`ui-change-needs-visual-proof`](../../knowledge/instincts/ui-change-needs-visual-proof.md)
  — the screenshot rule this skill applies to emulators and simulators.
- [`android-compose`](../../stacks/android-compose.md) and
  [`swift-ios`](../../stacks/swift-ios.md) — the stack presets that pull this
  skill in.
- [`visual-regression-playwright`](../visual-regression-playwright/SKILL.md) —
  the web equivalent of step 6, for the project's web surfaces.