메뉴
Step-by-step workflows for developing or debugging React Native apps on iOS simulator or Android emulator. Use when starting the app, debugging Metro, fixing builds, diagnosing runtime errors, or running tests.
기본적으로 소스를 먼저 확인하는 Prompt가 선택됩니다. 직접 명령으로 전환하거나 로컬 사본을 다운로드할 수도 있습니다.
설치 여부를 결정하기 전에 SKILL.md와 SkillsMP에 표시된 보조 파일을 읽어 보세요.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
직접 명령은 검토 Prompt를 거치지 않습니다. 실행하기 전에 소스를 확인하세요.
npx skills add https://github.com/software-mansion/argent --skill argent-react-native-app-workflow명령은 한 줄로 유지됩니다. 복사하기 전에 가로로 스크롤해 전체 내용을 확인하세요.
로컬 사본을 원하시나요? SkillsMP에서 현재 제공할 수 있는 파일을 다운로드하세요.
SOC 직업 분류 기준
SKILL.md 표시 중
| name | argent-react-native-app-workflow |
| description | Step-by-step workflows for developing or debugging React Native apps on iOS simulator or Android emulator. Use when starting the app, debugging Metro, fixing builds, diagnosing runtime errors, or running tests. |
Before running commands, read the project's build and run configuration from the argent-environment-inspector subagent result.
Do NOT default to npx react-native start or npx react-native run-ios without first checking for custom scripts and workflows.
Manual fallback (if neither the agent nor the tool is available): read ALL package.json scripts — look for custom scripts like start:local, start:dev, ios, build:ios, flavors, etc. Custom scripts take priority over default commands. Also check metro.config.js for non-default port or watchFolders. For iOS builds, prefer opening .xcworkspace over .xcodeproj (CocoaPods generates the workspace).
If the project structure is convoluted, ask the user before proceeding.
Remember the workflow: Once you discover the project's build/run workflow, save it to project memory so you don't need to re-discover it each time.
Checklist before start:
node_modules present (if not: npm install or yarn)ios/Podfile exists; if missing or stale, run ios/Podscd ios && pod install && cd ..Check whether metro is already running on port found in configuration and if it is - do not start another server. Refer to point 2.1.
Use the project's custom start script if one exists (e.g. npm run start:local, yarn start:dev). Fall back to default commands if no custom scripts are defined:
npx react-native start
Optional: npx react-native start --reset-cache if cache issues are suspected.
Verify Metro is ready: use the debugger-status tool. It returns a status result instead of erroring: status: "connected" or status: "not_connected" with reason: "no_app_connected" both mean Metro is up (the app just hasn't attached yet); reason: "metro_not_running" means Metro is not reachable — follow the result's guidance.
Projects with flavors or custom configs: Use project-specific start script if present (e.g. npm run start:local), and start Metro before running the app.
In a separate terminal (Metro keeps running in the first):
Use the project's custom build/run script if one exists (e.g. npm run ios, npm run android, yarn ios:debug). Only fall back to the defaults below if no custom scripts are defined.
Pass the target device explicitly — derive it from list-devices (see <device_selection_rule>):
npx react-native run-ios --simulator="<name>" # iOS (or --udid <UDID>)
npx react-native run-android --deviceId=<adb-serial> # Android
Android only: after install, run adb -s <serial> reverse tcp:8081 tcp:8081 so the emulator/device can reach Metro on your host. Repeat if the device restarts or adb drops.
Agent checklist:
boot-device with the iOS udid or Android avdName. Refer to the argent-ios-simulator-setup / argent-android-emulator-setup skill.adb -s <serial> reverse tcp:8081 tcp:8081 done.Before starting Metro, avoid "port already in use" errors. Default port to check is :8081, infer the port from documentation:
lsof -i :PORT
Use the debugger-status tool to check whether the process on that port is actually a Metro server — it returns a structured result, not an error. status: "connected" or reason: "no_app_connected" → the process is Metro. reason: "metro_not_running" while lsof shows a listener → the port is occupied by something that is not Metro; the result's detail field shows what the process answered (Metro at port ... is not running (got: ...)). In that case ask the user whether you may kill the process.
To kill a Metro process, use the stop-metro tool (requires user confirmation).
Verify Metro is reachable: use the debugger-status tool. reason: "metro_not_running" means Metro did not answer on that port — start it (§2.1); "no_app_connected" means Metro answered but the app has not attached (§2.3). Any other reason: follow the result's guidance (it does not by itself prove Metro is up).
After code or config changes, the app must load the new bundle:
| Method | How |
|---|---|
| Reload tool | Use the debugger-reload-metro tool |
| Restart app | Use the restart-app tool, or kill the app in simulator and run npx react-native run-ios again |
Agent checklist:
Order of operations (simplest first):
watchman watch-del-all, remove node_modules + lockfile, npm install, then cd ios && rm -rf build Pods Podfile.lock && pod install --repo-updatepod deintegrate then pod install --repo-updateios/*.xcworkspace in Xcode for detailed errors in the Report navigatorAfter 2-3 failed build or run attempts, STOP and ask the user for guidance. The user may know about required env vars, Xcode version requirements, custom build configurations, monorepo-specific setup, or required external services.
If the project structure is convoluted and the correct build approach is not obvious, ask the user early rather than guessing.
Once you discover the correct build/run workflow for a project, save it to project memory. Capture: commands to start Metro, commands to build/run the app, and any required environment setup.
| Situation | Action |
|---|---|
| JS/React only changed | Use debugger-reload-metro tool. No rebuild. |
Native code or pod install / project config changed | Rebuild: npx react-native run-ios (Metro can stay running). |
node_modules or package.json changed | npm install, then if native deps changed run cd ios && pod install. Then rebuild. |
| App needs reinstalling from .app path | Use reinstall-app tool with UDID, bundle ID, and .app path. |
| Persistent native build errors | Full clean + reinstall (step 2 above). |
| Action | Tool / Command |
|---|---|
| List devices | list-devices tool (iOS + Android) |
| Boot an iOS simulator | boot-device tool with udid |
| Boot an Android emulator | boot-device tool with avdName |
| Launch an app | launch-app tool (pass device id + bundle id / package name) |
| Restart an app | restart-app tool (pass device id + bundle id / package name) |
| Open a URL / deep link | open-url tool (pass device id + URL) |
| Rotate device | rotate tool |
| Stop simulator server | stop-simulator-server tool (iOS UDID or Android serial — one device) |
| Stop all simulator servers | stop-all-simulator-servers tool — pass devices: [...] to scope the teardown to this session's devices (an unscoped call also tears down other agents' devices; use it only for a machine-wide cleanup) |
For full simulator setup workflow, refer to the argent-ios-simulator-setup skill.
| Problem type | Tool / Where to look |
|---|---|
| JavaScript errors / logs | Use debugger-log-registry to get a summary and log file path, then Grep/Read to search. If it returns status: "not_connected", no log file is returned — follow its guidance to reconnect first. |
| React component hierarchy | Use debugger-component-tree tool for a text tree, or debugger-inspect-element at specific logical pixel coordinates (not normalized 0-1). |
| Visual state of the app | Use screenshot tool to capture the current screen, but prefer describe or debugger-component-tree for actual navigation and target discovery. If a permission prompt or system-owned modal overlay is not exposed reliably, then fall back to screenshot. |
| Evaluate JS in the app | Use debugger-evaluate tool to run JavaScript in the app's runtime. |
| Native crashes / native stack | npx react-native log-ios or iOS Simulator: Debug → Open System Log. |
| Build/runtime config | metro.config.js, babel.config.js, package.json scripts, ios/Podfile. |
For comprehensive Metro debugging workflows (component inspection, console logs, JS evaluation), refer to the argent-metro-debugger skill.
Logs are written to a flat log file on disk under ~/.argent/tmp/. Use the log-registry → grep pattern instead of reading logs inline.
For the full workflow, flat entry format, and grep examples, see argent-metro-debugger skill §5.
Use the argent tools instead.
Check the argent-environment-inspector result for test commands. For interactive UI testing with automatic screenshot verification, use the argent-test-ui-flow skill.
package.json ("test": "jest", jest config). Run: npm test or yarn test..detoxrc.js or similar), or other E2E config. Dependencies: detox, detox-cli, and for iOS often applesimutils.argent-test-ui-flow for manual QA. For screenshot-diff rules and parameters, follow the argent-screenshot-diff skill. Use it when stable before/after screenshots add meaningful pixel-visible evidence.argent-test-ui-flow skill.If the user's intent is ambiguous (run existing tests, write new tests, or find missing coverage), clarify before proceeding.
npm test or npx jest.detox build --configuration ios.sim.release (or debug).detox test --configuration ios.sim.release.package.json and test config (Jest, Detox, etc.).| Goal | Tool / Command |
|---|---|
| Check port 8081 | lsof -i :8081 |
| Kill Metro | stop-metro tool |
| Start Metro | npx react-native start |
| Start Metro (reset cache) | npx react-native start --reset-cache |
| Run iOS app | npx react-native run-ios |
| Run Android app | npx react-native run-android |
| List devices | list-devices tool (iOS + Android) |
| Boot a device | boot-device tool (pass udid for iOS or avdName for Android) |
| Take screenshot | screenshot tool |
| Compare visible UI changes | screenshot-diff tool; follow the argent-screenshot-diff skill for baseline/current capture choices |
| Describe screen (a11y tree) | describe tool for normal app screens and in-app modals; use screenshot only when permission/system overlays are not exposed reliably |
| Read JS console logs | debugger-log-registry tool |
| Reload JS bundle | debugger-reload-metro tool |
| Check Metro status | debugger-status tool |
| Inspect React component tree | debugger-component-tree tool |
| Run JS in app | debugger-evaluate tool |
| iOS native logs | npx react-native log-ios |
| Android native logs | npx react-native log-android or adb -s <serial> logcat |
| Clean + reinstall (nuclear) | See §3.1 step 3 |
| Skill | When to use |
|---|---|
argent-ios-simulator-setup | Initial iOS simulator boot and connection setup |
argent-android-emulator-setup | Initial Android emulator boot and connection setup |
argent-device-interact | Tapping, swiping, typing, hardware buttons, gestures on the simulator/emulator |
argent-metro-debugger | JS-runtime CDP debugging (Metro on iOS / Android; the four ported tools also drive Chromium/CDP apps): component inspection, console logs, JS evaluation |
argent-react-native-profiler | Profiling performance, finding re-render issues, CPU hotspots |
argent-test-ui-flow | Interactive UI testing with automatic screenshot verification after each action |
Ask the user before running tests: confirm which test suite (unit, E2E, or both), whether to use existing CI commands, and whether they want you to run existing tests, write new ones, or explore test cases yourself.