Skip to main content
Agent skill

Agent Device

Drive iOS and Android devices for the Expensify App - testing, debugging, performance profiling, bug reproduction, and feature verification. Use when the developer needs to interact with the mobile app on a device.

Get started

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Agent Device when an AI agent needs a reusable SKILL.md workflow for this job: Drive iOS and Android devices for the Expensify App - testing, debugging, performance profiling, bug reproduction, and feature verification. Use when the developer needs to interact with the mobile app on a device.

When not to use it

Skip Agent Device when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/agent-device
# Save SKILL.md to ~/.claude/skills/agent-device/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/agent-device/SKILL.md. For a shared project, commit the folder at .claude/skills/agent-device/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Agent Device skill for this task: Use Agent Device when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

71/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
77/100
Practical detail
68/100
Source evidence
63/100
Source signals
72/100
Model compatibility evidence
  • claudeinferred

    The skill text mentions Claude or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# agent-device

## Pre-flight (auto)

These checks evaluate at skill load. If any line shows `FAIL`, stop and surface the fix before running any device command.

`agent-device` version: !`R=0.20.0; V=$(agent-device --version 2>/dev/null); [ -n "$V" ] && [ "$(printf '%s\n%s\n' "$R" "$V" | sort -V | head -1)" = "$R" ] && echo "OK ($V)" || echo "FAIL (need v$R+, got: ${V:-not installed}). Fix: npm install -g agent-device@latest"`

Bundled CLI skills dir: !`D="$(npm root -g)/agent-device/skills/agent-device"; test -s "$D/SKILL.md" && echo "OK ($D)" || echo "FAIL (missing $D/SKILL.md). Fix: npm install -g agent-device@latest"`

HybridApp mode: !`M=$(scripts/is-hybrid-app.sh 2>/dev/null | tail -1); [ "$M" = "true" ] && echo "OK (HybridApp)" || echo "FAIL (got: ${M:-unknown}). This skill only supports the HybridApp build - ensure the Mobile-Expensify submodule is present."`

## Bring-up

Run this sequence the first time the user asks for device interaction in a session, before any `open` / `snapshot` / `replay`.

### 1. Platform

If the user prompt names `ios` or `android` explicitly, use it. Otherwise ask. Only iOS and Android are supported; reject other platforms.

### 2. Bundle ID

HybridApp dev builds only (the pre-flight gate enforces this).

| Platform | Bundle ID | Build command from App root | | --------- | ------------------------------- | --------------------------- | | `ios` | `com.expensify.expensifylite` | `npm run ios` | | `android` | `org.me.mobiexpensifyg.dev` | `npm run android` |

### 3. Confirm dev build is installed

```bash agent-device apps --platform <p> --json ```

If the resolved bundle ID is missing from the list, **STOP** and instruct the developer to run the matching build command from the App repository root. The build script detects HybridApp mode and builds the native app from `Mobile-Expensify/`.

### 4. Metro

```bash agent-device metro prepare --public-base-url http://localhost:8081 --port 8081 --kind react-native ```

If `metro prepare` fails, **STOP** and surface the error verbatim.

### 5. Pick a target device

```bash agent-device devices --platform <p> --json ```

- Prefer the first device with `booted=true`. - If none are booted, choose the default target device (usually the first listed), then continue to step 6 to detect and clear any stale session bound to that device before opening. - If multiple are booted, ask the user which.

Capture the device name and (for iOS) the simulator UDID, or (for Android) the serial.

### 6. Session reuse vs reset

```bash agent-device session list --json ```

For each entry whose `device_udid` (iOS) or `serial` (Android) matches the chosen device:

- If the session was created earlier in the **current** Claude invocation, reuse it silently. - Otherwise prompt: `reuse` (continue with the existing session) or `reset` (force-close it). - To reset: `agent-device close --shutdown --session <name>`. `--shutdown` also frees the simulator.

### 7. Open

```bash agent-device open <bundle-id> --platform <p> --device "<name>" ```

If `open` errors with "app not installed", revisit step 3.

### 8. Sanity

```bash agent-device snapshot -i ```

Confirm the app rendered. From here, follow the [Agent decision loop](flows/README.md) for repeatable flows or drive interactively.

### 9. Interaction safety

After opening or relaunching the App, inspect `agent-device snapshot -i` for React Native development overlays before interacting.

If the snapshot reports a LogBox warning, run:

```bash agent-device react-native dismiss-overlay agent-device snapshot -i ```

Continue only when the fresh snapshot no longer reports the overlay. Multiple LogBox banners can require repeated `dismiss-overlay` and fresh `snapshot -i` calls. If the snapshot reports a RedBox fatal error, stop and surface the error instead of dismissing it.

Before pressing an action that may be covered by an overlay or system UI:

```bash agent-device snapshot -i agent-device screenshot --overlay-refs ```

Use a stable selector or a fresh `@eN` reference. Confirm the target is reported as hittable. Never use coordinates to bypass `interactionBlocked: "covered"`, `reason: "offscreen_ref"`, or `targetHittable: false`.

When a target is rejected, capture `agent-device screenshot --overlay-refs`. Dismiss a recoverable LogBox overlay when present, capture a fresh `snapshot -i`, and retry only through a selector or fresh reference. Otherwise stop and report the blocker.

After pressing the action, verify the expected destination or control state with `wait`, `is`, `find`, or a fresh snapshot.

### Canonical skill references

Read these files directly for device automation guidance (bootstrap, exploration, verification, debugging): !`echo "$(npm root -g)/agent-device/skills/agent-device"`

## Flows

This skill owns interactive automation only: reusable setup and navigation macros under [`flows/macros/`](flows/README.md), with platform overrides under `flows/macros/<platform>/`. Propose and run macros through the [Agent decision loop](flows/README.md). `flows/README.md` is also the reference for the `.ad` metadata spec, selector rules, and recording workflow, so read it before authoring any `.ad` file in this repository.

Measurement flows live in the [`measure-telemetry-span`](../measure-telemetry-span/SKILL.md) skill, which owns its own `flows/` and runner. Do not add measurement flows here.

Intended uses

  • Use Agent Device when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.