IO

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

Installs 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.
235 charsno explicit “when” trigger
Advanced

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

You give it
iOS app bundle ID or simulator command
You get back
Test results, UI element lists, or simulator state changes

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:

  1. screen_mapper.py → structured element list (5-7 lines, ~10 tokens)
  2. navigator.py --find-text/--find-type/--find-id → semantic interaction
  3. 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)

  1. 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
    • --run builds, 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
  2. 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)

  1. 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|normal toggles Increase Contrast and reads it back to confirm; --reset also 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
  2. location.py - Simulate GPS coordinates, named city presets, and GPX scenario playback

    • Fix a coordinate with --lat/--lng or 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 --waypoints and --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
  3. media.py - Seed or empty the photo library for photo-picker tests

    • --add a.jpg b.png via xcrun simctl addmedia
    • --clear --yes empties the library via idb photos clear (idb 1.7+); --clear --yes --add leaves exactly the added files
    • Without --yes, --clear refuses 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
  4. 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

Navigation & Interaction (5 scripts)

  1. 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
    • --deep reads 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 --deep to find elements, not to take tap coordinates
    • Options: --verbose, --hints, --deep, --json
  2. 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
    • --tap on 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 TEXT replaces a field's value without the keyboard (any characters, idb 1.7+). Focus doesn't move, so use --enter-text when 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 VALUE taps only if the element's value is VALUE (toggles: 1 on, 0 off) 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
  3. gesture.py - Perform swipes, scrolls, pinches, and complex gestures

    • Directional swipes (up/down/left/right) - --swipe is the direction the finger moves
    • Multi-swipe scrolling - --scroll is the direction the content moves (down reveals content below)
    • Pinch zoom via idb ui pinch (--pinch out zooms in; --scale sets 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 is x,y or 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
  4. 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/--option need 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
  1. app_launcher.py - App lifecycle management
  • Launch apps by bundle ID
  • Terminate apps
  • Install/uninstall from .app bundles (--uninstall needs --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 as SIMCTL_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)

  1. 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
  2. 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

macOS 12+Xcode Command Line ToolsPython 3

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.

SkillInstallsUpdatedSafetyDifficulty
ios-simulator-skill (this skill)275moReviewAdvanced
build-iphone-apps1412moReviewAdvanced
xcodebuildmcp247moNo flagsAdvanced
swiftui-expert-skill137moNo flagsIntermediate

Try saying

Example prompts that trigger this skill in your AI assistant.

Search skills

Search the agent skills registry