feat: replace bulky skills with versioned CLI help

README.md

@@ -29,12 +29,26 @@ If you know Vercel's [agent-browser](https://github.com/vercel-labs/agent-browse
 
 ## Quick Start
 
-Install the CLI.
+Install the CLI first:
 
 ```bash
 npm install -g agent-device
+agent-device --version
+agent-device help workflow
 ```
 
+The CLI help is the source of truth for agents and is shipped with the installed version. Skills are optional but recommended when your agent runtime supports them: they auto-route device, React DevTools, and dogfood tasks to the right `agent-device help <topic>` page and verify the CLI is new enough before acting.
+
+If you install skills separately, keep the CLI on `agent-device >= 0.13.4`. Older CLIs do not include the workflow help topics that the router skills expect.
+
+```bash
+npm install -g agent-device@latest
+agent-device --version
+agent-device help
+```
+
+`agent-device` performs a lightweight background upgrade check for interactive CLI runs and, when a newer package is available, suggests a global reinstall command. Updating the package also refreshes the bundled `skills/` shipped with the CLI.
+
 Prerequisites: Node.js 22+, Xcode for iOS/tvOS/macOS targets, Android SDK + ADB for Android, and macOS Accessibility permission for desktop automation. See [Installation](https://incubator.callstack.com/agent-device/docs/installation).
 
 Try the loop.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-device",
-  "version": "0.13.3",
+  "version": "0.13.4",
   "description": "Agent-driven CLI for mobile UI automation, network inspection, and performance diagnostics across iOS, Android, tvOS, and macOS.",
   "license": "MIT",
   "author": "Callstack",
@@ -100,7 +100,7 @@
     "test-app:typecheck": "pnpm --dir examples/test-app typecheck",
     "test": "vitest run",
     "test:unit": "vitest run",
-    "test:skillgym": "skillgym run ./test/skillgym/suites/agent-device-smoke-suite.ts --config ./test/skillgym/skillgym.config.ts",
+    "test:skillgym": "pnpm build && skillgym run ./test/skillgym/suites/agent-device-smoke-suite.ts --config ./test/skillgym/skillgym.config.ts",
     "test:smoke": "node --test test/integration/smoke-*.test.ts",
     "test:integration": "node --test test/integration/*.test.ts",
     "test:replay:ios": "node --experimental-strip-types src/bin.ts test test/integration/replays/ios/simulator",

skills/agent-device/SKILL.md

@@ -1,76 +1,34 @@
 ---
 name: agent-device
-description: Automates interactions for Apple-platform apps (iOS, tvOS, macOS) and Android devices. Use when navigating apps, taking snapshots/screenshots, tapping, typing, scrolling, extracting UI info, or collecting logs, network inspection, and perf snapshots across mobile, TV, and desktop targets.
+description: Automates Apple-platform apps (iOS, tvOS, macOS) and Android devices. Use when navigating apps, taking snapshots/screenshots, tapping, typing, scrolling, extracting UI info, collecting logs/network/perf evidence, or planning agent-device CLI commands.
 ---
 
 # 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.
+Router only. Private setup before using this skill:
 
-## Default operating rules
+```bash
+agent-device --version
+```
 
-- 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.
-- In Metro-backed React Native dev loops, use `agent-device metro reload` for a JS app reload before falling back to `open <app> --relaunch`. It mirrors pressing `r` in the Metro terminal and preserves the native app process.
-- 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 appears only in an off-screen summary, use `scroll <direction>` and re-snapshot until the target is visible.
-- 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`.
+Require `agent-device >= 0.13.4`; older CLIs lack these help topics. If older, run `npm install -g agent-device@latest`, recheck, then continue. If you cannot upgrade, stop and tell the user. Do not include version/upgrade commands in final plans.
 
-## Default flow
+Before your first agent-device command or plan, read the version-matched CLI guide:
 
-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`.
+```bash
+agent-device help workflow
+```
 
-## QA modes
+Escalate only when relevant:
 
-- 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).
+```bash
+agent-device help debugging
+agent-device help react-devtools
+agent-device help remote
+agent-device help macos
+agent-device help dogfood
+```
 
-## Required references
+Default loop: `open -> snapshot/-i -> get/is/find or press/fill/scroll/wait -> verify -> close`.
 
-- 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.
-
-## 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 `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.
-- For React Native code changes where the app is already connected to Metro, prefer `agent-device metro reload`, then wait and re-snapshot. Use `open <app> --relaunch` only when Metro reload does not reconnect or native startup state must reset.
-- 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
-
-- 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 desktop surfaces, menu bar behavior, or macOS-specific interaction rules: [references/macos-desktop.md](references/macos-desktop.md)
-- Need remote HTTP transport, `connect --remote-config`, or tenant leases on a remote macOS host: [references/remote-tenancy.md](references/remote-tenancy.md)
-  This includes remote React Native runs where `agent-device` now prepares Metro locally and manages the local Metro companion tunnel automatically.
-- Need the React Native component tree, props, state, hooks, or render profiling: use `agent-device react-devtools ...` and the [react-devtools skill](../react-devtools/SKILL.md).
+Keep refs current, prefer selectors/refs over coordinates, use `fill` to replace text, and use `back` for app-owned navigation. Let `help workflow` provide the exact command shapes.