ios-agent-skill

iOS Agent Skill is an open-source project for AI coding agents that provides agents with the Apple reference materials, Swift source code, and local tools needed to build and review iOS apps.

Purpose This project is designed to enable AI coding agents to plan, write, and verify iOS apps. From a one-sentence app description, the /ios-build agent plans the app, writes SwiftUI code and the Xcode project, and applies capability modules (such as login, storage, payment, maps, and so on), then builds, runs, and takes screenshots in the iOS Simulator, and finally reports which parts require the user's own account or payment. For existing projects, the same package provides agents with code review, local Apple reference materials, and Simulator tools to inspect their work.

Main capabilities

• One-sentence app building: the /ios-build "<requirement>" command lets Claude Code plan an iOS app, write SwiftUI code and the Xcode project, apply capability modules, and build, run, and take screenshots in the Simulator.
• Code review: provides static review tools for existing projects (these are heuristic rules, not compiler diagnostics).
• Capability modules: each capability is a folder under capabilities/ containing a manifest, recipe, Swift templates, apply hook, and verify hook. The catalog contains 162 entries and 31 categories.
• Toolset: the published npm 2.10.1 package contains build agent tools and 80 unified tools, including 7 Apple system integration tools and 9 Screenshot Studio tools.
• Local Apple documentation: after installing the documentation archive in Xcode, read it via Window → Developer Documentation, bridged using xcrun mcpbridge, with the archive managed by Xcode. Provides version-aware documentation retrieval, preferring Xcode MCP DocumentationSearch, followed by bounded SDK evidence.
• Simulator tools: use the xcode-mcp tool to discover the Xcode schema, and use doctor xcode to diagnose settings.
• Release process: ios-agent-mcp ship prepares the screenshot set and metadata, then provides separateApproved signing/archiving and TestFlight upload steps (online signing distribution not yet verified, npm not updated).
• Remote build: The GitHub source includes build --remote, used for unsigned builds and simulator screenshots on GitHub Actions, requiring a target repository, GitHub CLI authentication, and a pinned toolchain/Xcode version.

Usage After installing the published server and Claude Code commands, use them in any Claude Code session on a Mac with Xcode 16 or later. Connections can also be set up for ChatGPT/Codex, Gemini CLI, or Muse. Requires Node.js 20+; local iOS builds require macOS and Xcode; remote channels run on Actions. A starter can be created directly: --xcodegen writes project.yml, which XcodeGen converts into a project. For a complete app, use /ios-build. Optional commands: ios-agent-mcp environment to view the actual Xcode/SDK/simulator inventory; ios-agent-mcp ai models and ai doctor to view the catalog and account/local availability. Text generation uses the on-device Apple model by default; cloud providers and fallback require explicit configuration. Local Apple documentation requires installing the archive in Xcode → Settings → Components → Developer Documentation.

Use cases

• Quickly prototype an iOS app from a one-sentence description (SwiftUI + Xcode project).
• Perform focused code reviews of existing iOS projects.
• Provide AI agents with local Apple framework reference materials and version-aware documentation retrieval.
• Build, run, take screenshots, and collect verification evidence in the simulator.
• Quickly integrate features such as login, storage, payments, and maps through capability modules.

Limitations

• Requires a user account: the agent can build and run in the simulator without an account; capabilities that require services declare keys in the manifest, client keys are placed in the project's gitignored .env file, passed into the app via the generated xcconfig, and when not set are REPLACE_ME placeholder. Server keys are not placed into the app. Running on a device, using TestFlight, or releasing requires Apple Developer Program membership.
• The design system, firebase-auth, firebase-firestore, google-sign-in, stripe-payments, rive-animation, and webview-animation capabilities have been verified by compilation on an isolated Mac; provider accounts and runtime transactions have not yet been verified, and combined compilation checks cannot replace the verify run of each module.
• The agent's build, simulator launch, and screen-by-screen screenshot stages have been run on a Mac against four existing examples; the original planning and code generation sessions are separate, and a brand-new one-sentence end-to-end generation has not yet been run on a Mac.
• Taps and scrolls during the agent's own screenshots, as well as device builds, have not yet been completed. In the food delivery example, StoreKit purchases and Live Activity were not executed.
• Static review is heuristic rules, not compiler diagnostics. The Apple catalog is a reference map, not Apple proprietary framework source code, and does not prove that there are 405 usable integrations. Token savings have not been benchmarked.
• XcodeGen is optional: without it, the agent writes the folder-synchronized Xcode project itself.
• The paired benchmark tool contains 20 Swift micro-tasks; results have not been published, and full app builds have not yet been measured.
• prepare_issue_report allows the AI to prepare a local report when the iOS Agent tool fails, accepts only fixed categories, shows a preview and duplicate search links, public submission is completed by the user, and it does not collect app source code or logs. private_feedback is an experimental tool, hosting is not configured, and private submission is not live.
• The project focuses on four client families; other clients can submit support requests, and existing experimental adapters are not actively maintained.
• install.sh is optional and installs source guidance for selected local clients; it is not an MCP server or a browser extension.
• The Apple catalog tracks 99 technologies, covers 99, with 100% coverage, but the coverage count describes documentation rather than compiled integrations. Download counts refresh daily and do not represent unique users.
• License: MIT.