ios-agent-skill

An Agent Skill for production-oriented iOS, Swift, and SwiftUI development.
Helps AI coding assistants generate safer Swift code, follow modern Apple APIs, and work inside existing Xcode projects.

---

Adoption and Community Usage

This repository tracks public adoption evidence in 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.

📖 Complete AI Setup Guide (Mac + Windows) for ALL 28 Tools

---

⚠️ 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)
5. Click Next → Choose a folder → Click Create
6. 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.

---

⚡ One-Line Install

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

---

🤖 Works With Every AI Coding Agent

🔷 Claude Code

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

Auto-reads CLAUDE.md

🟢 OpenAI Codex CLI

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

Auto-reads AGENTS.md

🔵 Gemini CLI / Antigravity

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

Auto-reads GEMINI.md and AGENTS.md

🟣 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

GitHub Copilot

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

🌊 Windsurf (Codeium)

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

🧠 JetBrains AI / Junie

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

🌐 15+ More Platforms

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

---

🧠 What's Inside

⚙️ The Skill Brain

CLAUDE.md / SKILL.md / AGENTS.md / GEMINI.md — all identical

• ✅ Zero-error Swift code generation rules
• ✅ Framework selection guide (SwiftUI vs UIKit, SwiftData vs CoreData)
• ✅ MVVM project structure with naming conventions
• ✅ Platform-specific guidance (iOS, macOS, watchOS, tvOS, visionOS)
• ✅ UI design standards (colors, typography, spacing, animations)
• ✅ Top 10 pitfalls and how to avoid them

---

📚 Documentation Reference

📙 Swift Language — docs/swift/

	File	Topics
🔤	swift-language.md	Types, protocols, generics, property wrappers, result builders, macros, pattern matching
🔄	swift-concurrency.md	async/await, Task, actors, @MainActor, Sendable, AsyncSequence, continuations
📦	swift-standard-library.md	Collections, String, Codable, Result, Regex, Clock/Duration

🎨 SwiftUI — docs/swiftui/

	File	Topics
🧩	views-and-controls.md	Text, Image, Button, List, ScrollView, Form, Menu, ViewModifier, lifecycle
💾	state-and-data-flow.md	@State, @Binding, @Observable, @Environment, @Query
🧭	navigation.md	NavigationStack, sheets, TabView, deep linking, iOS 18 zoom transitions
📐	layout.md	Stacks, Grid, GeometryReader, LazyVGrid, custom Layout protocol
✨	animations.md	Spring, transitions, matchedGeometry, PhaseAnimator, MeshGradient, TextRenderer
👆	gestures.md	Tap, drag, magnify, rotate, gesture composition

📱 UIKit — docs/uikit/

	File	Topics
🏗️	uikit-essentials.md	UIViewController, Auto Layout, diffable data sources, compositional layout
🌉	uikit-swiftui-interop.md	UIViewRepresentable, UIHostingController, Coordinator pattern
🎥	animations.md	UIViewPropertyAnimator, custom VC transitions, Core Animation, CAShapeLayer

🌈 Design System — docs/design/

	File	Topics
🎨	color-system.md	5 color palettes, hex codes, 10 gradient recipes, materials, dark mode
🔠	typography-system.md	Text styles, SF Symbols, Dynamic Type, gradient/animated text effects
🌟	stunning-ui-patterns.md	20+ UI patterns: glassmorphism, neumorphism, parallax, shimmer, card stacks
🕹️	interaction-standards.md	Animation curves, haptics, button styles, states, localization, privacy manifest
✏️	fonts-catalog.md	Every iOS font, 100+ Google Fonts, 15 pairings, variable fonts, international
🎬	third-party-animations.md	Lottie integration, Rive state machines, decision table

🔧 Drop-In Components — templates/common-patterns/

	File	Includes
🖌️	design-system.swift	5 themes, spacing/radius/shadow tokens, 6 ButtonStyles, ViewState, AnimationStandard
🧱	ui-components.swift	GradientButton, GlassCard, AvatarView, StatCard, RatingView, CircularProgress, ToastView, SearchBar + 9 more

⚙️ Apple Frameworks — docs/frameworks/

	File	Framework
🌐	foundation.md	URLSession, FileManager, Codable, NotificationCenter
🌊	combine.md	Publishers, operators, error handling
💾	core-data.md	NSManagedObject, fetch requests, migration
❇️	swiftdata.md	@Model, @Query, #Predicate, History API, custom DataStore
📡	networking.md	API client, auth tokens, WebSocket
📍	core-location.md	GPS, geofencing, iBeacon
🗺️	mapkit.md	Map views, annotations, directions, LookAround
📽️	avfoundation.md	Audio/video playback, camera capture
💳	storekit.md	In-app purchases, subscriptions, EU marketplace
☁️	cloudkit.md	iCloud sync, CKSyncEngine, sharing
🔔	usernotifications.md	Local/remote notifications, actions
🗂️	widgetkit.md	Widgets, Live Activities, Control Center
♿	accessibility.md	VoiceOver, Dynamic Type, contrast
📱	arkit.md	World/face/body/image/object/geo tracking, mesh, anchors
👓	realitykit.md	ECS, RealityView, ARView, PBR materials, physics, USDZ

🤖 AI & Machine Learning — docs/frameworks/ml/

	File	Framework
🧠	coreml.md	Model loading, prediction, Neural Engine
👁️	vision.md	OCR, face detection, barcode, segmentation
💬	natural-language.md	Tokenization, sentiment, embeddings
🎤	speech.md	Speech-to-text, live transcription
🔮	on-device-ai.md	Foundation Models, MLX Swift, on-device LLM

🚀 Advanced App Experience

	File	Framework
🟢	activitykit.md	Live Activities, Dynamic Island
🙌	app-intents.md	Siri, Shortcuts, Spotlight, Apple Intelligence
💡	tipkit.md	Feature discovery tooltips
✂️	app-clips.md	App Clips, NFC/QR triggers
📷	photosui.md	PhotosPicker, custom camera, PiP

🔌 Hardware — docs/frameworks/hardware/

	File	Framework
📶	core-bluetooth.md	BLE scanning, connecting
❤️	healthkit.md	Health data, workouts
🏃	core-motion.md	Accelerometer, pedometer
📳	core-nfc.md	NFC tag reading/writing
🏠	homekit.md	Home automation, Matter

💼 Services — docs/frameworks/services/

	File	Framework
💰	passkit.md	Apple Pay, Wallet passes
⛅	weatherkit.md	Weather forecasts, alerts
📆	eventkit.md	Calendar, reminders
👥	contacts.md	Contact access, picker

🛡️ Security & Engineering

	File	Framework
🔒	cryptokit.md	SHA256, AES-GCM, Secure Enclave
🔍	oslog.md	Logger, MetricKit diagnostics
⏳	background-tasks.md	BGTaskScheduler
✅	device-integrity.md	DeviceCheck, AppAttest

🌎 Platform Guides — docs/platforms/

	File	Platform
📱	ios.md	iOS — lifecycle, deep linking, extensions
💻	macos.md	macOS — menu bar, toolbar, sandboxing
⌚	watchos.md	watchOS — complications, workouts
📺	tvos.md	tvOS — focus engine, Siri Remote
👓	visionos.md	visionOS — spatial computing, RealityKit

---

🏗️ Code Templates

📱 iOS App Template

templates/ios-app/
 |- App.swift              # @main with SwiftData
 |- ContentView.swift      # TabView (Home, Profile, Settings)
 |- Models/Item.swift      # Data model
 |- Views/                 # HomeView, ProfileView, SettingsView
 |- ViewModels/            # @Observable view models
 |- Tests/                 # Swift Testing + XCTest examples
 |- Info.plist

🌐 Multiplatform Template

templates/multiplatform-app/
 |- Shared/                # NavigationSplitView, shared logic
 |- iOS/                   # iOS-specific (haptics, etc.)
 |- macOS/                 # Menu commands, window styling
 |- watchOS/               # Compact layouts

🧰 Common Patterns

	File	What It Does
📡	networking-layer.swift	Actor-based API client, auth tokens
💾	persistence-layer.swift	SwiftData setup, @Query, previews
🔑	auth-flow.swift	AuthManager, Keychain, Sign in with Apple
🧭	navigation-router.swift	Type-safe router, deep linking
💉	dependency-injection.swift	Protocol-based DI, Environment

---

🏛️ Architecture Patterns

	Pattern	Guide
🔄	MVVM	@Observable, DI, testing
🧱	Clean Architecture	Domain/Data/Presentation layers
🧭	Coordinator	NavigationPath, deep linking
🗄️	Repository	Offline-first, caching
⚠️	Error Handling	Custom errors, retry, circuit breaker
⚛️	TCA	Composable Architecture, TestStore

---

🚀 CI/CD Templates

	File	What It Does
	github-actions.yml	Build, test, TestFlight deploy, SPM cache
💎	Fastfile	Test, beta, release lanes, match signing

---

📋 Quality Checklists

	Checklist	When to Use
🍎	App Store Submission	Before submitting — metadata, privacy, entitlements
🏎️	Performance	Instruments, SwiftUI perf, image optimization
🛡️	Security	Keychain, pinning, biometrics, encryption
🧪	Testing	XCTest, Swift Testing, UI tests, CI/CD

---

📊 Tech Stack

	Category	Technology	Version
🔤	Language	Swift 5.9+	Xcode 15+
🎨	UI (primary)	SwiftUI	iOS 15+
📱	UI (interop)	UIKit / AppKit	iOS 13+
💾	Persistence	SwiftData	iOS 17+
🔄	Concurrency	async/await, actors	iOS 15+
👀	State	@Observable	iOS 17+
🏗️	Architecture	MVVM / TCA	All
👓	Spatial	RealityKit + ARKit	visionOS 1.0+
🧠	AI/ML	CoreML + Vision	iOS 15+

---

💬 Example Prompts

	What You Want	What to Ask
📱	New app	"Create a SwiftUI habit tracker with SwiftData persistence"
🔔	Push notifications	"Add local and remote notification support"
🐛	Fix a bug	"My NavigationStack isn't preserving state on back"
📡	Networking	"Create a REST API client that fetches user data"
👓	visionOS	"Build a visionOS app with 3D models in immersive space"
⌚	watchOS	"Add a watchOS companion that syncs with iPhone"
🗂️	Widget	"Create a home screen widget showing today's tasks"
💳	In-app purchase	"Add a subscription paywall with StoreKit 2"
🌟	Stunning UI	"Build onboarding with gradient glass cards and animations"
🎨	Design system	"Apply Ocean Blue theme across the entire app"
📊	Dashboard	"Add stat cards with circular progress and animated counters"
🧠	ML feature	"Add on-device text recognition with Vision framework"
❤️	Health app	"Read step count data from HealthKit and display weekly chart"

---

🤝 Contributing

1. 🍴 Fork this repository
2. ✏️ Add or update documentation in docs/
3. 🛠️ Add new templates or patterns
4. ⤴️ Submit a pull request

---

📜 License

MIT License | Copyright (c) 2026 Nagarjuna Reddy

---

95+ files | 50,000+ lines | 25+ AI platforms | All Apple frameworks