iOS Agent Skill
Swift code reviews and local Apple source/guide retrieval for Claude and other MCP clients. Optional Xcode simulator tools build, test, launch and preview apps.
Documentation
iOS Agent Skill
One install, one MCP connection (2.5.1)
claude mcp add ios-agent -- npx -y ios-agent-mcp@2.5.1
The default server exposes 34 tools: 11 Swift reviews, 8 Apple reference tools, 14 simulator tools, and create_app. App scaffolding and simulator packages install automatically as dependencies; no separate installation or MCP connection is needed. Remove the separate knowledge/simulator connections if you previously configured them to avoid duplicate tools.
Create a starter directly:
npx -y ios-agent-mcp@2.5.1 new MyApp --brief "A reading list with local storage" --xcodegen
Requires Node.js 20+. Simulator operations require macOS and Xcode; XcodeGen is required to generate an Xcode project from the starter specification. The agent implements app features using the starter, source tools and verification tools. One install is not autonomous app generation. The default connection now includes tools that write files and operate the simulator; review and reference tools remain read-only.
Give your AI coding agent local Swift source, Apple guides, code review tools, and a way to see the app running.
Build with Claude, Codex, or Gemini CLI. Portable references are also available for ChatGPT workflows. Free and open source under MIT.
Try it in your next app
Install the skill into your coding agent:
npx skills add Nagarjuna2997/ios-agent-skill
For build/run/screenshot tools, also configure the optional simulator MCP on a Mac with Xcode. Installing the skill alone adds guidance, not runtime tools.
Then ask:
Build a SwiftUI reading list with local persistence, search, and accessible empty/error states. Reuse this skill's local source where it fits. Run the build and tests, and show simulator evidence for what you verified.
Already have an app? Ask: “Review this project for concurrency, architecture, accessibility, and security issues. Give me file locations and fix the blockers first.”
Client setup · Start a new app · Download integrations · Contribute
What makes it useful
| Feature | What you can do |
|---|---|
| Local source, retrieved in small sections | Search complete editable Swift files, templates, and guides; read only the matching section using offline commands or MCP. No need to load the whole library into each prompt. |
| Apple technology discovery: Accelerate → XPC | Navigate 405 unique technology entries, plus updates and release notes, with official Apple attribution and dated snapshots. |
| 11 read-only Swift review tools | Find concurrency, architecture, SwiftUI, memory, security, testing, performance, and App Store readiness issues with file-level findings. |
| Build → run → see | Use 14 simulator tools to build/test, launch an app, capture screenshots, and open a private browser preview alongside your agent. Requires macOS and Xcode. |
| An app starter you own | Generate a Swift starter, app brief, optional XcodeGen spec, and editable icon layers. Your coding agent implements the features; you keep the source. |
| Examples with tests | Reuse SkillPatterns and AppleRecipes: persistence, networking, cryptography, language, vector statistics, and PDF recipes. |
Local retrieval bounds output size; token and cost savings depend on the model and task and have not been benchmarked. The catalog is a discovery map, not 405 completed framework implementations or Apple's proprietary source. Static reviews are heuristic findings; builds, tests, and runtime checks supply separate evidence.
What This Is
ios-agent-skill is a repo you can install into AI coding tools so they behave more like senior iOS engineers:
- The skill teaches the agent what good Apple-platform code looks like.
- The static MCP server reviews an existing Swift project and returns structured findings.
- The CLI scaffolds a clean iOS project layout.
- The simulator MCP package is the first runtime slice: build, test, install, launch, deep link, and screenshot through Xcode and Simulator.
- The subagents route specialized work to reviewers for SwiftUI, UIKit, RealityKit, Metal, WebKit, testing, security, performance, App Store readiness, and more.
The central rule is simple: do not let an agent say "it works" without evidence. Build output, test output, screenshots, logs, and structured findings matter more than confident prose.
All Apple Technologies
The complete Apple technology directory covers 405 unique entries, from Accelerate to XPC, checked against Apple on 2026-09-10. It reuses existing guides for 83 technology entries and adds 322 dedicated reference pages, with platform metadata and 11,500 API/topic links. Five Apple directory entries lead to external resources.
The machine-readable snapshot and python3 scripts/sync-apple-technologies.py --check keep names, URLs, routes, and generated pages consistent. Use --refresh to retrieve the live directory again. This is complete technology-level discovery, not a per-symbol documentation mirror or a claim that every integration has been compiled.
Why It Exists
AI-generated Swift often compiles while still being wrong in production-shaped ways.
| Problem | Common AI output | This repo enforces |
|---|---|---|
| Concurrency | @Observable state read by SwiftUI with no @MainActor isolation | Main-actor UI state, Sendable boundaries, structured tasks |
| Architecture | View models creating URLSession, ModelContext, or singletons directly | Protocol boundaries, dependency injection, preview-safe screens |
| Availability | #available(iOS 27, *) around an API introduced earlier | Guards on the symbol's real introduction version |
| Error handling | try!, empty catch, swallowed failures | User-visible outcomes or documented deliberate no-ops |
| Design | Fixed fonts, literal colors, inaccessible icon buttons | Design tokens, Dynamic Type, contrast, VoiceOver labels |
| Verification | "Should work now" | Commands run, output shown, evidence labelled |
Start with your app idea
npx -y @nagarjuna2002/ios-agent@0.2.0 new MyApp --brief "Describe the app you want" --xcodegen
Open the generated folder with your coding agent and ask it to implement App/APP_BRIEF.md through build and screen verification. The starter includes an XcodeGen project spec and separate editable icon layers. Full idea-to-app workflow.
Claude, ChatGPT/Codex and Gemini
- Claude and Codex: local MCP analyzers plus eight Apple knowledge/source tools. A Codex plugin ZIP is included in releases.
- ChatGPT: a portable skills-only plugin ZIP with bundled references. The optional knowledge server supports HTTP for deployment to your own HTTPS host.
- Gemini CLI: install this GitHub repository as an extension; it includes both MCP connections and GEMINI guidance.
Client installation · Knowledge MCP · Apple updates and release notes · Layer-by-layer Icon Composer workflow · Release downloads
The release artifacts are installable packages, not a claim of acceptance into a public plugin marketplace. Xcode builds and native Icon Composer editing require a compatible Mac environment.
Quick Install
Install the skill
Use this when you want your AI agent to load the iOS rules while writing code:
npx skills add Nagarjuna2997/ios-agent-skill
Or clone it into an iOS project so tools can read the mirrored instruction files:
cd /path/to/YourApp
git clone https://github.com/Nagarjuna2997/ios-agent-skill.git .ios-skill
Install the static MCP analyzer
ios-agent-mcp is published on npm. Reviews and references are read-only; app creation and simulator tools have write/runtime effects. Simulator operations require Xcode.
claude mcp add ios-agent -- npx -y ios-agent-mcp --project /path/to/YourApp
Generic MCP config:
{
"mcpServers": {
"ios-agent": {
"command": "npx",
"args": ["-y", "ios-agent-mcp", "--project", "/path/to/YourApp"]
}
}
}
More client setup is in docs/mcp/installation.md.
Use the CLI
The CLI is published on npm. For a quick start, use npx -y @nagarjuna2002/ios-agent@0.2.0 new MyApp --xcodegen. To develop it from source:
cd cli
npm install
npm run build
node dist/index.js new MyApp
The CLI creates a visible app root and keeps tool-owned state under .ios-agent/.
Use the simulator MCP package from source
ios-simulator-mcp is intentionally separate from ios-agent-mcp because it requires macOS, Xcode, and simulator side effects.
cd ios-simulator-mcp
npm install
npm run build
node dist/index.js --help
Packages
| Package | Status | Runtime | Purpose |
|---|---|---|---|
| ios-agent-mcp | Version: 2.5.1 | Node 20+; runtime tools need Mac/Xcode | 34 tools in one default connection |
| @nagarjuna2002/ios-agent | Published: 0.2.0 | Node 20+ | Project scaffolding, app briefs, editable icon layers |
| @nagarjuna2002/ios-simulator-mcp | Published: 0.2.0 | macOS + Xcode | 14 tools for runtime evidence and browser preview |
| samples/SkillPatterns | CI sample | Swift Package Manager | Compile-checked examples of the rules |
MCP Tools
The unified server includes these eleven read-only review tools:
| Tool | Use when |
|---|---|
analyze_swift_project | You need a project overview, file counts, frameworks, architecture signals, DI evidence, and issue totals |
review_swift_concurrency | You are checking actor isolation, @MainActor, Sendable, task structure, and empty catches |
review_swift_architecture | You are checking MVVM/Clean Architecture boundaries and dependency injection |
review_swiftui | You are checking SwiftUI layout, state, deprecated APIs, design tokens, and accessibility basics |
check_availability_guards | You are checking iOS version guards and runtime model availability |
audit_app_store_readiness | You are checking Info.plist permissions, privacy manifest risk, localization, labels, and diagnostics |
review_swift_memory | You are checking retain cycles, delegates, timers, Combine sinks, and unowned self |
review_swift_security | You are checking secrets, ATS, HTTP, Keychain accessibility, weak hashes, randomness, and JS injection |
review_swift_testing | You are checking test quality, flakiness, sleeps, live network, and vacuous tests |
review_swift_performance | You are checking SwiftUI render-path work, formatters, sorting, stacks, and blocking I/O |
lint_skill | You are checking this skill repo or another Agent Skill for metadata, mirrors, agents, and references |
Every review returns markdown plus structuredContent with counts, issues, score, checked files, and suggestions.
Simulator Tools
@nagarjuna2002/ios-simulator-mcp exposes 14 runtime tools:
| Tool | Backend |
|---|---|
simulator_list | xcrun simctl list devices available --json |
simulator_environment | Installed Xcode, runtime and device availability |
simulator_show | Open native Simulator |
simulator_preview_start | Start private, read-only browser screenshot preview |
simulator_preview_stop | Stop browser preview |
simulator_boot | xcrun simctl boot |
simulator_shutdown | xcrun simctl shutdown |
build_project | xcodebuild build |
run_tests | xcodebuild test |
install_app | xcrun simctl install |
launch_app | xcrun simctl launch |
terminate_app | xcrun simctl terminate |
open_deep_link | xcrun simctl openurl |
screenshot | xcrun simctl io screenshot |
No current simulator tool erases all simulator content. Video, logs, UI gestures, accessibility-tree inspection, and visual comparison are planned next. See docs/tooling/ios-simulator-mcp.md.
What It Checks
Example MCP finding:
Sources/FeedModel.swift:3
Severity: blocker
Rule: observable-without-mainactor
@Observable type is not @MainActor-isolated.
Why it matters:
SwiftUI reads observable state during layout. A background write can become a
data race under Swift 5 mode and a compile error under Swift 6 strict checking.
Fix:
Annotate UI-rendered observable state:
@MainActor @Observable final class FeedModel { ... }
The same rules are documented in the skill docs so agents can learn the fix before generating new code.
Documentation Map
Start here:
Curated Framework Guide Coverage
This smaller, curated guide index is separate from the 405-entry Apple directory above. “Covered” tracks documentation coverage, not compiled integrations.
Apple catalog tracked: 99 technologies. Covered: 99. Planned: 0. Skipped: 0. Deprecated: 0. Coverage: 100.0%.
Source of truth: frameworks.json. Human index: docs/apple-framework-index.md.
The catalog is generated and checked by CI. Update frameworks.json, then run:
node scripts/check-framework-catalog.mjs
Subagents
The repo ships 24 specialist subagents in .claude/agents. Highlights:
| Agent | Use for |
|---|---|
swift-reviewer | Independent read-only verification before shipping |
swift-debugger | Reproduce, isolate, fix, and prove a Swift failure |
swiftui-expert | SwiftUI layout, state, navigation, and modern interactions |
ui-ux-designer | Product UI hierarchy, accessibility, state design, and polish |
realitykit-expert | RealityKit, Model3D, ARKit integration, and spatial review |
metal-expert | Metal rendering, shaders, compute, and frame-loop review |
testing-expert | Swift Testing, XCTest, XCUIAutomation, and evaluations |
xcode-expert | Xcode projects, schemes, Device Hub, and Instruments |
security-reviewer | Authentication, Keychain, privacy, permissions, and threat modeling |
app-store-reviewer | App Review, StoreKit, privacy manifests, release risk |
Read routing guidance in docs/orchestration/router.md and docs/orchestration/subagents.md.
Recommended Workflow
For a new iOS app:
- Create the real Xcode project first in Xcode.
- Add this skill repo as
.ios-skill/or install it through your AI tool. - Configure
ios-agent-mcpwith--project /path/to/YourApp. - Ask the agent to build features inside the Xcode project, not beside it.
- Run static MCP reviews.
- Build and test in Xcode or with
ios-simulator-mcp. - Capture screenshots or logs before claiming the UI/runtime path works.
For an existing app:
claude mcp add ios-agent -- npx -y ios-agent-mcp --project /path/to/ExistingApp
Then ask:
Analyze this Swift project and list blockers first.
Review concurrency, SwiftUI, security, testing, performance, and App Store readiness.
Show evidence and exact file locations.
Local Development
Run repo consistency checks:
./scripts/hooks/verify-repo.sh
node scripts/check-framework-catalog.mjs
./scripts/eval-agents.sh --table
Run the static MCP package:
cd mcp-server
npm install
npm run typecheck
npm run build
npm test
Run the CLI package:
cd cli
npm install
npm run typecheck
npm run build
npm test
Run the simulator MCP package:
cd ios-simulator-mcp
npm install
npm run typecheck
npm run build
npm test
Publishing
ios-agent-mcp@2.5.1 is published on npm:
npm view ios-agent-mcp version
npm publishing is manual from a local trusted machine. GitHub Actions creates GitHub Releases but does not store npm tokens or run npm publish.
cd mcp-server
npm login
npm publish --access public
If npm asks for security-key approval, use the browser link printed by the CLI and approve with the passkey/security key registered on the npm account.
Roadmap
Current state:
- v3.3.0 repository release: local source library, Apple catalog, cross-client integrations, and simulator preview.
- npm: unified package 2.5.1, app CLI 0.2.0, and simulator package 0.2.0.
Next work:
- Add runtime video capture and log streaming.
- Choose the UI automation backend for tap, swipe, type, and accessibility-tree inspection.
- Add visual-review loops that pair screenshots with UI/UX, accessibility, motion, RealityKit, Metal, and performance reviewers.
- Expand static review contracts for UI/UX, motion, haptics, 3D, AI safety, and evaluations.
Detailed planning lives in ROADMAP.md.
Works With
Primary support is intentionally focused on:
- Claude Code and Claude Desktop
- ChatGPT / Codex
- Gemini CLI
Other instruction-file mirrors may exist in the repo for compatibility, but the product direction is Claude, ChatGPT/Codex, and Gemini first.
Contributing
Read CONTRIBUTING.md before changing docs, agents, mirrors, or package behavior.
Important rules:
- Edit
SKILL.md, then run./scripts/sync-mirrors.sh; do not hand-edit mirrors. - Keep examples complete and compiling.
- Add tests when behavior changes.
- Do not commit npm tokens, recovery codes,
.npmrccredentials, or GitHub secrets.
License
MIT. See LICENSE.