Mobile Developer (Expo / React Native)
Work like a senior mobile engineer inside the workspace. Prefer the mobile
tool over raw shell guesses for setup and packager lifecycle.
When to use
- The workspace is (or should become) an Expo or React Native app.
- The user asks to run on an emulator/device, fix Metro/Gradle/redbox errors,
add screens, restyle UI, or make the layout responsive.
- Flutter is detected: report it, use
mobile(action=detect|plan), and say
Flutter run automation is plan-only in this release.
Operating loop
Stay in Agent execution. Do not switch to Plan mode for Mobile setup.
When preparing the environment, show a short numbered checklist in chat and
tick items as you finish them (1/4, 2/4, …). Prefer doing installs over
writing a long plan. Progress bars come from the tools - do not invent fake %.
- Detect -
mobile(action="detect") as soon as the session opens on a
mobile-looking repo. Do not assume Expo vs bare React Native.
- Bootstrap - for a ready Android toolchain call
mobile(action="bootstrap") (preferred over hand-rolled sdkmanager shells).
It installs under ~/.navin (adb → JDK → cmdline-tools → SDK → AVD) and
emits live progress. First bootstrap step is OS-aware:
- WSL: if KVM group not active yet, tell the user to open Windows
PowerShell (not Ubuntu) and run
wsl --shutdown, then reopen WSL. Never
run wsl from inside Ubuntu. Or ask them to Play an AVD in Android
Studio on Windows → Refresh Mobile.
- Windows: ASK user to open Android Studio → Device Manager → Play an AVD
(winget installs Studio when missing).
- macOS: Android Studio via
brew install --cask android-studio when missing
- Linux: KVM (
usermod -aG kvm) then logout/login (not wsl --shutdown)
Never start -accel off / swiftshader. USB phones always OK when in
adb devices. Then mobile(action="doctor") / mobile(action="devices").
- Doctor / setup - if bootstrap is unnecessary (device already online),
mobile(action="setup") then mobile(action="doctor") is enough.
- Run -
mobile(action="run", target="android") (or ios / web /
metro). Use mobile(action="logs") while iterating. Stop with
mobile(action="stop").
- Preview (mandatory) - once a device/emulator is online, call
mobile(action="preview_start") (opens the Dev Mobile tab) or
open_preview(kind="mobile"). For target="web", after the packager URL
responds, call open_preview(kind="web", url=...). Keep the app running so
you can fix redboxes the user sees in Preview. Tell the user to click
Start preview only if the panel is already open and idle.
- Code - small, focused edits. Follow the project's router, theme, and
component patterns (Expo Router vs React Navigation, NativeWind vs StyleSheet).
- Verify (mandatory) - after meaningful edits, run
verify action=check
or test_run. Also watch Fast Refresh / mobile(action="logs"); fix redboxes
before claiming done. Add a minimal test for new behavior when the stack allows it.
- Review (light) - short
critic-reviewer pass (or code_review on larger
diffs); fix blockers, then deliver.
- Deliver - summarize files changed, how to re-run (
mobile run or the
packager command), test/preview status, and any remaining device/SDK setup.
Delivery gate (do not skip)
Before ending a turn that built or changed a mobile/web app:
- App is running (
mobile run / packager / web target).
- Preview is open (
preview_start or open_preview).
- Tests /
verify ran; failures fixed or explicitly reported.
- Light review done; blockers fixed.
Tool cheat sheet
| Goal |
Call |
| What stack is this? |
mobile(action="detect") |
| Full Android install cycle |
mobile(action="bootstrap") |
| Is the machine ready? |
mobile(action="doctor") |
| List phones / AVDs |
mobile(action="devices") |
| Show commands only |
mobile(action="plan", target="android") |
| Start Expo/Metro (+ AVD if needed) |
mobile(action="run", target="android") |
| Follow logs |
mobile(action="logs") |
| Stop packager / emulator |
mobile(action="stop") |
| Live Android preview |
mobile(action="preview_start") (auto-opens Dev Mobile) or open_preview(kind="mobile") |
| Tap / swipe / keys |
mobile(action="tap"|"swipe"|"key"|"text", ...) |
| See the screen (vision) |
mobile(action="screenshot") - returns a real image to the model |
| Map on-screen controls |
mobile(action="ui_dump") then match testID / text / bounds |
| Perf snapshot |
mobile(action="metrics") |
If run is blocked, do not invent alternate start commands until doctor is
clean - fix the reported missing tools first.
The Mobile Preview panel (Dev workbench → Mobile) shows the device screen,
logcat, FPS/memory. Click = tap, drag = swipe. preview_start opens that panel
for the user automatically; use tap / ui_dump yourself when verifying a fix.
Stack recipes
Expo (preferred)
- Start:
mobile(action="run", target="android") or target="web" for a quick
UI loop without an emulator.
- Entry is often
app/ (Expo Router) or App.tsx.
- Use Expo APIs (
expo-router, expo-image, expo-secure-store) before adding
bare native modules. If a library needs custom native code, confirm whether
the app is managed Expo, prebuild, or a dev client.
- Common fix: delete stale Metro cache with
npx expo start -c via exec only
after a normal start fails on cache.
React Native CLI
- Prefer project scripts (
npm run android / start) surfaced by
mobile(action="plan").
- Native folders
android/ and ios/ matter: Gradle errors are real; read the
first failure, not the last warning.
- After native dependency changes: rebuild the app (
run-android), not only
Metro.
Flutter
- Detected via
pubspec.yaml. Prefer mobile(action="run", target="android")
or target="ios". Use the Mobile Preview panel the same way as Expo/RN once
the device is online.
- Never pass a platform to
-d: flutter run -d ios matches no device and the
run hangs. The tool resolves the real adb serial / iPhone UDID; pass
device=<id> to pick one when several are online.
- On a physical iPhone, the first run takes many minutes (Xcode prepares
debugger support, then signs). Poll
mobile(action="logs") and tell the user
what is happening instead of waiting silently.
UI / product patterns
- New screen: match existing navigation (Expo Router file in
app/, or a
React Navigation stack/tab). Wire the route, empty/loading/error states, and
a way to open the screen from the current IA.
- Material / theme: reuse the project's theme provider or tokens; do not
invent a second palette. For React Native Paper / NativeWind / Tamagui,
follow whatever is already installed.
- Responsive: prefer flex + constraints over fixed pixel widths; test
mentally for small phones and tablets; avoid hardcoded
width: 400.
- Dark mode: use the project's color scheme / theme tokens; never hardcode
only light colors if dark is already supported.
Error playbook
- Metro port in use:
mobile(action="stop"), then run again; if needed
kill the stale process on 8081 via exec.
- SDK / adb missing: quote the doctor
Fix: lines; do not pretend the
emulator started.
- Gradle / compileSdk: open the cited
build.gradle / gradle.properties
and align versions with the React Native / Expo version in package.json.
- Redbox "Element type is invalid": usually a wrong default vs named
import - check the export of the file you just touched.
- iOS on Linux/Windows: say clearly that Xcode/macOS is required; offer
Android or Expo web instead.
Guardrails
- Do not commit secrets from
google-services.json, keystores, or .env.
- Do not run
npm install -g for expo-cli; use npx expo.
- Do not claim the app is running without packager logs or a connected device
when the task required a device.
- Keep changes scoped; mobile UI refactors easily sprawl across navigation,
theme, and assets - one concern per turn when possible.
1---2name: mobile-dev3description: Build, run, and debug Expo and React Native mobile apps - detect the stack, doctor the Android/Node toolchain, start Metro/Expo, fix redbox errors, and ship UI changes with hot reload. Use for mobile Dev sessions and any React Native / Expo task.4metadata:5 source: https://skillmd.com/skills/navinspire-ia/mobile-dev6 navin:7 emoji: 📱8 category: development9---1011# Mobile Developer (Expo / React Native)1213Work like a senior mobile engineer inside the workspace. Prefer the `mobile`14tool over raw shell guesses for setup and packager lifecycle.1516## When to use1718- The workspace is (or should become) an Expo or React Native app.19- The user asks to run on an emulator/device, fix Metro/Gradle/redbox errors,20 add screens, restyle UI, or make the layout responsive.21- Flutter is detected: report it, use `mobile(action=detect|plan)`, and say22 Flutter run automation is plan-only in this release.2324## Operating loop2526Stay in **Agent** execution. Do **not** switch to Plan mode for Mobile setup.27When preparing the environment, show a short numbered checklist in chat and28tick items as you finish them (1/4, 2/4, …). Prefer doing installs over29writing a long plan. Progress bars come from the tools - do not invent fake %.30311. **Detect** - `mobile(action="detect")` as soon as the session opens on a32 mobile-looking repo. Do not assume Expo vs bare React Native.332. **Bootstrap** - for a ready Android toolchain call34 `mobile(action="bootstrap")` (preferred over hand-rolled sdkmanager shells).35 It installs under `~/.navin` (adb → JDK → cmdline-tools → SDK → AVD) and36 emits live progress. First bootstrap step is OS-aware:37 - **WSL**: if KVM group not active yet, **tell the user** to open Windows38 PowerShell (not Ubuntu) and run `wsl --shutdown`, then reopen WSL. Never39 run `wsl` from inside Ubuntu. **Or** ask them to Play an AVD in Android40 Studio on Windows → Refresh Mobile.41 - **Windows**: ASK user to open Android Studio → Device Manager → Play an AVD42 (winget installs Studio when missing).43 - **macOS**: Android Studio via `brew install --cask android-studio` when missing44 - **Linux**: KVM (`usermod -aG kvm`) then logout/login (not `wsl --shutdown`)45 **Never** start `-accel off` / swiftshader. USB phones always OK when in46 `adb devices`. Then `mobile(action="doctor")` / `mobile(action="devices")`.473. **Doctor / setup** - if bootstrap is unnecessary (device already online),48 `mobile(action="setup")` then `mobile(action="doctor")` is enough.494. **Run** - `mobile(action="run", target="android")` (or `ios` / `web` /50 `metro`). Use `mobile(action="logs")` while iterating. Stop with51 `mobile(action="stop")`.525. **Preview (mandatory)** - once a device/emulator is online, call53 `mobile(action="preview_start")` (opens the Dev **Mobile** tab) or54 `open_preview(kind="mobile")`. For `target="web"`, after the packager URL55 responds, call `open_preview(kind="web", url=...)`. Keep the app running so56 you can fix redboxes the user sees in Preview. Tell the user to click57 **Start preview** only if the panel is already open and idle.586. **Code** - small, focused edits. Follow the project's router, theme, and59 component patterns (Expo Router vs React Navigation, NativeWind vs StyleSheet).607. **Verify (mandatory)** - after meaningful edits, run `verify action=check`61 or `test_run`. Also watch Fast Refresh / `mobile(action="logs")`; fix redboxes62 before claiming done. Add a minimal test for new behavior when the stack allows it.638. **Review (light)** - short `critic-reviewer` pass (or `code_review` on larger64 diffs); fix blockers, then deliver.659. **Deliver** - summarize files changed, how to re-run (`mobile run` or the66 packager command), test/preview status, and any remaining device/SDK setup.6768## Delivery gate (do not skip)6970Before ending a turn that built or changed a mobile/web app:71721. App is **running** (`mobile run` / packager / web target).732. Preview is open (`preview_start` or `open_preview`).743. Tests / `verify` ran; failures fixed or explicitly reported.754. Light review done; blockers fixed.7677## Tool cheat sheet7879| Goal | Call |80|------|------|81| What stack is this? | `mobile(action="detect")` |82| Full Android install cycle | `mobile(action="bootstrap")` |83| Is the machine ready? | `mobile(action="doctor")` |84| List phones / AVDs | `mobile(action="devices")` |85| Show commands only | `mobile(action="plan", target="android")` |86| Start Expo/Metro (+ AVD if needed) | `mobile(action="run", target="android")` |87| Follow logs | `mobile(action="logs")` |88| Stop packager / emulator | `mobile(action="stop")` |89| Live Android preview | `mobile(action="preview_start")` (auto-opens Dev **Mobile**) or `open_preview(kind="mobile")` |90| Tap / swipe / keys | `mobile(action="tap"\|"swipe"\|"key"\|"text", ...)` |91| See the screen (vision) | `mobile(action="screenshot")` - returns a real image to the model |92| Map on-screen controls | `mobile(action="ui_dump")` then match testID / text / bounds |93| Perf snapshot | `mobile(action="metrics")` |9495If `run` is blocked, do not invent alternate start commands until doctor is96clean - fix the reported missing tools first.9798The Mobile Preview panel (Dev workbench → Mobile) shows the device screen,99logcat, FPS/memory. Click = tap, drag = swipe. `preview_start` opens that panel100for the user automatically; use `tap` / `ui_dump` yourself when verifying a fix.101102## Stack recipes103104### Expo (preferred)105106- Start: `mobile(action="run", target="android")` or `target="web"` for a quick107 UI loop without an emulator.108- Entry is often `app/` (Expo Router) or `App.tsx`.109- Use Expo APIs (`expo-router`, `expo-image`, `expo-secure-store`) before adding110 bare native modules. If a library needs custom native code, confirm whether111 the app is managed Expo, prebuild, or a dev client.112- Common fix: delete stale Metro cache with `npx expo start -c` via `exec` only113 after a normal start fails on cache.114115### React Native CLI116117- Prefer project scripts (`npm run android` / `start`) surfaced by118 `mobile(action="plan")`.119- Native folders `android/` and `ios/` matter: Gradle errors are real; read the120 first failure, not the last warning.121- After native dependency changes: rebuild the app (`run-android`), not only122 Metro.123124### Flutter125126- Detected via `pubspec.yaml`. Prefer `mobile(action="run", target="android")`127 or `target="ios"`. Use the Mobile Preview panel the same way as Expo/RN once128 the device is online.129- Never pass a platform to `-d`: `flutter run -d ios` matches no device and the130 run hangs. The tool resolves the real adb serial / iPhone UDID; pass131 `device=<id>` to pick one when several are online.132- On a physical iPhone, the first run takes many minutes (Xcode prepares133 debugger support, then signs). Poll `mobile(action="logs")` and tell the user134 what is happening instead of waiting silently.135136## UI / product patterns137138- **New screen**: match existing navigation (Expo Router file in `app/`, or a139 React Navigation stack/tab). Wire the route, empty/loading/error states, and140 a way to open the screen from the current IA.141- **Material / theme**: reuse the project's theme provider or tokens; do not142 invent a second palette. For React Native Paper / NativeWind / Tamagui,143 follow whatever is already installed.144- **Responsive**: prefer flex + constraints over fixed pixel widths; test145 mentally for small phones and tablets; avoid hardcoded `width: 400`.146- **Dark mode**: use the project's color scheme / theme tokens; never hardcode147 only light colors if dark is already supported.148149## Error playbook150151- **Metro port in use**: `mobile(action="stop")`, then run again; if needed152 kill the stale process on 8081 via `exec`.153- **SDK / adb missing**: quote the doctor `Fix:` lines; do not pretend the154 emulator started.155- **Gradle / compileSdk**: open the cited `build.gradle` / `gradle.properties`156 and align versions with the React Native / Expo version in package.json.157- **Redbox "Element type is invalid"**: usually a wrong default vs named158 import - check the export of the file you just touched.159- **iOS on Linux/Windows**: say clearly that Xcode/macOS is required; offer160 Android or Expo web instead.161162## Guardrails163164- Do not commit secrets from `google-services.json`, keystores, or `.env`.165- Do not run `npm install -g` for expo-cli; use `npx expo`.166- Do not claim the app is running without packager logs or a connected device167 when the task required a device.168- Keep changes scoped; mobile UI refactors easily sprawl across navigation,169 theme, and assets - one concern per turn when possible.