iOS Simulator Skill for Claude Code

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

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

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

Via Git Clone

# Personal installation
git clone https://github.com/conorluddy/ios-simulator-skill.git ~/.claude/skills/ios-simulator-skill

# Project installation
git clone https://github.com/conorluddy/ios-simulator-skill.git .claude/skills/ios-simulator-skill

Restart Claude Code. The skill loads automatically.

Prerequisites

• macOS 12+
• Xcode Command Line Tools (xcode-select --install)
• Python 3
• IDB (optional, for interactive features: brew tap facebook/fb && brew install idb-companion)
• Pillow (optional, for visual diffs: pip3 install pillow)

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 27 scripts is 3-5 lines — 96% reduction vs raw tool output.

All 27 Scripts

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

Build & Development

Device State

Navigation & Interaction

Testing & Analysis

Permissions & Environment

Device Lifecycle

Configuration

Every operational limit — timeouts, output caps, polling intervals, cache size, post-action delays — is tunable via an IOS_SIM_* environment variable. Defaults are tuned for local development on Apple Silicon. Raise them on slow CI runners, large monorepos, or accessibility audits over complex screens. Lower them when you need faster failure or tighter token budgets.

There's a universal tradeoff to keep in mind:

• Higher caps / longer timeouts → fewer false failures, more complete diagnostics, more tokens consumed by AI agents and slower failures when something is genuinely broken.
• Lower caps / shorter timeouts → faster feedback, tighter token usage, risk of silently dropped errors or premature timeouts on legitimately slow operations.

Boot & lifecycle timeouts

How long to wait on xcrun simctl operations.

Build & test output caps

build_and_test.py returns counts by default and full details via xcresult ID; these caps govern what's surfaced in human/JSON output before progressive disclosure kicks in.