Build, Run, and Probe iOS Apps From Claude Code With ios-simulator-skill

An agent asked to "build the app and tap through the login screen" faces two walls: xcodebuild output that floods the context window, and simulator UI it cannot see. ios-simulator-skill is a production-ready skill — 29 scripts wrapping xcodebuild, xcrun simctl, and idb — that handles both: builds come back as one-line summaries, and UI navigation finds buttons by meaning instead of pixel coordinates.

Why This Skill Matters

The token math is the point. A screenshot costs 1,600–6,300 tokens; the accessibility tree this skill navigates by costs about 10 tokens for default output. Across all 29 scripts, the README reports 3–5 lines of default output — a 96% reduction versus raw tool output. Build results work the same way: one summary line plus an xcresult ID, with details disclosed only when you ask.

Navigation goes through iOS accessibility APIs: navigator.py --find-text "Login" --tap finds the button by label, which survives layout changes that would break a hardcoded idb ui tap 320 400. The script set covers the full loop — build and test, device state (dark mode, locale, GPS simulation), gestures and keyboard, accessibility audits, visual diffs, push-notification simulation, permission management, and simulator lifecycle.

Installation

In Claude Code, via the plugin marketplace:

/plugin marketplace add conorluddy/ios-simulator-skill
/plugin install ios-simulator-skill@conorluddy

Manual install from a release (simplest):

curl -L https://github.com/conorluddy/ios-simulator-skill/releases/latest/download/ios-simulator-skill.zip -o skill.zip
unzip skill.zip -d ~/.claude/skills/ios-simulator-skill

Do not clone the whole repo into your skills directory — this repository is a plugin, so the actual skill lives at ios-simulator-skill/skills/ios-simulator-skill/, and a raw clone leaves SKILL.md three levels too deep to load.

Prerequisites: macOS 15+, Xcode 26+ with Command Line Tools, Python 3.12+, and idb 1.5.1+ (needed by every interactive script; Pillow only for visual diffs). Install idb from Meta's tap:

brew tap facebook/fb
brew install facebook/fb/idb-companion facebook/fb/idb-cli

Then verify the environment in one shot:

bash scripts/sim_health_check.sh

Real Workflow: Fix a Login Bug the Agent Can See

1. Build and test with progressive disclosure:

python scripts/build_and_test.py --project MyApp.xcodeproj --scheme MyApp

2. The result is one line — Build: SUCCESS (0 errors, 3 warnings) [xcresult-...]. Drill in on demand with --get-errors, --get-warnings, or --get-log plus that xcresult ID.
3. Boot a simulator, launch the app, and navigate semantically:

python scripts/navigator.py --find-text "Login" --tap

4. Hand the agent the bug and let it drive the loop itself:

登录按钮点击后没有跳转。用 ios-simulator-skill 启动 app，走到登录页复现这个问题，
把截图和控件层级一起带回来。

5. On Xcode 27, remember there is no Simulator.app — it was replaced by DeviceHub.app; the scripts drive simulators headlessly via simctl and idb, so this rarely matters, but open -a Simulator will fail.

Tips

• Tune limits with IOS_SIM_* environment variables. For a slow GitHub Actions macOS runner: IOS_SIM_BOOT_TIMEOUT=600 python scripts/simctl_boot.py --wait-ready.
• There is a real tradeoff in those knobs: higher caps mean fewer false failures and fuller diagnostics but more tokens; lower caps mean faster feedback but risk silently dropped errors or premature timeouts on legitimately slow operations.
• If idb calls fail with Connection refused after a crash, a dead companion is still registered — clear it with idb disconnect <udid>; the health check detects this.
• brew install idb-companion no longer works: the package moved to Meta's own facebook/fb tap. On Xcode 27, an older companion silently drops every tap and keystroke — upgrade to 1.5.1+.
• The README reports Claude Code evals at 100% pass with the skill (3/3) versus 46% without — worth re-running against your own app via claude evals run evals/evals.json --skill ios-simulator-skill.

When Not to Use This

It needs a Mac, Xcode 26+, and a Python 3.12+ toolchain — CI-only Linux builds gain nothing. And if you only want Xcode build tooling without simulator interaction, the same author ships a plugin version, xclaude-plugin, without the simulator scripts.

See the leaderboard for more skills.