iOS Simulator Skill for Claude Code

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 "user@test.com"

# 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 "user@test.com"
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.

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

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.