AutoGineer
Generated banner for Agent Device
Generated logo for Agent Device

Agent Device

CallstackOfficialPublished by Callstack

  • Skill
  • Tool integration
  • Software development
  • MIT
  • No issues found
Download ZIP

From the author

Automates interactions for Apple-platform apps (iOS, tvOS, macOS) and Android devices. Use when navigating apps, taking snapshots/screenshots, tapping, typing, scrolling, or extracting UI info across mobile, TV, and desktop targets.
— the description by Callstack

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The agent-device skill provides a structured framework for automating device interactions, including navigation, UI inspection, and input simulation. It enforces a deterministic workflow by requiring setup via bootstrap references before proceeding to exploration and interaction. The skill emphasizes read-only inspection and selector-based targeting to ensure stability, while providing specific guidance for handling different device types and platforms.

What it does

  • Manages app sessions, including launching, installing, and relaunching applications.
  • Performs UI inspection through snapshots and element referencing.
  • Executes user-like interactions such as tapping, typing, and scrolling.
  • Supports cross-platform automation for mobile, TV, and desktop environments.
  • Provides structured paths for debugging, verification, and environment setup.
  • Enforces safe interaction patterns by prioritizing read-only checks before mutations.

When to use it

  • When you need to automate UI testing or interaction on mobile, TV, or desktop apps.
  • When you need to verify app state or extract UI information from a running session.
  • When you need to perform repeatable setup tasks like installing or launching specific app versions.
  • When you need to perform bug hunting or pass/fail QA against acceptance criteria.

Advantages

  • Promotes deterministic behavior by separating environment setup from UI interaction.
  • Reduces errors by favoring selector-based targeting over fragile coordinate-based actions.
  • Provides a consistent interface across diverse platforms like iOS, Android, and macOS.
  • Encourages safe, reversible UI actions to prevent unintended state changes.

Usage examples

“Open the test app on my iPhone simulator and check if the login button is visible.”
The agent will use bootstrap-install to ensure the simulator is ready, open the app, and then use exploration to verify the presence of the login button.
“Install the latest build of my Android app and navigate to the settings menu.”
The agent will use the install command to deploy the APK, open the app, and perform the necessary navigation steps to reach the settings screen.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/callstackincubator/agent-device/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip agent-device.zip -d .agents/skills

Documentation by Callstack

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.

Default operating rules

  • Start conservative. Prefer read-only inspection before mutating the UI.

  • 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.

  • 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.

  • 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.

  • 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.

Default flow

  1. Load references/bootstrap-install.md and 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.

QA modes

Required references

  • For every normal device task, after reading this file, load references/bootstrap-install.md first, then 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.

Decision rules

  • Use plain snapshot when you need to verify whether text is visible.

  • Use snapshot -i mainly for interactive exploration and choosing refs.

  • 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.

  • 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.

  • 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.

Additional references

Files

references/verification.md

Verification

When to open this file

Open this file when the task needs evidence, regression checks, replay maintenance, or startup performance measurements after the main interaction flow is already working.

Main commands to reach for first

  • screenshot

  • diff snapshot

  • record

  • replay -u

  • perf

Most common mistake to avoid

Do not use verification tools as the first exploration step. First get the app into the correct state with the normal interaction flow, then capture proof or maintain replay assets.

Canonical loop

agent-device open Settings --platform ios
# after using exploration to reach the state you want to verify
agent-device snapshot
agent-device screenshot /tmp/settings-proof.png
agent-device close

Structural verification with diff snapshot

Use diff snapshot when you need a compact view of how the UI changed between nearby states.

agent-device snapshot -i
agent-device press @e5
agent-device diff snapshot -i

  • Initialize the baseline at a stable point.

  • Perform the mutation.

  • Run diff snapshot to confirm the expected structural change.

  • Re-run full snapshot only when you need fresh refs.

Visual artifacts

Use screenshot when the proof needs a rendered image instead of a structural tree.

Session recording

Use record for debugging, documentation, or shareable verification artifacts.

agent-device record start ./recordings/ios.mov
agent-device open App
agent-device snapshot -i
agent-device press @e3
agent-device close
agent-device record stop

  • record supports iOS simulators, iOS devices, and Android.

  • On iOS, recording is a wrapper around simctl for simulators and the corresponding device capture path for physical devices.

  • On Android, recording is a wrapper around adb.

  • Recording writes a video artifact and a gesture-telemetry sidecar JSON.

  • On macOS hosts, touch overlay burn-in is available for supported recordings.

  • On non-macOS hosts, recording still succeeds but the video stays raw and record stop can return an overlayWarning.

  • If the agent already knows the interaction sequence and wants a more lifelike, uninterrupted recording, drive the flow with batch while recording instead of replanning between each step.

Example:

agent-device record start ./recordings/smoke.mov
agent-device batch --session sim --platform ios --steps-file /tmp/smoke-steps.json --json
agent-device record stop

  • Use this only after exploration has stabilized the flow.

  • Keep the batch short and add wait or is exists guards after mutating steps so the recorded flow still tracks realistic UI timing.

Replay maintenance

Use replay updates when selectors drift but the recorded scenario is still correct.

agent-device replay -u ./session.ad
agent-device test ./smoke --platform android

  • Prefer selector-based actions in recorded .ad replays.

  • Use test when you already have multiple .ad flows and need a quick regression pass after updating or recording them.

  • Keep the skill-level rule simple: use replay -u to maintain one script, use test to verify a folder or matcher of scripts.

  • Treat test as a human and CI-facing suite runner that an agent can invoke for verification, not as the main source of product documentation.

  • Failed runs keep suite artifacts under .agent-device/test-artifacts by default, which is usually enough for debugging without extra agent-side processing.

  • Use update mode for maintenance, not as a substitute for fixing a broken interaction strategy.

Performance checks

Use perf --json or metrics --json when you need startup timing for the active session.

agent-device open Settings --platform ios
agent-device perf --json

  • Current startup data is command round-trip timing around open.

  • It is not true first-frame or first-interactive telemetry.

  • fps, memory, and cpu are currently placeholders.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
Callstack
Publisher
Callstack (Official)
Source
callstackincubator/agent-skills · plugins/vendored/.agents/skills/agent-device · commit 59e9d17
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Callstack or Callstack.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download agent-device.zip