Agent skill

Xcode Build

by pzep1 in pzep1/xcode-build-skill

Build and run iOS/macOS apps using xcodebuild and xcrun simctl directly.

MITAuto-check: notesMobile

Install Xcode Build

skills CLI
$ npx skills add pzep1/xcode-build-skill --skill xcode-build -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install pzep1/xcode-build-skill xcode-build --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/pzep1/xcode-build-skill.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/xcode-build .claude/skills/xcode-build && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
xcode-build
GitHub stars
138
Token cost
~1.5k tokens
SKILL.md length
261 words
Files
3
Skills in repo
1
Repo updated
First seen
Licence
MIT

At a glance

Build and run iOS/macOS apps using xcodebuild and xcrun simctl directly.

  • Works in 5 steps: Discover Project Structure → Find Available Simulators → Build for Simulator → …
  • Building Xcode projects
  • SKILL.md covers When to Use This Skill, Quick Start, Detailed References and Common Patterns, plus 4 more sections
  • Calls xcrun, xcodebuild and jq

What it does

Xcode Build is an agent skill from pzep1/xcode-build-skill. Build and run iOS/macOS apps using xcodebuild and xcrun simctl directly. Use when building Xcode projects, running iOS simulators, managing devices, compiling Swift code, running UI tests, or automating iOS app interactions. Replaces XcodeBuildMCP with native CLI tools.

Its SKILL.md is about 1.5k tokens, which your agent loads only when the skill is triggered. The skill folder holds 2 other files (for example `CLI_REFERENCE.md` and `XCUITEST_GUIDE.md`).

It sits in Mobile, covering iOS development. It works with Xcode, iOS, macOS and Model Context Protocol. The licence is MIT.

When your agent uses it

  • Building Xcode projects
  • Running iOS simulators
  • Managing devices
  • Compiling Swift code

Example prompts

  • “/xcode-build”

Requirements

  • Pre-approved tools (allowed-tools): Bash, Read, Grep, Glob

Workflow steps

5 steps, taken from the step headings in SKILL.md.

  1. Discover Project Structure
  2. Find Available Simulators
  3. Build for Simulator
  4. Install and Launch
  5. Take Screenshot

What it can do on your machine

Read from SKILL.md and the folder at commit 9b5c313. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves these tools, so the agent can use them without asking each time:

    • Bash
    • Read
    • Grep
    • Glob

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • xcrun
    • xcodebuild
    • jq

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Xcode Build loads about 1.5k tokens when it runs. Until then it costs about 71 tokens; SKILL.md has 261 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~71
When it runs · the whole SKILL.md, loaded when a task matches
~1.5k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check: notes

The automated check noted patterns worth knowing about, such as sudo or a known installer.

  • NotePre-approves every shell command (allowed-tools: Bash)SKILL.md
    allowed-tools: Bash, Read, Grep, Glob

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from pzep1/xcode-build-skill at commit 9b5c313, republished under its MIT licence (© pzep1). 261 words, ~1,483 tokens.

Download SKILL.mdSave it as .claude/skills/xcode-build/SKILL.md (or your agent's skills folder). This skill also uses 2 other files; get the full folder from GitHub.
name
xcode-build
description
Build and run iOS/macOS apps using xcodebuild and xcrun simctl directly. Use when building Xcode projects, running iOS simulators, managing devices, compiling Swift code, running UI tests, or automating iOS app interactions. Replaces XcodeBuildMCP with native CLI tools.
allowed-tools
Bash, Read, Grep, Glob

Xcode Build Direct

Build and manage iOS/macOS projects using native Xcode CLI tools instead of MCP servers.

When to Use This Skill

Use this skill when:

  • Building iOS or macOS apps with Xcode
  • Running apps in iOS simulators
  • Managing simulator instances (boot, shutdown, list)
  • Taking screenshots of simulators
  • Capturing app logs
  • Running tests (unit or UI)
  • Automating UI interactions (tap, type, swipe)

Preference: Always use direct CLI commands (xcodebuild, xcrun simctl) instead of XcodeBuildMCP tools.

Quick Start

1. Discover Project Structure
bash
# List schemes in a workspace
xcodebuild -workspace /path/to/App.xcworkspace -list

# List schemes in a project
xcodebuild -project /path/to/App.xcodeproj -list

# Show build settings
xcodebuild -workspace /path/to/App.xcworkspace -scheme AppScheme -showBuildSettings
2. Find Available Simulators
bash
# List all simulators
xcrun simctl list devices

# List as JSON (better for parsing)
xcrun simctl list devices --json

# List only available simulators
xcrun simctl list devices available
3. Build for Simulator
bash
# Get simulator UUID first
UDID=$(xcrun simctl list devices --json | jq -r '.devices | .[].[] | select(.name=="iPhone 16 Pro") | .udid' | head -1)

# Build
xcodebuild \
  -workspace /path/to/App.xcworkspace \
  -scheme AppScheme \
  -destination "platform=iOS Simulator,id=$UDID" \
  -configuration Debug \
  -derivedDataPath /tmp/build \
  build
4. Install and Launch
bash
# Find the built .app
APP_PATH=$(find /tmp/build -name "*.app" -type d | head -1)

# Install on simulator
xcrun simctl install $UDID "$APP_PATH"

# Launch app
xcrun simctl launch $UDID com.your.bundleid
5. Take Screenshot
bash
xcrun simctl io $UDID screenshot /tmp/screenshot.png

Detailed References

For comprehensive command documentation, see:

  • CLI_REFERENCE.md - Full xcodebuild and xcrun simctl command reference
  • XCUITEST_GUIDE.md - UI automation via XCUITest (tap, type, gestures, element queries)

Common Patterns

Build + Run Workflow
bash
# 1. Boot simulator
xcrun simctl boot $UDID 2>/dev/null || true

# 2. Build
xcodebuild -workspace App.xcworkspace -scheme App \
  -destination "platform=iOS Simulator,id=$UDID" \
  -derivedDataPath /tmp/build build

# 3. Find and install app
APP=$(find /tmp/build -name "*.app" -type d | head -1)
xcrun simctl install $UDID "$APP"

# 4. Launch with console output
xcrun simctl launch --console $UDID com.bundle.id
Log Capture
bash
# Stream app logs (run in background)
/usr/bin/log stream \
  --predicate 'processImagePath CONTAINS[cd] "AppName"' \
  --style json &
LOG_PID=$!

# ... interact with app ...

# Stop logging
kill $LOG_PID
Running Tests
bash
# Unit tests
xcodebuild -workspace App.xcworkspace -scheme App \
  -destination "platform=iOS Simulator,id=$UDID" \
  test

# Specific test class
xcodebuild -workspace App.xcworkspace -scheme App \
  -destination "platform=iOS Simulator,id=$UDID" \
  -only-testing "AppTests/MyTestClass" \
  test

UI Automation

For tapping, typing, and UI element queries, use XCUITest (Apple's native UI testing framework).

This is more powerful than MCP-based automation because:

  • Native to iOS, always up-to-date
  • Full access to accessibility tree
  • Can wait for elements, handle animations
  • Integrates with Xcode test runner

See XCUITEST_GUIDE.md for complete patterns.

Quick example:

swift
// In a UI test file
func testLogin() {
    let app = XCUIApplication()
    app.launch()

    // Type in text field
    app.textFields["email"].tap()
    app.textFields["email"].typeText("user@example.com")

    // Tap button
    app.buttons["Login"].tap()

    // Verify result
    XCTAssertTrue(app.staticTexts["Welcome"].exists)
}

Run UI tests:

bash
xcodebuild -workspace App.xcworkspace -scheme AppUITests \
  -destination "platform=iOS Simulator,id=$UDID" \
  test

Session Configuration

Unlike MCP, CLI tools don't maintain session state. Use environment variables or a config file:

bash
# Set up session variables
export XCODE_WORKSPACE="/path/to/App.xcworkspace"
export XCODE_SCHEME="App"
export SIM_UDID="DD5E339B-468E-43C7-B219-54112C9D3250"
export APP_BUNDLE_ID="com.your.app"

# Use in commands
xcodebuild -workspace "$XCODE_WORKSPACE" -scheme "$XCODE_SCHEME" ...
xcrun simctl launch "$SIM_UDID" "$APP_BUNDLE_ID"

Troubleshooting

Build fails with "no matching destination"
bash
# Check available destinations
xcodebuild -workspace App.xcworkspace -scheme App -showDestinations

# Use exact destination string from output
Simulator won't boot
bash
# Check if already booted
xcrun simctl list devices | grep Booted

# Force shutdown and reboot
xcrun simctl shutdown $UDID
xcrun simctl boot $UDID
Can't find built .app
bash
# Check derived data path you specified
ls -la /tmp/build/Build/Products/Debug-iphonesimulator/

# Or use default derived data
ls ~/Library/Developer/Xcode/DerivedData/

Key Differences from XcodeBuildMCP

FeatureXcodeBuildMCPThis Skill
Buildbuild_sim({...})xcodebuild -workspace ... build
List simslist_sims()xcrun simctl list devices
Launch applaunch_app_sim({...})xcrun simctl launch $UDID $BUNDLE
Screenshotscreenshot({...})xcrun simctl io $UDID screenshot
Tap/Typetap({x,y}), type_text({...})XCUITest framework
Session stateBuilt-inEnvironment variables

© pzep1, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 2 other files in skills/xcode-build of pzep1/xcode-build-skill.

  • SKILL.md
  • CLI_REFERENCE.md
  • XCUITEST_GUIDE.md

Open the folder on GitHubat commit 9b5c313

Compare with similar skills

Xcode Build next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Xcode Build compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Xcode Build this skillpzep1/xcode-build-skill138—~1.5kAutomated safety check: NotesMIT
Orca iOS Simulator Controlstablyai/orca87k1 repos~584Automated safety check: PassApache-2.0
Apple Crash Log .NET Symbolicationdotnet/skills5.6k1 repos~2.4kAutomated safety check: PassMIT
Update Swiftui APIsAvdLee/SwiftUI-Agent-Skill3.7k—~1.2kAutomated safety check: PassMIT
iOS Simulator Skillconorluddy/ios-simulator-skill1.3k—~5.7kAutomated safety check: PassMIT
Macios Xcode Beta Updatedotnet/macios2.9k—~1.8kAutomated safety check: PassCustom licence

Similar skills

  • iOS Simulator control from inside Orca, with the live device view in Orca's emulator pane. Use when driving a booted Apple Simulator on macOS: taps, gestures…

    87k GitHub starsUsed in 1 repo~584 tokens
    MobileAuto-check passed
  • Official

    Resolves .NET runtime frames in Apple .ips crash logs to function names, source files and line numbers using dSYM symbols, atos and the Microsoft symbol server.

    5.6k GitHub starsUsed in 1 repo~2.4k tokens
    MobileAuto-check passed
  • Update Swiftui APIs

    AvdLee/SwiftUI-Agent-Skill

    Scan Apple's SwiftUI documentation for deprecated APIs and update the SwiftUI Expert Skill with modern replacements.

    3.7k GitHub stars~1.2k tokensUpdated yesterday
    MobileAuto-check passed
  • iOS Simulator Skill

    conorluddy/ios-simulator-skill

    29 production-ready scripts for iOS app testing, building, and automation.

    1.3k GitHub stars~5.7k tokensUpdated yesterday
    MobileAuto-check passed
  • Official

    Update dotnet/macios to a new Xcode beta and validate it end-to-end.

    2.9k GitHub stars~1.8k tokensUpdated today
    MobileAuto-check passed
  • Odevio

    Odevio/Odevio-CLI

    Take a Flutter project to an iPhone or the App Store with Odevio - build, sign and publish iOS apps from Windows, Linux or macOS with no Mac and no Xcode.

    423 GitHub stars~7.6k tokensUpdated 13 days ago
    MobileAuto-check passed

Categories

Questions about Xcode Build

What does Xcode Build do?

Build and run iOS/macOS apps using xcodebuild and xcrun simctl directly. Xcode Build is an agent skill from pzep1/xcode-build-skill. Build and run iOS/macOS apps using xcodebuild and xcrun simctl directly.

When should I use Xcode Build?

Xcode Build fits situations like: building Xcode projects; running iOS simulators; managing devices; compiling Swift code.

How do I install Xcode Build in Claude Code?

Run `npx skills add pzep1/xcode-build-skill --skill xcode-build -a claude-code`. Or copy the skill folder (skills/xcode-build in pzep1/xcode-build-skill) into .claude/skills/xcode-build in your project. Claude Code loads it when a task matches its description.

How do I install Xcode Build in Codex?

Run `npx skills add pzep1/xcode-build-skill --skill xcode-build -a codex`. Or copy the skill folder (skills/xcode-build in pzep1/xcode-build-skill) into .agents/skills/xcode-build in your project. Codex loads it when a task matches its description.

Can I use Xcode Build in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add pzep1/xcode-build-skill --skill xcode-build -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/xcode-build, .gemini/skills/xcode-build, .github/skills/xcode-build and .opencode/skills/xcode-build in your project.

What does Xcode Build need to run?

Going by SKILL.md and its folder, Xcode Build needs the command-line tools its instructions call (xcrun, xcodebuild and jq). Its frontmatter pre-approves these tools: Bash, Read, Grep, Glob.

Does Xcode Build access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Xcode Build safe to install?

Our automated static check of SKILL.md found notes only (pre-approves every shell command (allowed-tools: bash)), nothing it rates as a warning. It is not a guarantee. Review the folder before installing.

What licence does Xcode Build use?

Xcode Build is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Xcode Build use?

About 1.5k tokens (SKILL.md is roughly 5.9k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Xcode Build?

Skills that share tags, products or a category with Xcode Build: Orca iOS Simulator Control (stablyai/orca, 87k stars), Apple Crash Log .NET Symbolication (dotnet/skills, 5.6k stars), Update Swiftui APIs (AvdLee/SwiftUI-Agent-Skill, 3.7k stars) and iOS Simulator Skill (conorluddy/ios-simulator-skill, 1.3k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Xcode Build?

pzep1 (a GitHub user) maintains it in pzep1/xcode-build-skill, which has 138 GitHub stars. The repository was last updated on February 4, 2026.

Source: pzep1/xcode-build-skill on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.