Skip to content

Device Operator Skill

The device-operator skill teaches an AI coding agent (Claude Code or Codex) to operate a connected iPhone or iPad with pymobiledevice3. Use it when an agent needs to handle:

  • connectivity and transport selection
  • crash/log/file collection
  • app/container operations
  • DVT and other developer services
  • WebInspector and WDA automation
  • Python scripting against the library
  • thin CLI additions on top of existing services

The skill lives in this repository:

  • Skill file: .codex/skills/pymobiledevice3-device-operator/SKILL.md
  • Reference file: .codex/skills/pymobiledevice3-device-operator/references/quick-recipes.md
  • Reference file: .codex/skills/pymobiledevice3-device-operator/references/python-scripting.md
  • Reference file: .codex/skills/pymobiledevice3-device-operator/references/task-map.md
  • Reference file: .codex/skills/pymobiledevice3-device-operator/references/transport-and-safety.md

Inside a checkout, the skill is discovered automatically by both Codex (via .codex/skills/) and Claude Code (via a symlink in .claude/skills/). The two skill trees mirror each other with relative symlinks; see Skills in the agent guidance for the full inventory and the edit-the-canonical-copy convention.

Install Into Your Own Claude Code

You do not need to work inside this repository to use the skill. The commands it teaches run against the PyPI release via uvx pymobiledevice3 ..., so a fresh workstation only needs uv and a USB-connected device. Without uv, the skill falls back to a plain pip install and can also install uv without root.

As a plugin (recommended). This repository doubles as a Claude Code plugin marketplace. Inside Claude Code run:

/plugin marketplace add doronz88/pymobiledevice3
/plugin install pymobiledevice3-device-operator@pymobiledevice3

After installing, Claude can take screenshots, search the device syslog, pull crash reports, manage apps and files, and drive developer services from any directory.

As a personal skill (manual). Clone the repository once and symlink the skill into your personal skills directory:

git clone https://github.com/doronz88/pymobiledevice3.git
mkdir -p ~/.claude/skills
ln -s "$(pwd)/pymobiledevice3/.codex/skills/pymobiledevice3-device-operator" ~/.claude/skills/

Use From GitHub

To use the skill from an agent that cannot install it (for example Codex working against the GitHub repository), point the agent at these URLs:

  • Skill URL: https://github.com/doronz88/pymobiledevice3/blob/master/.codex/skills/pymobiledevice3-device-operator/SKILL.md
  • Quick recipes URL: https://github.com/doronz88/pymobiledevice3/blob/master/.codex/skills/pymobiledevice3-device-operator/references/quick-recipes.md
  • Python scripting URL: https://github.com/doronz88/pymobiledevice3/blob/master/.codex/skills/pymobiledevice3-device-operator/references/python-scripting.md
  • Task map URL: https://github.com/doronz88/pymobiledevice3/blob/master/.codex/skills/pymobiledevice3-device-operator/references/task-map.md
  • Transport and safety URL: https://github.com/doronz88/pymobiledevice3/blob/master/.codex/skills/pymobiledevice3-device-operator/references/transport-and-safety.md

Example prompt:

Use the pymobiledevice3 device-operator skill:
https://github.com/doronz88/pymobiledevice3/blob/master/.codex/skills/pymobiledevice3-device-operator/SKILL.md
Also use its references:
https://github.com/doronz88/pymobiledevice3/blob/master/.codex/skills/pymobiledevice3-device-operator/references/quick-recipes.md
https://github.com/doronz88/pymobiledevice3/blob/master/.codex/skills/pymobiledevice3-device-operator/references/python-scripting.md
https://github.com/doronz88/pymobiledevice3/blob/master/.codex/skills/pymobiledevice3-device-operator/references/task-map.md
https://github.com/doronz88/pymobiledevice3/blob/master/.codex/skills/pymobiledevice3-device-operator/references/transport-and-safety.md

What The Skill Enforces

  • Prefer existing CLI commands and service modules over new abstractions.
  • Prefer uvx --from . pymobiledevice3 ... inside a local checkout, and uvx pymobiledevice3 ... without one.
  • Prefer reading local docs and CLI source before invoking --help.
  • Treat --help as a fallback or final verification step.
  • Require explicit user intent before state-changing or destructive device actions.
  • Check transport, developer-mode, image-mount, and tunnel prerequisites before assuming a code bug.

Transport Notes

For iOS 17+ developer services, the skill routes users through the project tunnel documentation and transport rules in:

  • iOS 17+ tunnels
  • .codex/skills/pymobiledevice3-device-operator/references/transport-and-safety.md

On iOS 17.4+ no tunnel setup is needed at all: commands that require an RSD tunnel establish a no-root in-process userspace tunnel automatically, so the skill routes agents straight to the target command. On macOS, iOS 17.0-17.3 devices fall back to the no-root --native tunnel. Privileged tunnels (tunneld, start-tunnel) remain the fallback for iOS 17.0-17.3 devices on Linux/Windows, or when the no-root paths are not viable (e.g. a tunnel shared across processes or reachable by external tools).

For agent-driven start-tunnel startup on those fallback paths, the skill prefers lockdown start-tunnel --script-mode or remote start-tunnel --script-mode (with sudo if tunnel interface creation needs elevated privileges), then reads the RSD connection details from stdout and feeds those exact values into later --rsd HOST PORT commands.

When Updating The Project

If you add, remove, or substantially change device-facing CLI behavior, update the skill guidance when needed so agents keep routing requests correctly.

In practice, review the skill when changes affect:

  • top-level or nested CLI command layout
  • transport selection (USB, --rsd, --tunnel)
  • iOS version-specific command routing
  • safety expectations for state-changing commands
  • preferred service module or CLI entry point for a task