ios-simulator-skill
Manage iOS simulators and automate app builds, testing, and accessibility checks via CLI scripts.
Install
mkdir -p .claude/skills/ios-simulator-skill && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/211" && unzip -o skill.zip -d .claude/skills/ios-simulator-skill && rm skill.zipInstalls to .claude/skills/ios-simulator-skill
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
29 production-ready scripts for iOS app testing, building, and automation. Provides semantic UI navigation, build automation, accessibility testing, and simulator lifecycle management. Optimized for AI agents with minimal token output.Key capabilities
- →Automate iOS app builds and testing
- →Navigate UI using accessibility trees
- →Manage simulator state and appearance
- →Perform accessibility audits
- →Capture app state and logs for debugging
How it works
The skill uses accessibility-driven navigation and structured data to interact with iOS simulators, bypassing the need for image-based analysis.
Inputs & outputs
When to use ios-simulator-skill
- →Automate iOS app testing
- →Manage iOS simulator lifecycle
- →Run accessibility audits on iOS
- →Build iOS app from terminal
About this skill
iOS Simulator Skill
Build, test, and automate iOS applications using accessibility-driven navigation and structured data instead of pixel coordinates.
Quick Start
# 1. Check environment
bash scripts/sim_health_check.sh
# 2. Launch app
python3 scripts/app_launcher.py --launch com.example.app
# 3. Map screen to see elements
python3 scripts/screen_mapper.py
# 4. Tap button
python3 scripts/navigator.py --find-text "Login" --tap
# 5. Enter text
python3 scripts/navigator.py --find-type TextField --enter-text "[email protected]"
Paths: scripts/ is relative to the directory containing this SKILL.md, not the user's project.
Examples write scripts/... for brevity; run them by absolute path from the user's project
(e.g. python3 <skill-dir>/scripts/navigator.py ...) so relative Xcode project paths still resolve.
All scripts support --help for detailed options; most support --json for machine-readable output.
Navigation Strategy
Always prefer the accessibility tree over screenshots for navigation. The accessibility tree gives you element types, labels, frames, and tap targets — structured data that's cheaper and more reliable than image analysis.
Use this priority:
screen_mapper.py→ structured element list (5-7 lines, ~10 tokens)navigator.py --find-text/--find-type/--find-id→ semantic interaction- Screenshots → only for visual verification, bug reports, or visual diff
Screenshots cost 1,600–6,300 tokens depending on size. The accessibility tree costs 10–50 tokens in default mode.
31 Production Scripts
Build & Development (2 scripts)
-
build_and_test.py - Build Xcode projects, run tests, parse results with progressive disclosure
- Build with live result streaming
- Parse errors and warnings from xcresult bundles
- Retrieve detailed build logs on demand
--runbuilds, installs and launches the app in one call:Launched: <bundle> on <device> (pid N)- Tests that never started (parallel clone failed to boot) report
Tests: NOT RUN, not FAIL; retry with--no-parallel - Options:
--project,--scheme,--clean,--test,--run,--no-parallel,--verbose,--json
-
log_monitor.py - Real-time log monitoring with intelligent filtering
- Stream logs or capture by duration
- Filter by severity (error/warning/info/debug)
- Deduplicate repeated messages
- Options:
--app,--severity,--follow,--duration,--output,--json
Device State (4 scripts)
-
appearance.py - Control simulator appearance: dark mode, Dynamic Type size, contrast, and locale/region
- Toggle light/dark theme via
xcrun simctl ui - Set Dynamic Type size with friendly aliases (XS through AX5)
--contrast high|normaltoggles Increase Contrast and reads it back to confirm;--resetalso restores normal contrast- Write locale and region defaults; optional app restart via
--bundle-id - RTL flagged automatically for ar/he/fa/ur/yi locales
- Options:
--theme,--text-size,--contrast,--locale,--region,--reset,--bundle-id,--udid,--json,--verbose
- Toggle light/dark theme via
-
location.py - Simulate GPS coordinates, named city presets, and GPX scenario playback
- Fix a coordinate with
--lat/--lngor pick a city with--city - Play a built-in scenario (City Run, Freeway Drive, etc.) via
--gpx <scenario> - Animate multi-waypoint paths with configurable speed via
--waypointsand--speed - Clear simulated location with
--clear; list available scenarios with--list-scenarios - Options:
--lat,--lng,--city,--gpx,--waypoints,--speed,--clear,--list-scenarios,--udid,--json,--verbose
- Fix a coordinate with
-
media.py - Seed or empty the photo library for photo-picker tests
--add a.jpg b.pngviaxcrun simctl addmedia--clear --yesempties the library viaidb photos clear(idb 1.7+);--clear --yes --addleaves exactly the added files- Without
--yes,--clearrefuses if the library has photos (they can't be recovered): ask the user first - Fails fast on a missing file
- Options:
--add,--clear,--yes,--udid,--json
-
duo.py - Experimental iPhone Duo hinge and interface orientation controls
- Requires an explicit booted Duo
--udid; no automatic device selection - Read observed angle, active cover/inner display ID and rotation (default or
--state) --pose closed|partial|open(0°/90°/180°),--angle 0..180, or--orientation portrait|landscape|portrait-upside-down|landscape-flipped- Changes verify observed readback; hinge endpoints also verify cover/inner display activation
- Bundled Objective-C helper compiles and signs with the selected Xcode on first use; no extra CLI
- Private APIs are experimental; inner-display coordinate touch routing is unverified
- Options:
--udid,--state,--pose,--angle,--orientation,--json,--verbose
- Requires an explicit booted Duo
Navigation & Interaction (5 scripts)
-
screen_mapper.py - Analyze current screen and list interactive elements
- Element type breakdown
- Interactive button list
- Text field status
- If labelled elements cover under 10% of the screen, adds a
Coverage:line suggesting--deep --deepreads through idb's axbridge backend (idb 1.7+): also sees Safari/WKWebView content and in-app alerts the default read misses, plus many unlabelled container views. It turns on the device's accessibility automation mode (not restored afterwards). Web-content frames are relative to the web view, so use--deepto find elements, not to take tap coordinates- Options:
--verbose,--hints,--deep,--json
-
navigator.py - Find and interact with elements semantically
- Find by text (fuzzy, or exact with
--find-exact); interactive leaf elements rank above containers sharing the label - Find by element type
- Find by accessibility ID
- Enter text or tap elements
--tapon a Button/Link/Switch/CheckBox/Tab with a unique accessibility ID or label uses an accessibility press (idb 1.7+), so overlays like a floating search bar can't intercept it; output says(accessibility press). Otherwise it taps the frame center--set-value TEXTreplaces a field's value without the keyboard (any characters, idb 1.7+). Focus doesn't move, so use--enter-textwhen a Return key must submit afterwards The value is read back before success is claimed (not for secure fields); a mismatch exits 1--tap --expect VALUEtaps only if the element's value is VALUE (toggles:1on,0off) and exits 1 without tapping otherwise, so "turn X off" is safe to repeat- iOS 27 reports toggles as
CheckBox. Only a press flips them (no HID touch does, even on the switch itself); if neither ID nor label is unique, the output warns to check the value - A frozen app stalls every read and tap until its main thread responds
- Failures include idb's stderr (e.g. a dead companion)
- Options:
--find-text,--find-exact,--find-type,--find-id,--index,--tap,--expect,--tap-at,--enter-text,--set-value,--list
- Find by text (fuzzy, or exact with
-
gesture.py - Perform swipes, scrolls, pinches, and complex gestures
- Directional swipes (up/down/left/right) -
--swipeis the direction the finger moves - Multi-swipe scrolling -
--scrollis the direction the content moves (downreveals content below) - Pinch zoom via
idb ui pinch(--pinch outzooms in;--scalesets an explicit factor) - Long press via
idb ui tap --duration - Pull to refresh
--double-tap X,Y [--tap-count N]- multi-tap at a point (idb 1.7+)--drag SOURCE DEST- press-hold, drag, release; each end isx,yor an accessibility label, e.g.--drag "Row 1" "Row 4"(idb 1.7+)--rotate portrait|portrait-upside-down|landscape-left|landscape-right- physical device rotation (idb 1.7+)--shake- shake the device, for debug menus and undo (idb 1.7+)- Options:
--swipe,--swipe-from/--swipe-to,--scroll,--scroll-amount,--pinch,--scale,--long-press,--duration,--refresh,--double-tap,--tap-count,--drag,--rotate,--shake
- Directional swipes (up/down/left/right) -
-
keyboard.py - Text input and hardware button control
- Type text (fast or slow; ASCII only)
- Special keys (return, delete, tab, space, escape, arrows), single letters, or raw HID codes
- Key sequences (
--key-sequence h,i,return) - Key chords:
--key z --command --shift(redo);--shift/--control/--optionneed idb 1.7+ - Clear the focused field (Cmd+A, delete)
- Hardware buttons: home, lock/power, side, siri, apple-pay, volume-up/down (volume needs idb 1.6.3+)
- Options:
--type,--slow,--key,--shift,--control,--option,--command,--count,--key-sequence,--button,--clear,--dismiss
- app_launcher.py - App lifecycle management
- Launch apps by bundle ID
- Terminate apps
- Install/uninstall from .app bundles (
--uninstallneeds--yes: the app's data is deleted) - Deep link navigation
- List installed apps
- Check app state
- Pass launch arguments (
--args) and environment variables (--env KEY=VALUE, injected asSIMCTL_CHILD_*) to the app on launch/restart - Options:
--launch,--terminate,--restart,--install,--uninstall,--yes,--open-url,--list,--state,--args,--env,--wait-for-debugger
Testing & Analysis (9 scripts)
-
accessibility_audit.py - Check WCAG compliance on current screen
- Critical issues (missing labels, empty buttons, no alt text)
- Warnings (missing hints, small touch targets)
- Info (missing IDs, deep nesting)
- Options:
--verbose,--output,--json
-
visual_diff.py - Compare two screenshots for visual changes
- Pixel-by-pixel comparison
- Threshold-based pass/fail
- Generate diff images
- Options:
--threshold,--output, `
Content truncated.
When not to use it
- →Navigation relying on pixel coordinates
- →Tasks outside the scope of iOS simulator automation
Prerequisites
Limitations
- →Requires Xcode Command Line Tools
- →Accessibility tree is the primary navigation source
How it compares
It uses semantic navigation based on accessibility APIs, which is more reliable and token-efficient than screenshot-based analysis.
Compared to similar skills
ios-simulator-skill side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| ios-simulator-skill (this skill) | 27 | 5mo | Review | Advanced |
| build-iphone-apps | 14 | 12mo | Review | Advanced |
| xcodebuildmcp | 24 | 7mo | No flags | Advanced |
| swiftui-expert-skill | 13 | 7mo | No flags | Intermediate |
Try saying
Example prompts that trigger this skill in your AI assistant.
You might also like
build-iphone-apps
glittercowboy
Build professional native iPhone apps in Swift with SwiftUI and UIKit. Full lifecycle - build, debug, test, optimize, ship. CLI-only, no Xcode. Targets iOS 26 with iOS 18 compatibility.
xcodebuildmcp
cameroncooke
Official skill for XcodeBuildMCP. Use when doing iOS/macOS/watchOS/tvOS/visionOS work (build, test, run, debug, log, UI automation).
swiftui-expert-skill
sickn33
Write, review, or improve SwiftUI code following best practices for state management, view composition, performance, modern APIs, Swift concurrency, and iOS 26+ Liquid Glass adoption. Use when building new SwiftUI features, refactoring existing views, reviewing code quality, or adopting modern SwiftUI patterns.
ios-testing-validation
AriDevari
Validate iOS changes in Naviari_IOS. Use when: running narrow xcodebuild checks, planning XCTest or manual verification, validating visually sensitive SwiftUI work, checking reusable-view regressions, or recording slice-level evidence after iOS edits.
mobile-ios-design
wshobson
Master iOS Human Interface Guidelines and SwiftUI patterns for building native iOS apps. Use when designing iOS interfaces, implementing SwiftUI views, or ensuring apps follow Apple's design principles.
axiom-ios-accessibility
CharlesWiltgen
Use when fixing or auditing ANY accessibility issue - VoiceOver, Dynamic Type, color contrast, touch targets, WCAG compliance, App Store accessibility review.