Ios Agent Skill

iOS Agent Skill

Teach your AI coding agent to write iOS code like a senior engineer — then let it check its own work. An Agent Skill + MCP server for Swift 6.4, SwiftUI, Foundation Models, and Apple Intelligence.

---

Why

AI agents write Swift that compiles. They are much worse at the things that decide whether an app ships:

| | Without this skill | With it | |---|---|---| | Concurrency | @Observable with no @MainActor — a data race SwiftUI hits during layout | Isolation enforced, and checked by a tool | | Architecture | View models holding URLSession and singletons | Protocol boundaries; every screen previewable with no network | | Availability | #available(iOS 27, *) around an iOS 26 API — silently drops every iOS 26 device | Guards on the version the symbol was introduced | | Error handling | catch { } and try! | Every failure surfaces or is a documented no-op | | Verification | "It should work now" | Commands run, output pasted, claims labelled |

It encodes how senior iOS engineers actually work — and 100+ anti-patterns with the specific failure each one causes, because a code generator that has only seen correct examples still emits plausible, wrong code.

Install

As a skill — teaches the agent how to write iOS code:

npx skills add Nagarjuna2997/ios-agent-skill

Or clone into any project — 25+ agents auto-detect their own rule file (CLAUDE.md, AGENTS.md, .cursorrules, …):

git clone https://github.com/Nagarjuna2997/ios-agent-skill.git .ios-skill

As an MCP server — lets the agent review Swift you already have:

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

Claude Desktop, Cursor, and Windows/Linux setup: [docs/mcp/installation.md](docs/mcp/installation.md)

What it looks like

> You: Review my Swift project for concurrency problems.

🔴 Sources/FeedModel.swift:3 — @Observable type is not @MainActor-isolated.

   Why it matters: @Observable grants no isolation. SwiftUI reads this state
   during layout while any task may write it — a data race under Swift 5 mode,
   a compile error under Swift 6.

   Fix: Annotate the type: `@MainActor @Observable final class …`

   Rule `observable-without-mainactor` · see docs/swift/swift-concurrency.md

Every finding carries a file, a line, the consequence, the fix, and a link to the doc that explains it.

What's in it

| | | |---|---| | 🧠 The skill | 100+ files — Swift 6.4 concurrency, SwiftUI, Clean Architecture, 40+ Apple frameworks, design tokens, App Store checklists | | 🔌 [MCP server](mcp-server/) | 6 tools: concurrency, architecture, SwiftUI, availability guards, App Store readiness, project overview | | 🤖 [10 subagents](.claude/agents/) | explore, plan, review, debug, refactor, docs, Foundation Models, modernization, accessibility, performance | | ⚙️ [Orchestration](docs/orchestration/) | When to delegate, loop, or scale out — and the evidence rule that stops "it works" without proof | | 🪝 [Hooks](templates/hooks/) | Deterministic enforcement at write time, plus CI | | ✅ [Compile-checked sample](samples/SkillPatterns/) | An SPM package CI builds and tests on every push — the patterns are verified, not asserted |

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 10+ more — [full list](docs/ai-setup-guide.md)

---

Adoption and Community Usage

This repository tracks public adoption evidence in [ADOPTION.md](ADOPTION.md), including repository metrics, public mentions, user feedback, and projects built with the skill.

If you use this skill in a public project, tutorial, or workflow, please open an issue or discussion so it can be listed as community evidence.

:book: [Complete AI Setup Guide (Mac + Windows) for ALL 28 Tools](docs/ai-setup-guide.md)

---

:warning: Important: Create Your Xcode Project FIRST

> This skill generates Swift files, not a full Xcode project. You must create the Xcode project first, then use your AI agent to build features inside it.

Step 1: Create the Xcode Project

1. Open Xcode (macOS only — required for iOS development)
2. Click File → New → Project (or press Cmd + Shift + N)
3. Select App under iOS (or Multiplatform for cross-platform)
4. Fill in the project details:

• Product Name: YourAppName
• Team: Select your Apple Developer account (or Personal Team)
• Organization Identifier: com.yourname (e.g., com.nagarjuna)
• Interface: SwiftUI
• Language: Swift
• Storage: SwiftData (or None if you don't need persistence)

1. Click Next → Choose a folder → Click Create
2. Xcode creates the full project structure:

`` YourAppName/ ├── YourAppName.xcodeproj ← Xcode project file ├── YourAppName/ │ ├── YourAppNameApp.swift ← App entry point │ ├── ContentView.swift ← Main view │ ├── Assets.xcassets ← App icons, colors, images │ ├── Preview Content/ ← Preview assets │ └── Info.plist ← (if visible) └── YourAppNameTests/ └── ... ``

Step 2: Clone This Skill Into Your Project

cd /path/to/YourAppName
git clone https://github.com/Nagarjuna2997/ios-agent-skill.git .ios-skill

Step 3: Open Your AI Agent and Start Building

Now open your project folder in your preferred AI coding tool:

# Claude Code
cd /path/to/YourAppName && claude

# Codex
cd /path/to/YourAppName && codex

# Cursor — just open the folder in Cursor

# Any other tool — open the folder in your IDE

Step 4: Ask the AI to Build Features

The AI will create/modify .swift files inside your Xcode project:

"Add a login screen with email and password fields"
"Create a settings page with dark mode toggle"
"Add a tab bar with Home, Search, and Profile tabs"
"Implement a networking layer to fetch data from my API"

Step 5: Run in Xcode

Go back to Xcode → Press Cmd + R (or click the Play button) to build and run on the simulator.

> Why this workflow? AI agents generate Swift source files (.swift), but iOS apps need a proper Xcode project (.xcodeproj) with build settings, signing, asset catalogs, and simulator configuration. Xcode is the only tool that can compile, sign, and run iOS apps. Your AI agent writes the code — Xcode builds and runs it.

Alternative: Use the Template

If you want to skip Xcode project creation, copy our ready-made template files into a new Xcode project:

# After creating Xcode project, copy template files
cp ios-agent-skill/templates/ios-app/*.swift /path/to/YourAppName/YourAppName/
cp -r ios-agent-skill/templates/ios-app/Views/ /path/to/YourAppName/YourAppName/Views/
cp -r ios-agent-skill/templates/ios-app/ViewModels/ /path/to/YourAppName/YourAppName/ViewModels/
cp -r ios-agent-skill/templates/ios-app/Models/ /path/to/YourAppName/YourAppName/Models/

Then open Xcode → Right-click the project → Add Files to "YourAppName" → Select the new folders.

---

:zap: One-Line Install

curl -sL https://raw.githubusercontent.com/Nagarjuna2997/ios-agent-skill/main/install.sh | bash

---

:robot: Works With Every AI Coding Agent

:largebluediamond: Claude Code

git clone https://github.com/Nagarjuna2997/ios-agent-skill.git && cd ios-agent-skill && claude

Auto-reads CLAUDE.md

:green_circle: OpenAI Codex CLI

git clone https://github.com/Nagarjuna2997/ios-agent-skill.git ~/.codex/skills/ios-agent-skill

Auto-reads AGENTS.md

:largebluecircle: Gemini CLI / Antigravity

git clone https://github.com/Nagarjuna2997/ios-agent-skill.git && cd ios-agent-skill

Auto-reads GEMINI.md and AGENTS.md

:purple_circle: Cursor

cp ios-agent-skill/.cursorrules /path/to/your/project/
# Or use modern format:
cp -r ios-agent-skill/.cursor /path/to/your/project/

Auto-reads .cursor/rules/ios-skill.md or .cursorrules

:octocat: GitHub Copilot

Auto-reads .github/copilot-instructions.md when repo is cloned.

:ocean: Windsurf (Codeium)

Auto-reads .windsurf/rules/ios-skill.md or .windsurfrules

:brain: JetBrains AI / Junie

Auto-reads .aiassistant/rules/ios-skill.md or .junie/guidelines.md

:globewithmeridians: 15+ More Platforms

| Platform | File | Auto-detected | |----------|------|:---:| | Zed AI | .rules | :whitecheckmark: | | Trae (ByteDance) | .trae/rules/ios-skill.md | :whitecheckmark: | | Amazon Q Developer | .amazonq/rules/ios-skill.md | :whitecheckmark: | | Cline | .clinerules | :whitecheckmark: | | Roo Code | .roo/rules/ios-skill.md | :whitecheckmark: | | KiloCode | .kilocode/rules/ios-skill.md | :whitecheckmark: | | Continue.dev / PearAI | .continue/rules/ios-skill.md | :whitecheckmark: | | Augment Code | .augment/rules/ios-skill.md | :whitecheckmark: | | Tabnine | .tabnine/guidelines/ios-skill.md | :whitecheckmark: | | Aider | CONVENTIONS.md | :whitecheckmark: | | Sourcegraph Amp | AGENTS.md | :whitecheckmark: | | Replit Agent | replit.md | :whitecheckmark: | | Lovable | AGENTS.md | :whitecheckmark: | | OpenCode / OpenHands | AGENTS.md | :whitecheckmark: | | Bolt.new | CLAUDE.md | :whitecheckmark: |

---

:electric_plug: MCP Server — analyze your Swift project

Beyond teaching agents how to write iOS code, this repo ships an MCP server that lets them check it.

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

> You: Review my Swift project for concurrency problems. > > 🔴 Sources/FeedModel.swift:3 — @Observable type is not @MainActor-isolated. > Why it matters: @Observable grants no isolation. SwiftUI reads this state during layout while any task may write it — a data race under Swift 5 mode, a compile error under Swift 6. > Fix: Annotate the type: @MainActor @Observable final class …

| Tool | Finds | |------|-------| | analyze_swift_project | Structure, plus finding counts per category. Start here. | | review_swift_concurrency | @Observable without @MainActor, Task.detached, @unchecked Sendable, empty catch, a type named Task | | review_swift_architecture | Live-implementation defaults, presentation naming URLSession/APIClient, singletons in view models, domain importing SwiftUI | | review_swiftui | Fixed font sizes, AnyView, literal spacing, @EnvironmentObject, try! | | check_availability_guards | Missing and over-restrictive guards — an iOS 26 API guarded at iOS 27 silently drops every iOS 26 device | | audit_app_store_readiness | Missing purpose strings, privacy manifest, unlabeled icon buttons |

Setup for Claude Desktop and Cursor: [docs/mcp/installation.md](docs/mcp/installation.md) · Tool reference: [docs/mcp/tools.md](docs/mcp/tools.md) · Worked sessions: [docs/mcp/examples.md](docs/mcp/examples.md)

---

:gear: Supported Platforms

Write against: Swift 6.4 · Xcode 27 · iOS 27 SDK — deploy to: iOS 17–27

| | | |---|---| | Swift | 6.4+ (minimum 5.9) | | Xcode | 27+ | | iOS / iPadOS | 17 – 27 | | macOS | 14 – 27 | | watchOS / tvOS | 10 – 27 | | visionOS | 2+ |

Full per-feature floors, framework minimums, and toolchain support: [docs/compatibility-matrix.md](docs/compatibility-matrix.md).

> Guard on the version where an API was introduced, not the newest SDK. Liquid Glass and the Foundation Models baseline are iOS 26+; Private Cloud Compute, Dynamic Profiles, and image attachments are iOS 27+. Writing #available(iOS 27, *) around an iOS 26 API silently drops every iOS 26 device to your fallback.

Everything above the iOS 17 floor is additive — a newer-OS feature must degrade to a working path, never disappear.

---

:sparkles: What's New in 2.0

The repo is now installable, not just readable.

| | Feature | What it gives you | |:---:|---------|-------------------| | :electricplug: | [MCP server](mcp-server/) | Six Swift analysis tools usable from Claude Code, Claude Desktop, and Cursor. npx -y ios-agent-mcp | | :whitecheck_mark: | 38 tests, incl. real protocol round-trips | Unit tests for the analyzers, plus a smoke test that launches the server and speaks MCP over stdio | | :books: | [MCP docs](docs/mcp/) | Installation, full tool and rule reference, worked sessions |

The analysis engine is the same rule set as templates/hooks/forbid-antipatterns.sh — this productizes it rather than reinventing it.

---

:sparkles: What's New in 1.4

Adoption and maintenance. The repo now proves its own patterns compile.

| | Feature | What it gives you | |:---:|---------|-------------------| | :whitecheckmark: | [Compile-checked sample](samples/SkillPatterns/) | An SPM package implementing the skill's core patterns, built and tested in CI on every push — the patterns are now VERIFIED, not INSPECTED | | :bookmarktabs: | [Compatibility matrix](docs/compatibility-matrix.md) | One canonical table: deployment targets, SDKs, tested toolchains, per-feature availability floors | | :arrowup: | [Migration guides](docs/migration/) | Swift 5.9→6→6.4 organized by the compiler errors you actually hit; iOS 17→26→27; Xcode 15→16→27 | | :mag: | Expanded CI | Markdown links, backtick path references, code-fence languages, frontmatter consistency — repo-wide, not just SKILL.md |

---

:sparkles: What's New in 1.3

Apple Intelligence and the iOS 27 toolchain.

| | Feature | What it gives you | |:---:|---------|-------------------| | :brain: | [Foundation Models](docs/frameworks/foundation-models.md) | On-device + Private Cloud Compute LLMs, @Generable/@Guide structured output, tool calling, Dynamic Profiles, multimodal prompts, custom LanguageModel providers | | :sparkles: | [Apple Intelligence](docs/frameworks/apple-intelligence.md) | Which framework to reach for, the privacy model and what you may claim, App Intents, Image Playground, features that degrade | | :hammerandwrench: | [Xcode 27 agents](docs/tooling/xcode-27-agents.md) | Coding agents vs. Claude Code, agent-assisted localization and testing, the Swift Concurrency instrument | | :iphone: | [Device Hub](docs/tooling/device-hub.md) | The device/config test matrix, iOS 27 app resizability, accessibility passes | | :ocean: | Swift 6.4 | weak let, ~Sendable, @diagnose, async in defer, unhandled-task-error warnings, plus an actor isolation review checklist | | :bustsinsilhouette: | 4 new subagents | foundation-models, swiftui-modernization, accessibility-reviewer, performance-reviewer — 10 total |

---

:sparkles: What's New in 1.2

The agent-operations layer. Earlier versions taught the model what to write. This release adds how it should work — how to split a job, verify it, and scale it out.

| | Feature | What it gives you | |:---:|---------|-------------------| | :bustsinsilhouette: | 6 custom subagents in [.claude/agents/](.claude/agents/) | ios-explore, ios-plan, swift-reviewer, swift-debugger, swift-refactorer, ios-docs — each with its own fresh context and a restricted tool set | | :receipt: | The verification evidence rule | Agents must show command output, test results, or file:line citations. Every claim is labelled VERIFIED / INSPECTED / UNVERIFIED — no more "it should work now" | | :repeat: | Loop contracts | Every loop declares GOAL, CHECK, MAX, and ON-STALL. Turn-based, goal-based, time-based, and proactive patterns, with stall detection | | :chartwithupwards_trend: | A scale-up path | Inline → subagents → loop → /batch (worktree per unit) → script-driven dynamic workflows | | :lock: | Hooks for deterministic enforcement | This repo blocks edits to generated files and auto-syncs mirrors. [`templates

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Nagarjuna2997
• Source: Nagarjuna2997/ios-agent-skill
• License: MIT
• Homepage: https://github.com/Nagarjuna2997/ios-agent-skill

Install and usage instructions live in the source repository linked above.