iOS Simulator Skill for Claude Code

Name: ios-simulator-skill
Author: conorluddy

Production-ready automation for iOS app testing and building. 21 scripts optimized for both human developers and AI agents.

This is basically a Skill version of my XCode MCP: https://github.com/conorluddy/xc-mcp

[!WARNING]
You want to take the ios-simulator-skill directory from this repo and drop it into your skills directory - not this entire repo. I'll update this soon with an easier approach. Feel free to fork this and get Claude to adjust it to your specific needs.

MCPs load a lot of tokens into the context window when they're active, but also seem to work really well. Skills don't load in any context. I'll make a plugin next and try to find the balance...

Updated: The Plugin version lets you easily disable MCPs for different tool groups. Optimise your context window by only enabling the tools you're actively using, such as xcodebuild: https://github.com/conorluddy/xclaude-plugin

What It Does

Instead of pixel-based navigation that breaks when UI changes:

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

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

Uses semantic navigation on accessibility APIs to interact with elements by their meaning, not coordinates. Works across different screen sizes and survives UI redesigns.

Features

21 production scripts for building, testing, and automation
Semantic navigation - find elements by text, type, or ID
Token optimized - 96% reduction vs raw tools (3-5 lines default)
Zero configuration - works immediately on macOS with Xcode
Structured output - JSON and formatted text, easy to parse
Auto-UDID detection - no need to specify device each time
Batch operations - boot, delete, erase multiple simulators at once
Comprehensive testing - WCAG compliance, visual diffs, accessibility audits
CI/CD ready - JSON output, exit codes, automated device lifecycle

Installation

As Claude Code Skill

# 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.

From Release

# Download latest release
curl -L https://github.com/conorluddy/ios-simulator-skill/releases/download/vX.X.X/ios-simulator-skill-vX.X.X.zip -o skill.zip

# Extract
unzip skill.zip -d ~/.claude/skills/ios-simulator-skill

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)

Quick Start

# 1. Check environment
bash ~/.claude/skills/ios-simulator-skill/scripts/sim_health_check.sh

# 2. Launch your app
python ~/.claude/skills/ios-simulator-skill/scripts/app_launcher.py --launch com.example.app

# 3. See what's on screen
python ~/.claude/skills/ios-simulator-skill/scripts/screen_mapper.py
# Output:
# Screen: LoginViewController (45 elements, 7 interactive)
# Buttons: "Login", "Cancel", "Forgot Password"
# TextFields: 2 (0 filled)

# 4. Tap login button
python ~/.claude/skills/ios-simulator-skill/scripts/navigator.py --find-text "Login" --tap

# 5. Enter text
python ~/.claude/skills/ios-simulator-skill/scripts/navigator.py --find-type TextField --enter-text "[email protected]"

# 6. Check accessibility
python ~/.claude/skills/ios-simulator-skill/scripts/accessibility_audit.py

21 Scripts Organized by Category

Build & Development

build_and_test.py - Build projects, run tests, parse results
log_monitor.py - Real-time log monitoring

Navigation & Interaction

screen_mapper.py - Analyze current screen
navigator.py - Find and interact with elements
gesture.py - Swipes, scrolls, pinches
keyboard.py - Text input and hardware buttons
app_launcher.py - App lifecycle control

Testing & Analysis

accessibility_audit.py - WCAG compliance checking
visual_diff.py - Screenshot comparison
test_recorder.py - Automated test documentation
app_state_capture.py - Debugging snapshots
sim_health_check.sh - Environment verification

Advanced Testing & Permissions

clipboard.py - Clipboard management
status_bar.py - Status bar control
push_notification.py - Push notifications
privacy_manager.py - Permission management

Device Lifecycle

simctl_boot.py - Boot simulator
simctl_shutdown.py - Shutdown simulator
simctl_create.py - Create simulator
simctl_delete.py - Delete simulator
simctl_erase.py - Factory reset

See SKILL.md for complete reference.

How It Works with Claude Code

Claude Code automatically detects when to use this skill based on your request. You don't need to manually invoke it.

Example conversation:

You: "Set up my iOS app for testing"
Claude: [Uses simctl_boot.py and app_launcher.py automatically]

You: "Tap the login button"
Claude: [Uses navigator.py to find and tap]

You: "Check if the form is accessible"
Claude: [Uses accessibility_audit.py]

You can also run scripts manually when needed.

Usage Examples

Example 1: Login Flow

# Launch app
python scripts/app_launcher.py --launch com.example.app

# Map screen to find fields
python scripts/screen_mapper.py

# Enter credentials
python scripts/navigator.py --find-type TextField --index 0 --enter-text "[email protected]"
python scripts/navigator.py --find-type SecureTextField --enter-text "password"

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

# Verify accessibility
python scripts/accessibility_audit.py

Example 2: Test Documentation

# Record test execution
python scripts/test_recorder.py --test-name "Login Flow" --output test-reports/

# Generates:
# - Screenshots per step
# - Accessibility trees
# - Markdown report with timing

Example 3: Visual Testing

# Capture baseline
python scripts/app_state_capture.py --output baseline/

# Make changes...

# Compare
python scripts/visual_diff.py baseline/screenshot.png current/screenshot.png

Example 4: Permission Testing

# Grant permissions
python scripts/privacy_manager.py --bundle-id com.example.app --grant camera,location

# Test app behavior with permissions...

# Revoke permissions
python scripts/privacy_manager.py --bundle-id com.example.app --revoke camera,location

Example 5: Device Lifecycle in CI/CD

# Create test device
DEVICE_ID=$(python scripts/simctl_create.py --device "iPhone 16 Pro" --json | jq -r '.new_udid')

# Run tests
python scripts/build_and_test.py --project MyApp.xcodeproj

# Clean up
python scripts/simctl_delete.py --udid $DEVICE_ID --yes

Design Principles

Semantic Navigation: Find elements by meaning (text, type, ID) not pixel coordinates. Survives UI changes and works across device sizes.

Token Efficiency: Default output is 3-5 lines. Use --verbose for details or --json for machine parsing. 96% reduction vs raw tools.

Accessibility-First: Built on iOS accessibility APIs for reliability. Better for users with accessibility needs and more robust for automation.

Zero Configuration: Works immediately on any macOS with Xcode. No complex setup, no configuration files.

Structured Data: Scripts output JSON or formatted text, not raw logs. Easy to parse, integrate, and understand.

Auto-Learning: Build system learns your device preference and remembers it for next time.

Requirements

System:

macOS 12 or later
Xcode Command Line Tools
Python 3

Optional:

IDB (for interactive features)
Pillow (for visual_diff.py: pip3 install pillow)

Documentation

SKILL.md - Complete script reference and table of contents
CLAUDE.md - Architecture and developer guide
references/ - Deep documentation on specific topics
examples/ - Complete automation workflows

Output Efficiency

All scripts minimize output by default:

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

This efficiency keeps AI agent conversations focused and cost-effective.

Evaluation

This skill is tested using Claude Code evals — automated benchmarks that compare agent performance with and without the skill installed.

Results (Iteration 1)

Condition	Pass Rate
With skill	100% (3/3)
Without skill	46% (≈1.4/3)

What's Tested

Three eval scenarios cover the skill's core capabilities:

Environment & Discovery — Health check, list simulators, identify booted device
Build & Navigate — Build an app, launch it, map the screen, tap a button
Test & Capture — Accessibility audit, app state snapshot, status bar override

Each eval checks that the agent uses skill scripts (not raw xcrun simctl), follows progressive disclosure, and completes all requested steps.

Running Evals

# From repo root
claude evals run evals/evals.json --skill ios-simulator-skill

Eval definitions live in evals/evals.json.

Troubleshooting

Environment Issues

# Run health check
bash ~/.claude/skills/ios-simulator-skill/scripts/sim_health_check.sh

# Checks: macOS, Xcode, simctl, IDB, Python, simulators, packages

Script Help

# All scripts support --help
python scripts/navigator.py --help
python scripts/accessibility_audit.py --help

Not Finding Elements

# Use verbose mode to see all elements
python scripts/screen_mapper.py --verbose

# Check for exact text match
python scripts/navigator.py --find-text "Exact Button Text" --tap

Contributing

[!WARNING]
I appreciate contributions, but please note that this repo and my other public repos are far down in the priority queue of what I'm working on, so I'll be slow to review anything. Your best bet is really just to fork the repo and customise it to your own needs.

Contributions should:

Maintain token efficiency (minimal default output)
Follow accessibility-first design
Support --help documentation
Support --json for CI/CD
Pass Black formatter and Ruff linter
Include type hints
Update SKILL.md

License

MIT License - Allows commercial use and distribution.

Support

Issues: Create GitHub issue with reproduction steps
Documentation: See SKILL.md and references/
Examples: Check examples/ directory
Skills Docs: https://docs.claude.com/en/docs/claude-code/skills

Built for AI agents. Optimized for developers.