Skip to content

docs: restructure agent-device skill guidance #352

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
thymikee wants to merge 3 commits into
base: main
Choose a base branch
from
Open

docs: restructure agent-device skill guidance #352

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5d929ae
docs: restructure agent-device skill guidance
thymikee Apr 2, 2026
e89025f
docs: refine agent-device skill routing
thymikee Apr 2, 2026
6b79dcc
docs: tighten agent-device guidance and add checklist
thymikee Apr 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -167,6 +167,7 @@ Command-only flags (like `find --first`) that don't flow to the platform layer o
- For behavior/CLI surface changes, evaluate docs/skills updates.
- Update `README.md` and relevant `website/docs/**` pages for command behavior/flags/aliases/workflows.
- Update relevant `skills/**/SKILL.md` when usage examples/workflow recommendations change.
- When iterating on `skills/agent-device/**`, review [docs/agent-device-top-50-checklist.md](docs/agent-device-top-50-checklist.md) and check for regressions in routing, first-step guidance, and fallback coverage across those task families.
- Keep skill docs task-first:
- top-level `SKILL.md` should stay a thin router, not a full manual.
- keep detailed workflows/troubleshooting in a `references/` folder instead of growing the router.
Expand Down
114 changes: 114 additions & 0 deletions docs/agent-device-top-50-checklist.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
# agent-device Top 50 Checklist

Use this file when reviewing or refactoring `agent-device` skills.

This is a verification checklist, not a scoring rubric. The goal is to confirm that the skill package still gives both small and large models a clear, productive path through the most common mobile-app build, test, and exploration tasks.

## How to use this checklist

When changing `skills/agent-device/**`:

1. Review the touched guidance against the task families below.
2. Check for regressions in routing, missing first-step guidance, and lost fallback paths.
3. Focus especially on whether a smaller model can choose the right next reference and first command without guessing.
4. In your review or summary, call out any tasks that became clearer, weaker, or ambiguous.

## 1. Setup and environment

| # | Task | Goal |
| --- | --- | --- |
| 1 | Choose the right device target | Pick the correct simulator, emulator, phone, tablet, TV target, or desktop surface |
| 2 | Boot the correct simulator or emulator | Get the target running before app interaction |
| 3 | Launch the app on the correct target | Start the intended app on the intended device |
| 4 | Install a fresh build artifact | Put a new `.apk`, `.aab`, `.app`, or `.ipa` on the target |
| 5 | Relaunch into a clean runtime state | Reset stale app state without changing more than needed |
| 6 | Pick the correct app identifier or package | Discover and use the actual installed app name or identifier |
| 7 | Open the app in a named session | Pin work to a reusable session |
| 8 | Preserve a replay script when closing | Save a useful `.ad` artifact from a finished session |

## 2. Routing and session control

| # | Task | Goal |
| --- | --- | --- |
| 9 | Keep many commands pinned to one session | Avoid retargeting across a longer flow |
| 10 | Avoid retargeting by accident on a shared host | Keep one run scoped to one chosen device |
| 11 | Scope discovery to a subset of devices | Limit device selection in mixed environments |
| 12 | Run multiple concurrent sessions safely | Avoid session collisions across runs |
| 13 | Decide when session-routing is needed | Know when to stay in bootstrap vs load advanced routing |
| 14 | Route commands in tenant or remote setups | Handle remote daemon or tenant-scoped host control safely |

## 3. Navigation and interaction

| # | Task | Goal |
| --- | --- | --- |
| 15 | Inspect the current screen | Read visible structure and state |
| 16 | Find a specific element to act on | Resolve a control, row, field, or button reliably |
| 17 | Tap, scroll, and navigate normally | Move through the app using the default loop |
| 18 | Use selectors vs refs correctly | Choose stable targeting for the current task |
| 19 | Recover when a ref goes stale or off-screen | Re-target without guesswork |
| 20 | Use raw coordinates only as a fallback | Fall back safely when structured targeting fails |
| 21 | Open a deep link or route directly | Land on a known route without manual navigation |
| 22 | Navigate directly to a known screen without waste | Skip unnecessary manual steps when direct routing is available |

## 4. Text entry and keyboard

| # | Task | Goal |
| --- | --- | --- |
| 23 | Fill a form field correctly | Replace field text reliably |
| 24 | Append text to an already-focused field | Type at the insertion point without retargeting |
| 25 | Handle blocked UI due to keyboard | Continue the flow when the keyboard covers controls |
| 26 | Inspect Android keyboard state or input type | Read keyboard visibility or field type without mutating UI |
| 27 | Avoid typing just to reveal hidden info | Keep inspection read-only unless text entry is actually required |

## 5. Read-only QA and assertions

| # | Task | Goal |
| --- | --- | --- |
| 28 | Verify visible UI content | Confirm text, labels, and structure on screen |
| 29 | Turn acceptance criteria into checks | Convert expected behavior into concrete pass/fail verification |
| 30 | Verify nearby structural UI changes | Confirm what changed after one local mutation |
| 31 | Capture proof artifacts after verification | Save evidence once the expected state is reached |
| 32 | Compare before/after state around a mutation | Validate a nearby change without re-exploring everything |

## 6. Exploratory testing

| # | Task | Goal |
| --- | --- | --- |
| 33 | Run an open-ended bug hunt | Explore broadly for issues rather than proving one requirement |
| 34 | Systematically move through major app areas | Cover the main surfaces without getting stuck |
| 35 | Capture repro evidence for bugs | Save enough proof to make the issue actionable |
| 36 | Produce a structured issue report | Turn findings into a reproducible handoff |

## 7. Debugging and failure triage

| # | Task | Goal |
| --- | --- | --- |
| 37 | Inspect app logs for a broken flow | Narrow down what happened during a repro |
| 38 | Inspect network activity tied to the session | Check request and response behavior in context |
| 39 | Handle permission prompts and alerts | Resolve blocking system or app prompts correctly |
| 40 | Distinguish AX tree lag from real breakage | Avoid misdiagnosing stale snapshots as product failures |
| 41 | Triage a crash or fatal termination | Branch quickly to the right crash evidence source |
| 42 | Narrow a flaky repro to a short debug window | Reduce noise and capture only the relevant failure interval |

## 8. React Native and dev-build specific

| # | Task | Goal |
| --- | --- | --- |
| 43 | Dismiss transient React Native warnings and continue | Keep the flow moving when the warning is not the task |
| 44 | Escalate recurring React Native warnings to debugging | Treat repeated overlays as part of app state, not disposable chrome |
| 45 | Preserve evidence when React Native overlays appear | Capture enough proof to name the warning or error later |

## 9. Accessibility

| # | Task | Goal |
| --- | --- | --- |
| 46 | Compare visual UI with the accessibility tree | Detect mismatches between rendered UI and AX exposure |
| 47 | Detect elements visible to users but missing from AX | Find missing accessibility exposure gaps |
| 48 | Retry with `snapshot --raw` when AX exposure is unclear | Separate collector filtering from truly missing content |

## 10. Automation and maintenance

| # | Task | Goal |
| --- | --- | --- |
| 49 | Run a known stable multi-step flow with `batch` | Reduce round trips once the flow is already known |
| 50 | Maintain replay scripts when selectors drift | Keep `.ad` flows usable over time |
84 changes: 36 additions & 48 deletions skills/agent-device/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,68 +5,56 @@ description: Automates interactions for Apple-platform apps (iOS, tvOS, macOS) a

# agent-device

Use this skill as a router with mandatory defaults. Read this file first. For normal device tasks, always load `references/bootstrap-install.md` and `references/exploration.md` before acting. Use bootstrap to confirm or establish deterministic setup. Use exploration for UI inspection, interaction, and verification once the app session is open.
Use this skill as a thin router. Read this file first, then load only the references that match the task.

## Default operating rules
## Routing map

- Start conservative. Prefer read-only inspection before mutating the UI.
- Start deterministic. If the app name, package, device, or session is uncertain, load bootstrap and discover them before interacting.
- Use plain `snapshot` when the task is to verify what text or structure is currently visible on screen.
- Use `snapshot -i` only when you need interactive refs such as `@e3` for a requested action or targeted query. On iOS and Android, default snapshot output uses the same visible-first model: off-screen interactive content is exposed as discovery hints, not tappable refs.
- Prefer `diff snapshot` after a nearby mutation when you only need to know what changed.
- Avoid speculative mutations. You may take the smallest reversible UI action needed to unblock inspection or complete the requested task, such as dismissing a popup, closing an alert, or clearing an unintended surface.
- In React Native dev or debug builds, check early for visible warning or error overlays, tooltips, and toasts that can steal focus or intercept taps. If they are not part of the requested behavior, dismiss them and continue. If you saw them, report them in the final summary.
- Do not browse the web or use external sources unless the user explicitly asks.
- Re-snapshot after meaningful UI changes instead of reusing stale refs.
- Treat refs in default snapshot output as actionable-now, not durable identities. If a target is off-screen, use `scrollintoview` or scroll and re-snapshot.
- Prefer `@ref` or selector targeting over raw coordinates.
- Ensure the correct target is pinned and an app session is open before interacting.
- Keep the loop short: `open` -> inspect/act -> verify if needed -> `close`.
| Situation | Read next | Skip when |
| --- | --- | --- |
| Normal session setup, app launch, install, target selection | [references/bootstrap-install.md](references/bootstrap-install.md) | Skip only if the correct app session is already open on the correct target |
| Normal UI inspection or interaction | [references/exploration.md](references/exploration.md) | Skip only if the task is pure setup or pure debugging |
| Open-ended bug hunt with report | [../dogfood/SKILL.md](../dogfood/SKILL.md) | Skip for normal task execution |
| QA from acceptance criteria | [references/qa.md](references/qa.md) | Skip for open-ended exploration or bug hunts |
| Accessibility-gap audit | [references/accessibility.md](references/accessibility.md) | Skip unless the task is specifically about AX exposure |
| Known stable flow to run with `batch` | [references/batch.md](references/batch.md) | Skip unless the sequence is already known |
| Failure triage, logs, alerts, permissions, unstable sessions | [references/debugging.md](references/debugging.md) | Skip when the normal flow is working |
| Screenshots, diff, recording, replay maintenance, perf | [references/verification.md](references/verification.md) | Skip until the main interaction flow is working |
| macOS desktop surfaces, menu bar, frontmost app | [references/macos-desktop.md](references/macos-desktop.md) | Skip unless `--platform macos` or desktop surfaces matter |
| Shared host routing, session locking, scoped discovery | [references/session-routing.md](references/session-routing.md) | Skip for single-run local flows |
| Remote daemon or tenant-scoped host control | [references/remote-tenancy.md](references/remote-tenancy.md) | Skip for local runs |

## Default flow
## Normal device tasks

1. Load [references/bootstrap-install.md](references/bootstrap-install.md) and [references/exploration.md](references/exploration.md) before acting on a normal device task.
2. Use bootstrap first to confirm or establish the correct target, app install, and open app session.
3. Once the app session is open and stable, use exploration for inspection, interaction, and verification.
4. Start with plain `snapshot` if the goal is to read or verify what is visible.
5. Escalate to `snapshot -i` only if you need refs for interactive exploration or a requested action.
6. Use `get`, `is`, or `find` before mutating the UI when a read-only command can answer the question.
7. End by capturing proof if needed, then `close`.
For normal device tasks:

## QA modes
1. Load [references/bootstrap-install.md](references/bootstrap-install.md) if the correct app session is not already open on the correct target.
2. Load [references/exploration.md](references/exploration.md) before normal UI inspection or interaction.

- Open-ended bug hunt with reporting: use [../dogfood/SKILL.md](../dogfood/SKILL.md).
- Pass/fail QA from acceptance criteria: stay in this skill, start with [references/bootstrap-install.md](references/bootstrap-install.md), then use the QA loop in [references/exploration.md](references/exploration.md).
Use bootstrap to pin the correct target, app, and session. Use exploration once the app session is open and stable, or immediately if that session is already ready.

## Required references
## Golden paths

- For every normal device task, after reading this file, load [references/bootstrap-install.md](references/bootstrap-install.md) first, then [references/exploration.md](references/exploration.md), before acting.
- Use bootstrap to confirm or establish deterministic setup, especially in sandbox or cloud environments.
- Use exploration once the app session is open and stable.
- Load additional references only when their scope is needed.
1. Normal interaction: bootstrap if needed -> exploration -> verification only if you need proof.
2. RN warning during interaction: exploration -> dismiss warning -> continue without re-snapshotting -> debugging only if it keeps returning or becomes the task.
3. QA from acceptance criteria: bootstrap if needed -> exploration -> [references/qa.md](references/qa.md).
4. Bug hunt with reporting: switch to [../dogfood/SKILL.md](../dogfood/SKILL.md).
5. Accessibility audit: bootstrap if needed -> exploration -> [references/accessibility.md](references/accessibility.md).
6. Stable scripted flow: bootstrap if needed -> exploration -> [references/batch.md](references/batch.md).

## Decision rules
Treat transient React Native warnings as part of the normal interaction path. Switch to debugging only when the warning keeps returning or becomes the thing you need to investigate.

- Use plain `snapshot` when you need to verify whether text is visible.
- Use `snapshot -i` mainly for interactive exploration and choosing refs.
- Use `diff snapshot` for compact post-action verification; use `snapshot --diff` when that alias is easier to discover from snapshot help.
- Use `get`, `is`, or `find` when they can answer the question without changing UI state.
- Use `fill` to replace text.
- Use `type` to append text.
- Do not write `type @eN "text"`. Use `fill @eN "text"` to target a field directly, or `press @eN` then `type "text"` when the field already has focus and you want append semantics.
- If the on-screen keyboard blocks the next step, prefer `keyboard dismiss` over navigation. On iOS, keep an app session open first; `keyboard status|get` remains Android-only.
- When a task asks to "go back", use plain `back` for predictable app-owned navigation and reserve `back --system` for platform back gestures or button semantics.
- Use `type --delay-ms` or `fill --delay-ms` for debounced search fields that drop characters when typed too quickly.
- If there is no simulator, no app install, or no open app session yet, switch to `bootstrap-install.md` instead of improvising setup steps.
- Use the smallest unblock action first when transient UI blocks inspection, but do not navigate, search, or enter new text just to make the UI reveal data unless the user asked for that interaction.
- In React Native dev or debug apps, treat visible warning or error overlays as transient blockers unless the user is explicitly asking you to diagnose them. Dismiss them when safe, then continue the requested flow.
- Do not use external lookups to compensate for missing on-screen data unless the user asked for them.
- If the needed information is not exposed on screen, say that plainly instead of compensating with extra navigation, text entry, or web search.
- Prefer `@ref` or selector targeting over raw coordinates.
## QA modes

- Open-ended bug hunt with reporting: use [../dogfood/SKILL.md](../dogfood/SKILL.md).
- Pass/fail QA from acceptance criteria: stay in this skill, use [references/bootstrap-install.md](references/bootstrap-install.md) if the correct app session is not already open on the correct target, then [references/exploration.md](references/exploration.md), then [references/qa.md](references/qa.md).

## Additional references

- Need logs, network, alerts, permissions, or failure triage: [references/debugging.md](references/debugging.md)
- Need screenshots, diff, recording, replay maintenance, or perf data: [references/verification.md](references/verification.md)
- Need acceptance-criteria mapping or pass/fail checks: [references/qa.md](references/qa.md)
- Need accessibility-gap auditing: [references/accessibility.md](references/accessibility.md)
- Need a known stable `batch` flow: [references/batch.md](references/batch.md)
- Need desktop surfaces, menu bar behavior, or macOS-specific interaction rules: [references/macos-desktop.md](references/macos-desktop.md)
- Need shared-host routing, session locking, or scoped discovery: [references/session-routing.md](references/session-routing.md)
- Need remote HTTP transport, `--remote-config` launches, or tenant leases on a remote macOS host: [references/remote-tenancy.md](references/remote-tenancy.md)
29 changes: 29 additions & 0 deletions skills/agent-device/references/accessibility.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
# Accessibility

## When to open this file

Open this file when the task is to find UI that is visible to a user but missing from the accessibility tree.

## Audit loop

1. Capture a `screenshot` to see what is visually rendered.
2. Capture a `snapshot` or `snapshot -i` to see what the accessibility tree exposes.
3. Compare the two:
- visible in screenshot and present in snapshot: exposed to accessibility
- visible in screenshot and missing from snapshot: likely accessibility gap
4. If you suspect the node exists in AX but is filtered from interactive output, retry with `snapshot --raw`.

## Example

```bash
agent-device screenshot /tmp/accessibility-screen.png
agent-device snapshot -i
```

Use `screenshot` as the visual source of truth and `snapshot` as the accessibility source of truth for this audit.

## When to leave this file

- Return to [exploration.md](exploration.md) once the accessibility comparison is complete.
- Switch to [verification.md](verification.md) if you need screenshots, recordings, or other proof artifacts.
- Switch to [debugging.md](debugging.md) if the audit turns into a failure investigation rather than an accessibility comparison.
Loading
Loading