Agent Device

Automates interactions for iOS simulators/devices and Android emulators/devices. Use when navigating apps, taking snapshots/screenshots, tapping, typing, scr...

Security Scan

The skill's documentation and runtime instructions are internally consistent with a mobile automation CLI: it documents running a local agent-device CLI, optional iOS signing env vars for physical devices, and local log/artifact paths — nothing indicates hidden or unrelated behavior.

Purpose & Capability

The name/description match the provided SKILL.md and reference files: everything documents CLI commands for iOS/Android automation (open, snapshot, press, replay, logs, record, batch, etc.). There are no unrelated required binaries, credentials, or install steps requested by the manifest that would contradict the stated purpose.

Instruction Scope

The instructions legitimately direct the agent to run local CLI commands and to read/write session logs and replay scripts under ~/.agent-device (and platform-specific paths like ~/Library/Logs/DiagnosticReports). This is expected for a mobile automation tool, but those steps do give the skill access to potentially sensitive local app logs and artifacts; references also mention optional signing env vars for physical iOS devices. The SKILL.md does not instruct exfiltration to external endpoints.

Install Mechanism

This is an instruction-only skill with no install spec or bundled code, minimizing install risk. The doc recommends preferring a preinstalled binary or pinning an exact package version if installing via npx, which is reasonable guidance.

Credentials

The manifest declares no required env vars; the docs reference optional sensitive variables (AGENT_DEVICE_IOS_TEAM_ID, AGENT_DEVICE_IOS_SIGNING_IDENTITY, AGENT_DEVICE_IOS_PROVISIONING_PROFILE, AGENT_DEVICE_APP_LOG_REDACT_PATTERNS) that are proportionate to iOS physical-device signing and log redaction. These are optional and the docs explicitly advise treating them as sensitive; still, providing signing credentials would be high privilege and should be done only when necessary.

Persistence & Privilege

always is false; the skill does not request forced inclusion or modification of other skills. It documents writing logs, session state, daemon metadata, and saved replay scripts under ~/.agent-device and explicit paths you supply, which is appropriate for its function and scoped to its own data.

Assessment

This skill appears coherent and matches its description, but be aware of two practical risks: (1) logs and session artifacts are written to your home (~/.agent-device) and may contain sensitive runtime data — review and redact before sharing; (2) iOS physical-device workflows may require optional signing environment variables (team ID, signing identity, provisioning profile) which are sensitive — do not populate these unless you trust the environment and understand the implications. Prefer using an already-installed, pinned agent-device binary (or a pinned npx invocation) and run automation in isolated/least-privilege environments when granting signing or CI access. If you need higher assurance, ask the publisher for an exact binary/package URL or provenance and a reproducible install artifact to audit before installing or running.

Mobile Automation with agent-device

For exploration, use snapshot refs. For deterministic replay, use selectors.

Start Here (Read This First)

Use this skill as a router, not a full manual.

1. Pick one mode:
   • Normal interaction flow
   • Debug/crash flow
   • Replay maintenance flow
2. Run one canonical flow below.
3. Open references only if blocked.

Decision Map

• No target context yet: devices -> pick target -> open.
• Normal UI task: open -> snapshot -i -> press/fill -> diff snapshot -i -> close
• Debug/crash: open <app> -> logs clear --restart -> reproduce -> logs path -> targeted grep
• Replay drift: replay -u <path> -> verify updated selectors

Canonical Flows

1) Normal Interaction Flow

agent-device open Settings --platform ios
agent-device snapshot -i
agent-device press @e3
agent-device diff snapshot -i
agent-device fill @e5 "test"
agent-device close

2) Debug/Crash Flow

agent-device open MyApp --platform ios
agent-device logs clear --restart
agent-device logs path

Logging is off by default. Enable only for debugging windows. logs clear --restart requires an active app session (open <app> first).

3) Replay Maintenance Flow

agent-device replay -u ./session.ad

Command Skeleton (Minimal)

Session and navigation

agent-device devices
agent-device open [app|url] [url]
agent-device open [app] --relaunch
agent-device close [app]
agent-device session list

Use boot only as fallback when open cannot find/connect to a ready target.

Snapshot and targeting

agent-device snapshot -i
agent-device diff snapshot -i
agent-device find "Sign In" click
agent-device press @e1
agent-device fill @e2 "text"
agent-device is visible 'id="anchor"'

press is canonical tap command; click is an alias.

Utilities

agent-device appstate
agent-device get text @e1
agent-device screenshot out.png
agent-device trace start
agent-device trace stop ./trace.log

Batch (when sequence is already known)

agent-device batch --steps-file /tmp/batch-steps.json --json

Guardrails (High Value Only)

• Re-snapshot after UI mutations (navigation/modal/list changes).
• Prefer snapshot -i; scope/depth only when needed.
• Use refs for discovery, selectors for replay/assertions.
• Use fill for clear-then-type semantics; use type for focused append typing.
• iOS appstate is session-scoped; Android appstate is live foreground state.
• iOS settings helpers are simulator-only; use faceid match|nonmatch|enroll|unenroll.
• If using --save-script, prefer explicit path syntax (--save-script=flow.ad or ./flow.ad).

Security and Trust Notes

• Prefer a preinstalled agent-device binary over on-demand package execution.
• If install is required, pin an exact version (for example: npx --yes agent-device@<exact-version> --help).
• Signing/provisioning environment variables are optional, sensitive, and only for iOS physical-device setup.
• Logs/artifacts are written under ~/.agent-device; replay scripts write to explicit paths you provide.
• Keep logging off unless debugging and use least-privilege/isolated environments for autonomous runs.

Common Mistakes

• Mixing debug flow into normal runs (keep logs off unless debugging).
• Continuing to use stale refs after screen transitions.
• Using URL opens with Android --activity (unsupported combination).
• Treating boot as default first step instead of fallback.

References

• references/snapshot-refs.md
• references/logs-and-debug.md
• references/session-management.md
• references/permissions.md
• references/video-recording.md
• references/coordinate-system.md
• references/batching.md