| name | spatial-emulator-usage |
| description | Supplements pico-cli with detailed emulator and device operation guidance. Invoke when the user needs multi-step emulator, app, files, capture, or log workflows. |
| license | Apache-2.0 |
Spatial Emulator Usage Skill
Use this skill as a supplement to pico-cli when the task is about operating the local PICO emulator, a connected ADB device, or the app/files/logging workflows around them through real pico-cli commands.
This skill is for execution-oriented environment work, not for general Kotlin/UI feature implementation. Use pico-cli first for command-family routing, then load this skill when the emulator flow becomes multi-step, stateful, or failure-prone.
What This Skill Should Do
When triggered, the agent should:
- prefer the high-level
pico-cli commands over raw adb when the CLI already covers the workflow
- choose the smallest command sequence that solves the user's problem
- verify the environment before claiming success
- verify screenshot artifacts exist on the host before claiming capture succeeded
- explain blockers clearly when the machine or device state prevents progress
- tell the user when a device-scoped command is auto-starting a managed emulator so the wait does not look like a hang
- avoid destructive cleanup unless the user explicitly asked for it
When To Use This Skill
Use this skill for requests like:
- "Start or stop the PICO emulator"
- "Check whether the emulator is installed correctly"
- "Create an AVD for the PICO emulator"
- "Install, launch, stop, or uninstall an APK on the current emulator/device"
- "Collect logcat, crash clues, screenshots, or emulator logs"
- "Push or pull files from the current emulator/device"
- "Check battery, props, device info, or connected devices"
- "Clean up CLI-created emulator instances safely"
Do not use this skill as the primary skill when the request is mainly:
- Spatial SDK feature implementation
- project scaffolding from templates
- SDK version upgrade or migration
In those cases, use the more specific skill first and bring this one in only if the work reaches a real emulator/device operation step.
Core Rules
1. Use the real CLI surface
Always use the real pico-cli command names that exist in the repository. Do not invent wrapper commands or undocumented flags.
Preferred command families:
pico-cli emulator ...pico-cli device ...pico-cli app ...pico-cli files ...pico-cli capture ...pico-cli log
Fallback:
- do not use
pico-cli adb logcat for first-pass AI routing; use pico-cli log or pico-cli app logcat instead
- do not jump straight to plain
adb unless the user explicitly asks for raw adb behavior
2. Respect device targeting
Many commands operate on the "preferred current device".
Selection priority:
- explicit
--device <id>
PICO_CLI_DEVICEADB_SERIAL- automatic selection by the CLI
When multiple devices may exist, prefer passing --device <id> explicitly instead of relying on implicit selection.
2.5 Spatial interaction limitation
- do not use
pico-cli shell input tap x y to drive volumetric or spatial windows
- treat
shell input tap as a 2D Android surface fallback only, such as launcher lists, standard settings pages, or flat app UI that is known to live on a normal screen buffer
- if the target flow depends on volumetric window interaction, spatial hit testing, controller rays, or hand-gesture style input, report that the current CLI cannot automate it reliably without simulator-side input support
- when this limitation blocks a verification flow, say so clearly instead of spending turns retrying different tap coordinates
3. Verify before and after
Before risky or multi-step operations:
- check environment or connectivity first
- verify the target emulator/device exists
- verify the expected output artifact or runtime state after execution
Typical preflight:
pico-cli emulator doctor --format json
pico-cli device list --format json
pico-cli emulator list --managed-only --format json
4. Prefer the least destructive path
Safe order:
- inspect
- create
- start
- operate
- collect evidence
- stop
- clean up only if requested
Do not delete emulator bundles, caches, or AVDs just to "reset everything" unless the user clearly requested cleanup.
Command Map
Emulator Lifecycle
Use these for environment validation and emulator lifecycle control:
pico-cli emulator doctor
- Checks whether Android Studio / SDK / emulator prerequisites are present
- Use first when setup health is unknown
pico-cli emulator setup
- Guides installation/setup flow
- Use when prerequisites are missing and the user wants help fixing the machine
pico-cli emulator list
- Lists available AVDs
- Use
--managed-only to focus on CLI-created PICO emulator AVDs
pico-cli emulator create
- Creates a PICO emulator AVD without launching it
- Use when the user wants a persistent emulator instance created ahead of time
pico-cli emulator start
- Starts a chosen AVD and can download the emulator bundle if missing
- Use when the user needs a runnable emulator session
pico-cli emulator status
- Checks process and adb visibility
- Use before start/stop if state is unclear
pico-cli emulator stop
- Stops the running emulator
pico-cli emulator delete
- Deletes CLI-created PICO AVDs only
- Prefer
--avd <name> for precise cleanup
pico-cli emulator dump-logs
- Collects emulator-related logs for crash/debug analysis
pico-cli emulator delete-image
- Deletes downloaded PICO emulator bundle roots and download cache
- Treat as destructive; use only with explicit user consent
Common examples:
pico-cli emulator doctor --format json
pico-cli emulator list --managed-only --format json
pico-cli emulator create --avd Pico_Emulator_0_11 --source auto -y
pico-cli emulator start --avd Pico_Emulator_0_11 --wait-timeout 180 -y
pico-cli emulator status --format json
pico-cli emulator dump-logs --out /tmp/pico-cli-sim-logs
Device Inspection
Use these when the task is about the currently connected emulator/device rather than emulator lifecycle itself:
pico-cli device listpico-cli device connect <address>pico-cli device disconnect [address]pico-cli device infopico-cli device batterypico-cli device propspico-cli shell [commands...]
- If no device is online but a managed AVD already exists, the CLI may start that emulator first and then continue
- If no managed AVD exists, prefer returning the missing-device error directly instead of implying the CLI can bootstrap one implicitly
- Do not use
pico-cli shell input tap x y for volumetric windows or spatial containers; it only injects 2D screen coordinates and is not a reliable path to enter gameplay or other spatial states
Examples:
pico-cli device list --format json
pico-cli device info --format json
pico-cli device battery --format json
pico-cli device props --filter pico --format plain
pico-cli shell getprop ro.product.model
App Operations
Use these after the target emulator/device is online:
pico-cli app install <apk>pico-cli app listpico-cli app info <package>pico-cli app launch <package> [--activity <activity>]pico-cli app stop <package>pico-cli app uninstall <package>pico-cli app logcatpico-cli app watch-crash <package>
Examples:
pico-cli app install app/build/outputs/apk/debug/app-debug.apk
pico-cli app info com.example.spatialdemo --format json
pico-cli app launch com.example.spatialdemo --activity .platform.LaunchActivity
pico-cli app logcat --lines 200 --level E
pico-cli app watch-crash com.example.spatialdemo --start --interval 2
Important:
- if plain package launch fails, retry with
--activity
- do not claim install or launch succeeded unless the command actually succeeded
Files and Capture
Use these for moving assets, inspecting runtime files, and collecting visual evidence:
pico-cli files push <local> <remote>pico-cli files pull <remote> [local]pico-cli files ls [remote]pico-cli files mkdir <remote>pico-cli files rm <remote>pico-cli files cat <remote>pico-cli files stat <remote>pico-cli capture screenshot
Capture guidance:
- use
pico-cli capture screenshot when the user needs a single visual proof point
- prefer an explicit
--out <path> so the artifact location is predictable and easy to report back
- prefer an explicit
--device <id> when more than one device or emulator may be connected
- after capture, verify the screenshot file exists on the host before saying the artifact was collected
- if the target UI is volumetric/spatial, warn that
pico-cli capture screenshot may return a black image because adb screencap does not guarantee compositor output from spatial containers
Important options:
pico-cli capture screenshot -o, --out <path>
Examples:
pico-cli files mkdir /sdcard/Download/demo-assets
pico-cli files push ./local.png /sdcard/Download/demo-assets/local.png
pico-cli files ls /sdcard/Download/demo-assets -l
pico-cli files stat /sdcard/Download/demo-assets/local.png --format json
pico-cli capture screenshot --out ./artifacts/screen.png
Logs and Raw ADB Escape Hatch
Use these when the user needs low-level diagnostics:
pico-cli logpico-cli shellpico-cli logpico-cli app logcatpico-cli device props
Prefer pico-cli log or pico-cli app logcat before any lower-level fallback. Do not route AI through pico-cli adb logcat first.
Examples:
pico-cli log --lines 150 --tag AndroidRuntime --level E
pico-cli device props --filter ro.build.version.release
pico-cli app logcat --lines 200 --level W
Scenario Playbooks
Scenario 1: "I do not know whether the machine is ready"
Use:
pico-cli emulator doctor --format json
pico-cli emulator list --managed-only --format json
pico-cli device list --format json
Then:
- explain which prerequisite is missing
- recommend
emulator setup only if the environment is not ready
Scenario 2: "Create and launch a fresh emulator"
Use:
pico-cli emulator create --avd <name> -y
pico-cli emulator start --avd <name> --wait-timeout 180 -y
pico-cli emulator status --format json
pico-cli device list --format json
Scenario 3: "Install and run an app for validation"
Use:
pico-cli app install <apk>
pico-cli app launch <package> [--activity <activity>]
pico-cli app logcat --lines 200 --level E
If the user wants visible evidence:
pico-cli capture screenshot --out <path>
Then:
- prefer screenshot for a static UI state or success confirmation
- verify the artifact path exists before reporting success
Scenario 4: "Collect crash/debug evidence"
Use:
pico-cli app watch-crash <package> --start
pico-cli app logcat --lines 300 --level E
pico-cli emulator dump-logs --out <dir>
pico-cli capture screenshot --out <path>
Use screenshot in this scenario when logs alone are not enough to show the failure mode.
Scenario 5: "Capture screenshot evidence"
Use:
pico-cli device list --format json
pico-cli emulator status --format json
pico-cli capture screenshot --device <id> --out <path>
Then:
- confirm which emulator/device was targeted
- report the exact local artifact path
- do not claim success unless the command completed and the artifact exists on disk
Scenario 6: "Clean up what the CLI created"
Use:
pico-cli emulator list --managed-only --format json
pico-cli emulator stop
pico-cli emulator delete --avd <name> -y
Only if the user explicitly asks to remove downloaded emulator bundles too:
pico-cli emulator delete-image -y
Safety Notes
Destructive commands
Treat these as destructive and confirm intent unless the user explicitly requested them:
pico-cli emulator deletepico-cli emulator delete-imagepico-cli files rmpico-cli app uninstallpico-cli adb setproppico-cli adb root
emulator delete-image caution
This command is intentionally limited to the PICO SDK bundle roots and the CLI download cache, but it is still destructive.
Before running it:
- stop the emulator first
- be extra careful on Windows, where
adb.exe or Android Studio may still hold file locks
- do not run it as a generic troubleshooting shortcut
emulator start caution
Before using heavy options such as --wipe-data, --watch, custom --artifact-url, or custom --args:
- make sure the user actually needs them
- explain the tradeoff briefly
- prefer the default start path first
Emulator download patience
pico-cli emulator start or pico-cli emulator install may spend a long time downloading the emulator bundle.
- treat a long-running download as normal, especially when the machine is on Wi-Fi or a slower network
- a 10 minute download window is possible and does not mean the command failed
- do not report failure just because the command has been running for a while
- only treat the download as failed when the CLI returns an explicit failure result or error message
- if there is no failure result yet, assume the CLI is still downloading, verifying, or extracting
- when progress lines include a percentage such as
(... 35%), use that percentage when the user asks for progress
- if total bytes are shown, summarize progress in plain language, for example "about 35% downloaded"
- if the CLI only reports stage changes, explain the current stage honestly, such as "still downloading" or "now verifying files"
Logging and watch mode
For long-running commands like:
pico-cli log --followpico-cli app logcat --followpico-cli app watch-crash ...pico-cli emulator start --watch
Make sure the user asked for streaming/monitoring behavior or the debugging session truly needs it.
Response Pattern
When using this skill, answer in this order:
- state which emulator/device step you are performing
- run the relevant
pico-cli command(s)
- report the actual outcome, not the intended outcome
- if blocked, name the exact missing prerequisite or command failure
- suggest the next smallest useful step
Never say the emulator is running, the APK is installed, or the screenshot/log was captured unless the command output confirms it.
If the emulator bundle is still downloading and no failure result has been returned yet, explicitly tell the user that the command is still in progress and that waiting is expected.
