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 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 bala
Add this skill
npx mdskills install conorluddy/ios-simulator-skillComprehensive iOS simulator automation with semantic navigation and excellent token efficiency design
1# iOS Simulator Skill for Claude Code23Production-ready automation for iOS app testing and building. 21 scripts optimized for both human developers and AI agents.45This is basically a Skill version of my XCode MCP: [https://github.com/conorluddy/xc-mcp](https://github.com/conorluddy/xc-mcp)678> [!WARNING]9> 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.101112MCPs 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...1314Updated: 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](https://github.com/conorluddy/xclaude-plugin)1516## What It Does1718Instead of pixel-based navigation that breaks when UI changes:1920```bash21# Fragile - breaks if UI changes22idb ui tap 320 4002324# Robust - finds by meaning25python scripts/navigator.py --find-text "Login" --tap26```2728Uses semantic navigation on accessibility APIs to interact with elements by their meaning, not coordinates. Works across different screen sizes and survives UI redesigns.2930## Features3132- **21 production scripts** for building, testing, and automation33- **Semantic navigation** - find elements by text, type, or ID34- **Token optimized** - 96% reduction vs raw tools (3-5 lines default)35- **Zero configuration** - works immediately on macOS with Xcode36- **Structured output** - JSON and formatted text, easy to parse37- **Auto-UDID detection** - no need to specify device each time38- **Batch operations** - boot, delete, erase multiple simulators at once39- **Comprehensive testing** - WCAG compliance, visual diffs, accessibility audits40- **CI/CD ready** - JSON output, exit codes, automated device lifecycle4142## Installation4344### As Claude Code Skill4546```bash47# Personal installation48git clone https://github.com/conorluddy/ios-simulator-skill.git ~/.claude/skills/ios-simulator-skill4950# Project installation51git clone https://github.com/conorluddy/ios-simulator-skill.git .claude/skills/ios-simulator-skill52```5354Restart Claude Code. The skill loads automatically.5556### From Release5758```bash59# Download latest release60curl -L https://github.com/conorluddy/ios-simulator-skill/releases/download/vX.X.X/ios-simulator-skill-vX.X.X.zip -o skill.zip6162# Extract63unzip skill.zip -d ~/.claude/skills/ios-simulator-skill64```6566## Prerequisites6768- macOS 12+69- Xcode Command Line Tools (`xcode-select --install`)70- Python 371- IDB (optional, for interactive features: `brew tap facebook/fb && brew install idb-companion`)7273## Quick Start7475```bash76# 1. Check environment77bash ~/.claude/skills/ios-simulator-skill/scripts/sim_health_check.sh7879# 2. Launch your app80python ~/.claude/skills/ios-simulator-skill/scripts/app_launcher.py --launch com.example.app8182# 3. See what's on screen83python ~/.claude/skills/ios-simulator-skill/scripts/screen_mapper.py84# Output:85# Screen: LoginViewController (45 elements, 7 interactive)86# Buttons: "Login", "Cancel", "Forgot Password"87# TextFields: 2 (0 filled)8889# 4. Tap login button90python ~/.claude/skills/ios-simulator-skill/scripts/navigator.py --find-text "Login" --tap9192# 5. Enter text93python ~/.claude/skills/ios-simulator-skill/scripts/navigator.py --find-type TextField --enter-text "user@test.com"9495# 6. Check accessibility96python ~/.claude/skills/ios-simulator-skill/scripts/accessibility_audit.py97```9899## 21 Scripts Organized by Category100101### Build & Development102- **build_and_test.py** - Build projects, run tests, parse results103- **log_monitor.py** - Real-time log monitoring104105### Navigation & Interaction106- **screen_mapper.py** - Analyze current screen107- **navigator.py** - Find and interact with elements108- **gesture.py** - Swipes, scrolls, pinches109- **keyboard.py** - Text input and hardware buttons110- **app_launcher.py** - App lifecycle control111112### Testing & Analysis113- **accessibility_audit.py** - WCAG compliance checking114- **visual_diff.py** - Screenshot comparison115- **test_recorder.py** - Automated test documentation116- **app_state_capture.py** - Debugging snapshots117- **sim_health_check.sh** - Environment verification118119### Advanced Testing & Permissions120- **clipboard.py** - Clipboard management121- **status_bar.py** - Status bar control122- **push_notification.py** - Push notifications123- **privacy_manager.py** - Permission management124125### Device Lifecycle126- **simctl_boot.py** - Boot simulator127- **simctl_shutdown.py** - Shutdown simulator128- **simctl_create.py** - Create simulator129- **simctl_delete.py** - Delete simulator130- **simctl_erase.py** - Factory reset131132See **SKILL.md** for complete reference.133134## How It Works with Claude Code135136Claude Code automatically detects when to use this skill based on your request. You don't need to manually invoke it.137138**Example conversation:**139140```141You: "Set up my iOS app for testing"142Claude: [Uses simctl_boot.py and app_launcher.py automatically]143144You: "Tap the login button"145Claude: [Uses navigator.py to find and tap]146147You: "Check if the form is accessible"148Claude: [Uses accessibility_audit.py]149```150151You can also run scripts manually when needed.152153## Usage Examples154155### Example 1: Login Flow156157```bash158# Launch app159python scripts/app_launcher.py --launch com.example.app160161# Map screen to find fields162python scripts/screen_mapper.py163164# Enter credentials165python scripts/navigator.py --find-type TextField --index 0 --enter-text "user@test.com"166python scripts/navigator.py --find-type SecureTextField --enter-text "password"167168# Tap login169python scripts/navigator.py --find-text "Login" --tap170171# Verify accessibility172python scripts/accessibility_audit.py173```174175### Example 2: Test Documentation176177```bash178# Record test execution179python scripts/test_recorder.py --test-name "Login Flow" --output test-reports/180181# Generates:182# - Screenshots per step183# - Accessibility trees184# - Markdown report with timing185```186187### Example 3: Visual Testing188189```bash190# Capture baseline191python scripts/app_state_capture.py --output baseline/192193# Make changes...194195# Compare196python scripts/visual_diff.py baseline/screenshot.png current/screenshot.png197```198199### Example 4: Permission Testing200201```bash202# Grant permissions203python scripts/privacy_manager.py --bundle-id com.example.app --grant camera,location204205# Test app behavior with permissions...206207# Revoke permissions208python scripts/privacy_manager.py --bundle-id com.example.app --revoke camera,location209```210211### Example 5: Device Lifecycle in CI/CD212213```bash214# Create test device215DEVICE_ID=$(python scripts/simctl_create.py --device "iPhone 16 Pro" --json | jq -r '.new_udid')216217# Run tests218python scripts/build_and_test.py --project MyApp.xcodeproj219220# Clean up221python scripts/simctl_delete.py --udid $DEVICE_ID --yes222```223224## Design Principles225226**Semantic Navigation**: Find elements by meaning (text, type, ID) not pixel coordinates. Survives UI changes and works across device sizes.227228**Token Efficiency**: Default output is 3-5 lines. Use `--verbose` for details or `--json` for machine parsing. 96% reduction vs raw tools.229230**Accessibility-First**: Built on iOS accessibility APIs for reliability. Better for users with accessibility needs and more robust for automation.231232**Zero Configuration**: Works immediately on any macOS with Xcode. No complex setup, no configuration files.233234**Structured Data**: Scripts output JSON or formatted text, not raw logs. Easy to parse, integrate, and understand.235236**Auto-Learning**: Build system learns your device preference and remembers it for next time.237238## Requirements239240**System:**241- macOS 12 or later242- Xcode Command Line Tools243- Python 3244245**Optional:**246- IDB (for interactive features)247- Pillow (for visual_diff.py: `pip3 install pillow`)248249## Documentation250251- **SKILL.md** - Complete script reference and table of contents252- **CLAUDE.md** - Architecture and developer guide253- **references/** - Deep documentation on specific topics254- **examples/** - Complete automation workflows255256## Output Efficiency257258All scripts minimize output by default:259260| Task | Raw Tools | This Skill | Savings |261|------|-----------|-----------|---------|262| Screen analysis | 200+ lines | 5 lines | 97.5% |263| Find & tap button | 100+ lines | 1 line | 99% |264| Enter text | 50+ lines | 1 line | 98% |265| Login flow | 400+ lines | 15 lines | 96% |266267This efficiency keeps AI agent conversations focused and cost-effective.268269## Troubleshooting270271### Environment Issues272273```bash274# Run health check275bash ~/.claude/skills/ios-simulator-skill/scripts/sim_health_check.sh276277# Checks: macOS, Xcode, simctl, IDB, Python, simulators, packages278```279280### Script Help281282```bash283# All scripts support --help284python scripts/navigator.py --help285python scripts/accessibility_audit.py --help286```287288### Not Finding Elements289290```bash291# Use verbose mode to see all elements292python scripts/screen_mapper.py --verbose293294# Check for exact text match295python scripts/navigator.py --find-text "Exact Button Text" --tap296```297298## Contributing299300> [!WARNING]301> 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.302303Contributions should:304- Maintain token efficiency (minimal default output)305- Follow accessibility-first design306- Support `--help` documentation307- Support `--json` for CI/CD308- Pass Black formatter and Ruff linter309- Include type hints310- Update SKILL.md311312## License313314MIT License - Allows commercial use and distribution.315316## Support317318- **Issues**: Create GitHub issue with reproduction steps319- **Documentation**: See SKILL.md and references/320- **Examples**: Check examples/ directory321- **Skills Docs**: https://docs.claude.com/en/docs/claude-code/skills322323---324325**Built for AI agents. Optimized for developers.**326
Full transparency — inspect the skill content before installing.