iOS Development Skill

You are an expert iOS developer with full autonomous control of the Xcode build pipeline, iOS Simulator, screenshot capture, Maestro UI automation, and debug log analysis. Follow these procedures exactly.

1. Pre-flight Checks

On every invocation, run the preflight script first. Locate this skill's scripts directory:

SKILL_SCRIPTS=$(find -L .claude/skills .agents/skills -path "*/ios-dev/scripts" -type d 2>/dev/null | head -1)
bash "$SKILL_SCRIPTS/preflight.sh"

If it reports BLOCKED, fix the issues before proceeding. If Maestro is missing, the script auto-installs it. Always ensure ~/.maestro/bin is in PATH:

export PATH="$HOME/.maestro/bin:$PATH"

2. Project Discovery

Auto-detect the Xcode project:

# Prefer workspace (supports CocoaPods)
find . -maxdepth 3 -name "*.xcworkspace" -not -path "*/DerivedData/*" -not -path "*/.build/*" -not -path "*/Pods/*" 2>/dev/null | head -1

# Fall back to project file
find . -maxdepth 3 -name "*.xcodeproj" -not -path "*/DerivedData/*" -not -path "*/Pods/*" 2>/dev/null | head -1

If found, discover schemes:

xcodebuild -list -project <path> 2>/dev/null
# or
xcodebuild -list -workspace <path> 2>/dev/null

If no project exists, create one as needed for the task.

3. Simulator Management

Select a simulator

# Check if one is already booted -- use it
xcrun simctl list devices booted 2>/dev/null

# If none booted, list available iPhone simulators and pick the newest iPhone Pro:
xcrun simctl list devices available 2>/dev/null | grep "iPhone"

Selection priority: booted device > newest iPhone Pro > newest iPhone > any available.

Boot and open

xcrun simctl boot <UDID>
open -a Simulator
sleep 3  # Wait for simulator to fully boot

4. Build

xcodebuild -project <path.xcodeproj> -scheme <scheme> -sdk iphonesimulator -destination 'platform=iOS Simulator,id=<UDID>' -configuration Debug -derivedDataPath .claude-ios/build CODE_SIGNING_ALLOWED=NO build 2>&1

Note: The xcodebuild command must be on a single line when executed via Bash tool. Backslash line continuations may cause Unknown build action '' errors in agent environments.

For workspaces, use -workspace instead of -project.

On build failure: Read the error output, fix the source code, rebuild. Retry up to 3 times.

The built .app bundle will be at:

.claude-ios/build/Build/Products/Debug-iphonesimulator/<AppName>.app

5. Install & Launch

xcrun simctl install booted .claude-ios/build/Build/Products/Debug-iphonesimulator/<AppName>.app
xcrun simctl launch booted <bundle.identifier>
sleep 3  # Wait for app to load

Find the bundle identifier:

defaults read .claude-ios/build/Build/Products/Debug-iphonesimulator/<AppName>.app/Info.plist CFBundleIdentifier

6. Screenshots (CRITICAL)

ALWAYS use the screenshot script. Never take a raw screenshot without resizing.

SKILL_SCRIPTS=$(find -L .claude/skills .agents/skills -path "*/ios-dev/scripts" -type d 2>/dev/null | head -1)
bash "$SKILL_SCRIPTS/screenshot.sh" <descriptive_name>

This captures the simulator screen, resizes to max 1568px (Claude API limit), and saves to .claude-ios/screenshots/<name>.png.

After every screenshot, ALWAYS use the Read tool to view it:

Read tool -> .claude-ios/screenshots/<name>.png

This is how you see the app. Analyze what is on screen and decide next actions.

Screenshot naming convention

Use descriptive names: home_screen, login_form, after_submit, error_state, detail_view.

7. UI Navigation with Maestro

Quick single actions

Write a temporary Maestro flow file and run it:

# .claude-ios/flow.yaml
appId: <bundle.identifier>
---
- tapOn: "Button Text"
- inputText: "Hello"
- assertVisible: "Expected Result"
- takeScreenshot: .claude-ios/screenshots/after_action

export PATH="$HOME/.maestro/bin:$PATH"
MAESTRO_CLI_NO_ANALYTICS=1 maestro test .claude-ios/flow.yaml

After Maestro runs

Resize any screenshots Maestro took (it does NOT auto-resize):

sips --resampleHeightWidthMax 1568 .claude-ios/screenshots/<name>.png

Use the Read tool to view them.

Key Maestro commands

tapOn: "text" -- tap a button/label by its text
tapOn: { id: "accessibilityId" } -- tap by accessibility identifier
inputText: "text" -- type into focused field
assertVisible: "text" -- verify element exists
scroll / swipe -- navigate lists
waitForAnimationToEnd -- wait after transitions
See references/maestro-guide.md for the full command reference.

8. Video Recording

SKILL_SCRIPTS=$(find -L .claude/skills .agents/skills -path "*/ios-dev/scripts" -type d 2>/dev/null | head -1)

# Start recording
bash "$SKILL_SCRIPTS/record.sh" start <name>

# ... perform actions ...

# Stop recording
bash "$SKILL_SCRIPTS/record.sh" stop

Videos are saved to .claude-ios/videos/.

9. Debug Logs

View recent logs

xcrun simctl spawn booted log show --last 5m --predicate 'process == "<AppName>"' --style compact

Stream logs in real-time

xcrun simctl spawn booted log stream --predicate 'process == "<AppName>"' --level debug --timeout 10

Check for crash logs

xcrun simctl spawn booted log show --last 2m --predicate 'process == "<AppName>" AND messageType == 16' --style compact

10. The Autonomous Build-Run-Verify Loop

When asked to build, test, or fix an iOS app, follow this exact sequence:

Preflight -- Run preflight.sh, fix any blockers
Discover -- Find or create the Xcode project
Build -- xcodebuild for simulator
If build fails -- Read errors, fix code, rebuild (up to 3 retries)
Simulator -- Boot if needed, select best device
Install -- Install .app on simulator
Launch -- Start the app
Screenshot -- Take screenshot via screenshot.sh, view with Read tool
Verify -- Analyze the screenshot. Does the UI look correct?
If UI is wrong -- Diagnose from screenshot, fix code, rebuild from step 3
Navigate -- If needed, use Maestro to tap/type/swipe through the app
Screenshot again -- Capture and view each significant state
Debug -- If something is off, check logs for errors
Iterate -- Repeat until the app works correctly

11. Rules (Non-negotiable)

NEVER view a screenshot without resizing first -- always use screenshot.sh or sips --resampleHeightWidthMax 1568
ALWAYS use the Read tool to view screenshots after taking them -- this is how you see the app
NEVER ask the user to manually interact with the simulator -- do everything programmatically
ALWAYS store artifacts in .claude-ios/screenshots/ and .claude-ios/videos/
ALWAYS use CODE_SIGNING_ALLOWED=NO for simulator builds
ALWAYS use -derivedDataPath .claude-ios/build to keep build artifacts in the project
ALWAYS run preflight checks at the start of a session
For troubleshooting, see references/troubleshooting.md

ios-dev

Safety Notice

Copy this and send it to your AI assistant to learn