Ios Agent Skill

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.

Why It Exists

AI-generated Swift often compiles while still being wrong in production-shaped ways.

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. It is read-only and does not 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 currently used 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

MCP Tools

ios-agent-mcp exposes eleven read-only tools:

Every review returns markdown plus structuredContent with counts, issues, score, checked files, and suggestions.

Simulator Tools

ios-simulator-mcp currently exposes the safe first slice of runtime automation:

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:

Apple Technology Catalog

Apple catalog tracked: 98 technologies. Covered: 68. Planned: 30. Skipped: 0. Deprecated: 0. Coverage: 69.4%.

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:

Read routing guidance in docs/orchestration/router.md and docs/orchestration/subagents.md.

Recommended Workflow

For a new iOS app:

1. Create the real Xcode project first in Xcode.
2. Add this skill repo as .ios-skill/ or install it through your AI tool.
3. Configure ios-agent-mcp with --project /path/to/YourApp.
4. Ask the agent to build features inside the Xcode project, not beside it.
5. Run static MCP reviews.
6. Build and test in Xcode or with ios-simulator-mcp.
7. 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

[email protected] 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:

• v2.1: static MCP analyzer complete and published.
• v3.0: Apple Platform Intelligence docs, catalog, routing hubs, and specialist subagents.
• v4.0 seed: executable simulator MCP package for Build -> Run -> See evidence.

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

Claude Code, Claude Desktop, Cursor, Codex, GitHub Copilot, Windsurf, Gemini CLI, Cline, Roo, Zed, JetBrains AI, Amazon Q, Trae, Continue, Aider, Replit, and other tools that can read instruction files or connect to MCP servers.

See docs/ai-setup-guide.md for setup notes.

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, .npmrc credentials, or GitHub secrets.

License

MIT. See LICENSE.