Skill instructions
agent-device4.1 KB
View saved version →
---
name: agent-device
description: Drive apps on a local iOS simulator or Android device with Mobile Dev's device_* tools, the bundled agent-device runtime's commands. Use for opening apps, accessibility snapshots and refs, taps, text entry, scrolling, waits, and checking that the app reached the requested state.
---
# agent-device
Mobile Dev bundles agent-device 0.20.9 and serves each of its commands as a `device_<command>` tool: `device_open` is its `open` command, and so on. No global CLI install, npx download, or separate server is needed. Follow the Mobile Dev skill to choose the device and to build, install, and launch the app; this skill covers driving it.
Read [the workflow guide](references/workflow.md) before the first task. It is this agent-device version's own `help workflow`, written for its CLI. With the tools:
- Pass each command's options as the JSON fields in its tool's input schema, not as flags: `snapshot -i` is `device_snapshot` with `interactiveOnly: true`, and `--settle` is `settle: true`.
- Commands that act on an element take a `target` object instead of a positional ref or selector: `{ "kind": "ref", "ref": "@e12" }` or `{ "kind": "selector", "selector": "label=\"Search\"" }`.
- Skip the guide's shell advice, such as chaining commands with `&&`. Its `help <topic>` pointers are not available through the tools; each tool's description gives that command's contract.
- `logs` and `perf` are not served; use Mobile Dev's log and performance tools.
1. Use the chosen device's UDID (iOS) or running serial (Android) from Mobile Dev's tools or panel. Call `device_open` with the app, `platform`, `udid` or `serial`, a short `session` name, and `foreground: true`. If the app ID is unknown, find it with `mobile_list_apps` or `device_apps` first; do not invent one or boot another device.
2. Read the refs `device_open` returns, or call `device_snapshot` with `interactiveOnly: true`. Use actual refs from the latest result, or a known selector; prefer them to coordinates.
3. Call `device_press`, `device_fill`, or `device_scroll` with `settle: true`, and continue from the settled diff. `device_fill` replaces text; `device_type` appends to the focused field and has no settle option. Run stateful commands in order within one session.
4. Verify the requested result with a named expectation through `device_wait`, `device_is`, `device_get`, or `device_find`. Give `device_find` a read-only `action` such as `exists` or `getText`; without one it taps the match. A screenshot or snapshot alone is not verification, and an accepted input does not prove the app changed. `device_screenshot` returns the image when you need to look at the screen.
5. Call `device_close` when finished. Leave `shutdown` unset to keep the device running. Closing can close the active app; skip it if the user wants that app left open.
A selector that matches several elements fails with `AMBIGUOUS_MATCH` and lists the candidates: retry with one of their refs or a narrower selector.
Pass device selection to `device_open` once. Later commands take the same `session` and no `platform`, `udid`, `serial`, or `device`; the session holds the device. Discovery, installation, and standalone script tools keep their selection fields. Batch steps inherit the outer session and follow each command's own schema. Follow later user device selections by opening a session on the new device.
Mobile Dev manages state paths, runner configuration, and output format, so tool inputs omit them. Each server has its own temporary state directory; `device_session` with `action: "state-dir"` returns it, and its logs and artifacts stay there. Another agent-device daemon can own a simulator's runner; do not force-release a live owner's claim. End that task's session or choose another device. The server stops its daemon and releases its runner leases when it shuts down.
The first iOS interaction builds the bundled Apple runner with the local Xcode and caches it under `~/.agent-devicePreview of the first 4,000 characters. Read full instructions →
Referenced files: 2 — file references are metadata, not package contents.
mobile-dev27.6 KB
View saved version →
---
name: mobile-dev
description: Use when building, running, changing, or debugging local iOS, Android, Expo, React Native, or SwiftUI apps. Open the simulator beside the chat and control the app with bundled MCP tools. Also use for device streaming, screenshots, accessibility reads, logs, and interactive CPU, memory, and FPS charts. Skip web-only apps and tasks limited to planning, docs, or code review.
---
# Mobile Dev
Use the Mobile Dev MCP tools for local iOS and Android work. The plugin includes Baguette and starts it when you open the panel or list devices. Do not ask the user to install Baguette or run a separate server.
Before device work, resolve the Mobile Dev tools through the host's tool discovery
when available and confirm `mobile_open_simulator` and the relevant device-list
tools are callable. If they are missing, tell the user: "Mobile Dev could not
start. I'll check its setup." Then follow
[missing-tools recovery](../mobile-dev-setup/references/missing-tools.md): inspect the
installed configuration and recent startup failure, explain the result, and
offer a repair for that specific failure. Do not leave
the user with terminal commands to diagnose the problem when you can run the
checks. A generic startup timeout alone does not justify increasing the timeout.
Do not assume the chat predates installation or continue device work through a
substitute backend. Source edits or compilation can continue when they need no
device tools.
1. Open the panel beside the chat with `mobile_open_simulator` by default. For an existing app, open it when starting device work; for a new app, open it before the first device launch. Reuse an open Mobile Dev panel. Use `mobile_open_workspace` when the user asks for fullscreen. Use device-list tools without opening the panel when the user requests a tool-only workflow or the host cannot show panels. A request limited to planning, docs, code review, or compilation does not need a panel or a device launch.
Both opening tools accept optional `platform` (`ios` or `android`), `kind` (`simulator`, `emulator`, or `physical`), and `deviceId`. Pass only intent established by the user's request or app project: for example, `{ platform: "android", kind: "emulator" }` for Android emulator work, or `{ platform: "ios", kind: "physical" }` for an explicitly requested physical iPhone. Omit undecided fields for open-ended work. Pass `deviceId` only after discovering the exact device; discovery can precede opening when needed to identify a named target. A missing matching device stays unselected instead of connecting to another target. Opening selects a stopped simulator or AVD without booting it. Follow later manual selections.
2. Use the task and app project to choose the platform. Follow the user's device choice; otherwise reuse a compatible device shared by the panel, then a suitable running simulator or emulator. If no suitable device runs, choose a compatible installed simulator or AVD. Pick among equivalent devices yourself for routine app development. When the intended target is ambiguous (for example, the app is open on several devices for a performance run), ask the user with `mobile_choose_devices`, or in chat when the host has no form. Read device IDs from tool results or panel context; never invent them.
3. Boot a chosen stopped iOS simulator with `mobile_boot_simulator`, or an Android AVD with `mobile_boot_android_emulator`. A mobile app development request permits choosing and booting a suitable installed simulator without a separate device-choice question. Reuse running devices without rebooting them. Follow the Android section below for device discovery and serials. Opening the panel alone does not boot a device.
4. Build the app with the app project's own tools and the chosen device ID; the project's run command may also install and launch it. To restart an already installed app, use `mobile_launch_app` instead of rebuilding. Follow the project's framework skills where availablePreview of the first 4,000 characters. Read full instructions →
Referenced files: 1 — file references are metadata, not package contents.
mobile-dev-setup4.72 KB
View saved version →
---
name: mobile-dev-setup
description: Set up the Mobile Dev plugin's bundled iOS and Android backends and check local device tools.
---
# Set up Mobile Dev
The installed plugin contains Baguette 0.2.1, its resource bundle, agent-device 0.20.9 with its dependencies and Apple runner source, and the built MCP servers and panel. Do not install Baguette with Homebrew, install a global agent-device CLI, or start separate servers.
First resolve Mobile Dev tools through the host's tool discovery when available.
If `mobile_open_simulator` and the device-list tools are unavailable, tell the user:
"Mobile Dev could not start. I'll check its setup." Follow
[missing-tools recovery](references/missing-tools.md) before stopping: inspect the
installed configuration and startup failure, explain the result, and offer a
repair for that specific failure. Do not leave the user with
terminal commands to diagnose the problem when you can run the checks. A generic
startup timeout alone does not justify increasing the timeout. Stop device setup
until the tools are available; do not claim that the chat was created too early
without evidence or work around the failure with another device backend.
1. Call `mobile_open_simulator` to open the panel beside the chat, or reuse an open Mobile Dev panel. Use `mobile_open_workspace` if the user asks for fullscreen. For an explicit tool-only workflow or a host without panels, use the device-list tools instead. The iOS tools start the bundled backend on a private loopback port and list simulators.
2. If the backend fails, read the returned error. Check that this is an Apple Silicon Mac and that `xcode-select -p` points to Xcode 26 or later. Use `xcodebuild -version` when needed. Diagnose the server's actual startup error if the tools are unavailable.
3. If no devices appear, have the user add an iOS runtime in Xcode's Settings, Components. A runtime download can be large, so do not start it without the user's request.
4. Follow the user's device choice; otherwise reuse a compatible device shared by the panel, then a suitable booted simulator. For app development, choose and boot a suitable installed simulator if none runs. Pick among equivalent devices yourself; ask only when a device choice changes what the task needs and the project gives no answer. Setup alone does not require booting a device. Confirm tool connectivity with `mobile_list_simulators`.
5. The `device_*` tools run the bundled agent-device runtime, which starts on the first command. Its first iOS interaction builds the XCTest runner with the local Xcode. When a command reports that Agent Device could not start or complete it, call `device_doctor` for the device and toolchain readiness it reports. Do not install agent-device or start its CLI separately.
No account, token, tunnel, or hosted service is needed. Do not repeat setup after a successful connection.
For source development, `npm run vendor:baguette` downloads the pinned official archive, checks its SHA-256, and rebuilds the same source with Swift 6.4 or later to avoid macOS 27 crashes. Preparing Baguette requires Xcode 27 and Git. `npm run vendor:agent-device` installs agent-device and its dependencies from the runtime lockfile without package scripts. `npm run build` copies both runtimes into `dist`, and `npm run package` creates a local marketplace and a ZIP. The installed package needs neither npm nor the source checkout.
## Android setup
The package also contains a checked-in Node.js fork of serve-emu 0.0.6, its Node dependencies, and scrcpy 4.0. Android uses the same Node runtime as the server and needs Android SDK platform-tools and emulator, and an AVD or authorized attached device. Check connectivity with `mobile_list_android_devices`. The SDK lookup checks `ANDROID_HOME`, `ANDROID_SDK_ROOT`, `~/Library/Android/sdk`, then PATH.
Open or reuse the panel for Android work. Call `mobile_list_android_devices` to discover devices; listing does not boot them. Follow the user's cho
Preview of the first 4,000 characters. Read full instructions →
Referenced files: 2 — file references are metadata, not package contents.
