Ios Agent Skill

iOS Agent Skill

Give your coding agent the Apple references, Swift source and local tools it needs to build and review an iOS app.

[iOS Agent Skill website preview]

Watch the website walkthrough · Explore the website

Describe an app in one sentence and the /ios-build agent plans it, writes the SwiftUI code and Xcode project, then builds and runs it in the simulator (what has been verified, example apps on the website). For an existing project, the same package gives your coding agent reviews, local Apple references and simulator tools to check its work.

[Tests] [Docs] [npm total downloads]

Explore the website · Client setup guides · npm · Release notes

Build an app from one sentence

/ios-build "<what you want>" asks Claude Code to plan an iOS app, write its SwiftUI code and Xcode project, apply capability modules (sign-in, storage, payments, maps and more), then build, run and screenshot it in the iOS Simulator, ending with a report of what needs your accounts or money. Published tools are in ios-agent-mcp 2.10.2 (npm verified October 15, 2026), including plan-driven design tokens, sample data, palette-aligned assets, light/dark/XXL screenshot evidence, deployment-target checks and App Store readiness reports. Four existing apps built and ran on Xcode 27.0; see examples/agent for refreshed evidence.

Quickstart

Install the published server and Claude Code command:

claude mcp add ios-agent -- npx -y ios-agent-mcp@latestnpx -y ios-agent-mcp@latest install-command --global

Then, in any Claude Code session on a Mac with Xcode 16 or later:

/ios-build "A habit tracker with a list, a detail screen, and settings with dark mode toggle"

Shipping (unreleased GitHub source): ios-agent-mcp ship prepares screenshot sets and metadata, then offers separately approved signing/archive and TestFlight upload steps. Setup and limitations. Live signed distribution is not yet verified; npm is unchanged.

Windows/Linux or cloud client: the GitHub source now includes build --remote for unsigned builds and simulator screenshots on GitHub Actions. It requires a destination repository, GitHub CLI authentication and pinned toolkit/Xcode versions. See remote macOS setup and billing. npm publication is deferred.

XcodeGen is optional: without it, the agent writes a folder-synchronized Xcode project itself. The steps are described in docs/tooling/ios-build-agent.md. The four screenshot examples reused existing app folders; this exact one-sentence quickstart has not yet been run from planning through code generation in one Mac session.

Examples

Plans, generated sources, run reports and what was and was not exercised: examples/agent.

Capabilities

Every capability is a folder in capabilities/ with a manifest, recipe, Swift template, apply hook and verify hook. The catalog lists the wider landscape for planning and cost estimates. The counts below are generated from the manifests.

162 catalog entries in 31 categories; generated from capabilities/CATALOG.md.

Needs your accounts

The agent builds and runs everything in the simulator without accounts. Capabilities that need a service declare the keys in their manifest. Client keys, such as a publishable key, go in the project's gitignored .env file and reach the app through a generated xcconfig. Until they are set, the keys are REPLACE_ME placeholders, so the app still builds and shows a configuration message. Server secrets are never put in the app. PLAN.md lists what each run needs and the cost model of each service. Running on a device, using TestFlight or publishing needs your Apple Developer Program membership.

Not yet

• The design-system, firebase-auth, firebase-firestore, google-sign-in, stripe-payments, rive-animation and webview-animation capabilities have passed isolated Mac compile verification. Provider accounts and runtime transactions remain unverified; a combined compile check is not a substitute for each module's verify run (see the compile check).
• The agent's build, simulator launch and per-screen capture stages ran on Mac for these four existing examples. The original planning and code-generation sessions were separate, and a fresh one-sentence generation has not yet been run end to end on Mac.
• Taps and scrolling during the agent's own screenshots, and device builds, are not done. In the food-delivery example the StoreKit purchase and the Live Activity were not exercised.

Which workflow to use

Start with one connection

For Claude Code:

claude mcp add ios-agent -- npx -y ios-agent-mcp@latest

Set up ChatGPT/Codex, Gemini CLI or Muse. One npm package includes reviews, local references, app scaffolding and simulator tools. Node.js 20+ is required; local iOS builds need macOS and Xcode; the GitHub-source remote lane runs those steps on Actions.

Then ask:

Build a SwiftUI reading list with local persistence, search and accessible empty/error states. Reuse the local source library. Build it, run the tests and capture simulator evidence. Explain any checks that fail.

For an existing app, provide its absolute project path and ask for a focused review before making changes.

What it helps you do

Asset generation · Review tools · Simulator setup · Apple release status

Create a starter directly:

npx -y ios-agent-mcp@latest new MyApp --brief "A reading list with local storage" --xcodegen

The starter is not a finished app: --xcodegen writes a project.yml that XcodeGen turns into a project. For a complete app from a description, use /ios-build. Generated app ownership and branding belong to the user.

See the evidence

The Reading List demo has persistence, search, simulator acceptance tests and captured screens. The four apps the /ios-build agent planned and wrote, with their plans, run reports and simulator screenshots, are in examples/agent.

The published npm 2.10.2 package includes the build-agent tools, deployment-target checks and App Store readiness reports. They include seven Apple system integration tools and nine Screenshot Studio tools. Static reviews are heuristics, not compiler diagnostics. The Apple directory is a reference map, not Apple's proprietary framework source or proof of 405 working integrations. Token savings have not been benchmarked. Build-loop verification limits.

Why use this alongside Xcode?

Xcode already ships agent expertise and build/test tools. Use those when they meet your needs. This repository adds shared guidance across these four client families, inspectable review rules, local source retrieval and repeatable asset workflows. It has not been established that it makes an AI outperform Xcode's skills or use fewer tokens.

Where the guidance comes from, evidence and unfinished work. The paired benchmark harness contains 20 Swift microtasks; results are not published, and it does not yet measure complete app builds.

Help improve the tools

Failure feedback belongs in your coding session: the observed error, the proposed fix and actual verification results. The source server adds troubleshooting guidance to returned tool errors; agent instructions also cover compiler/test failures. These messages do not appear in the app you are building.

prepare_issue_report lets your AI prepare a local report when an iOS Agent tool fails. It accepts fixed categories only, shows a preview and a duplicate-search link, and leaves public submission to you. No app source or logs are collected. Reporting workflow.

Included as an experimental tool in 2.7.1: optional private_feedback keeps approval in the AI chat and sends fixed categories to a private inbox through a configured HTTPS receiver. Hosting is not configured, so private submission is not live. It never silently submits or falls back to public issues.

Four client families, one project

Optional companion: an AI/ML API connector can run beside the local server for icon and asset concepts on the user's own account. It is not bundled, called or verified by this project.

The project focuses on these five families. For another client, open a client-support request or add a 👍 to an existing request. Votes inform priorities alongside feasibility and testing; they do not guarantee delivery. Existing experimental adapters are not actively maintained.

install.sh is optional: it installs source guidance for a chosen local client, not the MCP server or a browser plugin. Run bash install.sh --help after cloning. Most users should use the client setup guide above.

Contributing · Development · Security · Roadmap · MIT license

Backend integration guidance: choose a service and review auth, data and security boundaries.

Optional provider commands

Use ios-agent-mcp environment to inspect the actual Xcode/SDK/simulator inventory. ios-agent-mcp ai models and ai doctor inspect the dated catalog and account/local availability. Text generation defaults to on-device Apple models; cloud providers and fallback require explicit configuration. Provider setup, handoff, simulator CLI and limits. These commands do not replace the coding client or claim autonomous app completion.

Local Apple documentation

Install the archive in Xcode → Settings → Components → Developer Documentation. Read it through Window → Developer Documentation (Shift–Command–0 with standard key bindings). This integration uses xcrun mcpbridge; the archive stays managed by Xcode.

Use xcode-mcp tools for discovered Xcode schemas and doctor xcode for setup diagnostics.

Use ios-agent-mcp docs status and ios-agent-mcp docs symbol SwiftUI.NavigationStack for version-aware documentation grounding. The adapter prefers Xcode MCP DocumentationSearch, then bounded SDK evidence. Apple’s archive is never bundled. Bridge authorization is required; retrieval is not automatic code validation. Setup, tools and limitations.

Experimental native source import

The feature-branch App IR prototype imports a bounded local HTML screen into a validated, source-mapped representation and generates native SwiftUI. It reuses the existing Xcode and simulator tooling. Unsupported markup is reported and blocks generation. This is not universal framework conversion and is not included in npm 2.10.2. See the architecture and roadmap and real native prototype evidence.

Experimental native conversion work, including the static React subset and saved-evidence review, is documented in the Universal App Engine architecture. These prototypes do not establish general React/Next.js compatibility or accepted visual fidelity.