iOS Simulator Skill for Agents

Production-ready skill for building, testing, and automating iOS apps. 29 scripts optimized for both human developers and AI agents.

(If you'd prefer an MCP, XC-MCP -> NPM )

Xcode Build + Simulator Automation

This skill covers both sides of iOS development:

• Xcode builds via xcodebuild — compile, test, and parse results with progressive error disclosure
• Simulator interaction via xcrun simctl and idb — semantic UI navigation, accessibility testing, device lifecycle

If you only need Xcode build tooling without the simulator scripts, see the plugin version: xclaude-plugin

Installation

Via Plugin Marketplace (Recommended)

In Claude Code:

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

Manual install

A skill is loaded from SKILL.md at the root of its directory — ~/.claude/skills/<name>/SKILL.md. This repository is a plugin, so the skill itself lives at ios-simulator-skill/skills/ios-simulator-skill/; cloning the whole repo into your skills directory puts SKILL.md three levels too deep and the skill will not load.

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

From a clone (to track main):

git clone https://github.com/conorluddy/ios-simulator-skill.git ~/src/ios-simulator-skill
cp -R ~/src/ios-simulator-skill/ios-simulator-skill/skills/ios-simulator-skill \
      ~/.claude/skills/ios-simulator-skill

For a project-local install, use .claude/skills/ios-simulator-skill as the destination instead. Either way, restart Claude Code afterwards; verify with ls ~/.claude/skills/ios-simulator-skill/SKILL.md.

Prerequisites

Requirement	Version	Needed for
macOS	15 (Sequoia)+	everything
Xcode + Command Line Tools	26+ (xcode-select --install)	building, simctl
Python	3.12+	every script
idb (CLI + companion)	1.5.1+	tapping, swiping, typing
Pillow	any	visual diffs only (pip3 install pillow)

Install idb — required for every interactive script (navigator.py, gesture.py, keyboard.py):

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

brew install idb-companion no longer works: idb-companion was removed from Homebrew core and now lives in Meta's own facebook/fb tap. If you followed older instructions, see Updating idb.

To verify everything at once:

bash scripts/sim_health_check.sh          # add --json for machine-readable output

Updating idb

On Xcode 27, idb-companion must be 1.5.1 or newer. Older builds look for SimulatorKit.framework where Xcode 26 kept it. Under Xcode 27 the companion still starts and the accessibility tree still reads correctly, but every tap, swipe and keystroke is silently dropped — idb reports success and nothing happens on screen.

brew upgrade facebook/fb/idb-companion facebook/fb/idb-cli
brew list --versions idb-companion        # expect >= 1.5.1

Coming from the old pip package? pip install fb-idb still provides a working idb CLI, but the Homebrew idb-cli above is the maintained path. If both are installed, whichever comes first on your PATH wins — check with which -a idb.

Xcode 27 notes

• There is no Simulator.app. Xcode 27 replaced it with DeviceHub.app, in Xcode.app/Contents/Applications/. Scripts drive simulators headlessly via simctl and idb, so you rarely need either — but open -a Simulator will fail.
• Quitting DeviceHub shuts down the simulator it is hosting.
• If idb calls start failing with Connection refused after a crash or a manual pkill, a dead companion is still registered. Clear it with idb disconnect <udid>; sim_health_check.sh detects this.

Features

Xcode Build with Progressive Disclosure

The build_and_test.py script wraps xcodebuild with token-efficient output. A build returns a single summary line with an xcresult ID:

Build: SUCCESS (0 errors, 3 warnings) [xcresult-20251018-143052]

Then drill into details on demand:

python scripts/build_and_test.py --get-errors xcresult-20251018-143052
python scripts/build_and_test.py --get-warnings xcresult-20251018-143052
python scripts/build_and_test.py --get-log xcresult-20251018-143052

This keeps agent conversations focused — no walls of build output unless you ask for them.

Simulator Navigation via Accessibility

Instead of fragile pixel-coordinate tapping, all navigation uses iOS accessibility APIs to find elements by meaning:

# Fragile — breaks if UI changes
idb ui tap 320 400

# Robust — finds by meaning
python scripts/navigator.py --find-text "Login" --tap

The accessibility tree gives structured data (element types, labels, frames, tap targets) at ~10 tokens default output vs 1,600-6,300 tokens for a screenshot. See AI-Accessible Apps for more on why accessibility-first navigation matters for AI agents.

Screenshot Token Optimization

When screenshots are needed (visual verification, bug reports, diffs), the skill automatically resizes and compresses them to minimize token cost. Default output across all 29 scripts is 3-5 lines — 96% reduction vs raw tool output.

Task	Raw Tools	This Skill	Savings
Screen analysis	200+ lines	5 lines	97.5%
Find & tap button	100+ lines	1 line	99%
Login flow	400+ lines	15 lines	96%

All 29 Scripts

Every script supports --help and --json. See SKILL.md for the complete reference.