name	iosctl
description	Use this skill when building, launching, testing, inspecting, or proving native iOS Simulator apps with the agent-first `iosctl` CLI. Triggers include iOS Simulator proof runs, Xcode build/test loops, screenshot receipts, semantic UI tapping, accessibility-tree inspection, and replacing brittle MCP-only iOS workflows with CLI-first workflows.

iosctl

Use iosctl for native iOS Simulator build/run/proof loops.

Default stance:

Prefer the iosctl CLI over MCP-only iOS helper servers.
Prefer --json for agent work.
Treat MCP as optional transport, not source of truth.
Prefer first-party Apple tools through iosctl before third-party abstractions.
Prefer accessibility trees and identifiers before screenshot vision.
Do not claim the app works unless there is a receipt, screenshot path, or result artifact.
Do not pass secrets as command-line arguments.

skills.sh Package Shape

This skill is published from the nested path skills/iosctl/SKILL.md. Do not depend on a root SKILL.md; Vercel's skills CLI lets a shallower SKILL.md shadow nested skills.

Install the skill with:

npx -y skills add -g danielgwilson/iosctl --skill iosctl

Use it without installing with:

npx -y skills use danielgwilson/iosctl@iosctl

Command Resolution

Use iosctl when it is already available on PATH. If it is missing and Node.js is available, prefer the published package for one-off agent runs:

npx -y iosctl@latest doctor --json

Only ask the user to install globally when repeated local use is expected:

npm i -g iosctl

Sanity Checks

Start with:

iosctl doctor --json
iosctl devices --json

If iosctl is missing from PATH, use the published package for the same checks:

npx -y iosctl@latest doctor --json
npx -y iosctl@latest devices --json

For local development, use the repository checkout:

npm install
npm run build
npm link

Proof Loop

Use:

iosctl proof-run \
  --project App.xcodeproj \
  --scheme App \
  --bundle com.example.app \
  --device "iPhone 17 Pro" \
  --json

Expected artifacts:

.iosctl/runs/<run-id>/receipt.json
.iosctl/runs/<run-id>/summary.md
build log or result path
app log path
screenshot path
optional UI tree path

If proof-run fails, inspect the returned error.artifact first. It should point at either receipt.json or the failing command log.

Fallback manually in this order only when the CLI cannot complete:

iosctl doctor --json
iosctl devices --json
direct xcodebuild build with explicit DerivedData and result paths
direct xcrun simctl boot/install/launch
direct xcrun simctl io ... screenshot
store commands and artifacts in a run directory

Semantic UI

Use semantic UI commands for app navigation:

iosctl ui snapshot --device <UDID> --json
iosctl ui find --text "Book appointment" --json
iosctl ui tap --text "Book appointment" --json
iosctl ui type --text-field "Ask anything..." --value "Can you help with scheduling?" --json
iosctl ui swipe --direction up --json

ui snapshot stores the full raw accessibility tree and normalized element list under .iosctl/ui/<snapshot-id>/. Use those artifacts when stdout is capped.

If the CLI cannot read the accessibility tree, use direct idb ui describe-all --nested --json before screenshot vision.

Contract Essentials

With --json, stdout must be exactly one JSON object.
Progress belongs on stderr.
Exit codes:
- 0 success
- 1 operation failed
- 2 invalid input, missing capability, or user action required
- 3 safety refusal
Common error codes:
- MISSING_TOOL
- COMMAND_FAILED
- INVALID_INPUT
- SAFETY_REFUSAL
- NOT_IMPLEMENTED
- XCODE_UNAVAILABLE
- SIMULATOR_UNAVAILABLE
- DESTINATION_UNAVAILABLE
- APP_NOT_FOUND
- BUNDLE_LAUNCH_FAILED
- UI_TREE_UNAVAILABLE
- UI_ELEMENT_NOT_FOUND
- TIMEOUT

Safety

Never commit .iosctl/ run artifacts unless explicitly sanitized.
Never paste full app logs, screenshots, or UI trees into public docs without review.
Never pass API keys or auth tokens as CLI arguments.
Treat screenshots and app logs as local private artifacts by default.
Use synthetic examples in docs and tests.

name	iosctl
description	Use this skill when building, launching, testing, inspecting, or proving native iOS Simulator apps with the agent-first `iosctl` CLI. Triggers include iOS Simulator proof runs, Xcode build/test loops, screenshot receipts, semantic UI tapping, accessibility-tree inspection, and replacing brittle MCP-only iOS workflows with CLI-first workflows.