Production-ready architectural patterns and implementation skills for building modern iOS apps with Swift, SwiftUI, and Tuist — designed as context for AI coding agents.

Created and maintained by Alp Özcan.

AI coding agents are powerful, but they lack the opinionated, battle-tested architectural knowledge that comes from shipping real iOS apps. They'll happily generate a ViewController with 2,000 lines, wire up Singletons everywhere, and skip actor isolation entirely.

iOS Agent Skills is a collection of 25 self-contained skill documents that teach AI agents (and developers) how to build modular, testable, privacy-first iOS applications using modern Swift patterns. Each skill encodes a specific architectural decision — the kind of thing a senior iOS engineer carries in their head but rarely writes down.

These skills were extracted from building a production iOS app with 10+ Tuist modules, on-device LLM integration (Apple Foundation Models), StoreKit 2 subscriptions, EventKit–CoreData sync, and a fully custom SwiftUI design system. They represent real patterns that survived contact with real users.

25 skills organized across 5 categories, covering everything from build system configuration to on-device AI safety guardrails.

The structural backbone of a modular iOS app. These skills define how code is organized, how dependencies flow, how services communicate safely across threads, how errors propagate with full type safety, and how all workflows are orchestrated through a single entry point.

Design system infrastructure, custom navigation, and multi-language support for SwiftUI apps that feel premium.

Quality assurance patterns that keep modular apps reliable across CI, simulators, and Xcode Previews.

Patterns for integrating Apple system frameworks (StoreKit, EventKit, WidgetKit, UNUserNotificationCenter) into modular apps, plus App Store publishing and direct distribution pipelines.

On-device AI architecture for privacy-first, zero-latency inference.

These skills form a skill graph — a network of interconnected markdown files where [[wikilinks]] carry meaning in prose. Instead of 25 isolated documents, you get a traversable knowledge structure where each skill links to the ones it depends on, enables, or complements.

Entry point: skills/index.md — scan the landscape, then follow links into the areas that matter for your task.

• YAML frontmatter on every skill file — scan title and description without reading the full content
• Wikilinks in prose — [[skill-name]] links woven into sentences tell the agent when and why to follow them
• Maps of Content (MOCs) — each category README organizes its skills into a navigable sub-topic with cross-category connections
• Progressive disclosure — index → MOC descriptions → wikilinks → sections → full content. Most decisions happen before reading a single full file

Point your agent at the graph index and let it traverse:

# Start from the graph entry point — agent follows relevant links
@skills/index.md

# Load a category MOC for focused context
@skills/architecture/README.md

# Load a specific skill with its cross-references
@skills/architecture/01-tuist-modular-architecture.md

The agent reads the index, scans frontmatter descriptions, follows wikilinks that matter for the current task, and skips what doesn't. This is the difference between injecting a document and giving the agent a knowledge structure to navigate.

Each skill is still self-contained — it provides enough context to implement the pattern correctly without reading other skills:

# Load all architecture skills as flat context
@skills/architecture/

# Load everything
@skills/

Browse the categories above and jump to whichever skill matches your current implementation challenge. The skills are numbered for reference but can be read in any order.

Fork this repo and add skills specific to your project's domain. The CONTRIBUTING.md guide explains the file naming convention, template structure, and quality checklist.

Every skill follows the same structure for consistency:

---
title: "Skill Title"
description: "1-2 sentence summary scannable without reading the file"
---

# Title

## Context
When and why you need this pattern. What problem does it solve?

## Pattern
The concrete implementation with Swift code.
Broken into layers/steps with ### subheadings.
[[wikilinks]] to related skills woven into prose.

## Edge Cases
Boundary conditions, race conditions, and failure modes.

## Why This Matters
Why this pattern exists and what it prevents.

## Anti-Patterns
Common mistakes and what to avoid.

The YAML frontmatter lets agents scan descriptions without reading full files. The Context helps decide whether to apply the skill, the Pattern provides how with [[wikilinks]] pointing to related skills, the Edge Cases document boundary conditions and failure modes, and the Anti-Patterns prevent common mistakes.

These skills assume the following technology stack:

iOSAgentSkills/
├── README.md                              ← You are here
├── CONTRIBUTING.md                        ← How to add new skills
├── LICENSE                                ← MIT License
│
└── skills/
    ├── index.md                           ← Skill graph entry point
    ├── architecture/                      ← 7 skills
    │   ├── README.md
    │   ├── 01-tuist-modular-architecture.md
    │   ├── 02-protocol-driven-service-catalog.md
    │   ├── 03-ui-composer-pattern-for-feature-modules.md
    │   ├── 06-actor-based-concurrency-patterns.md
    │   ├── 14-error-handling-and-typed-error-system.md
    │   ├── 18-makefile-for-ios-project-workflows.md
    │   └── 24-swiftdata-and-observation-framework-patterns.md
    │
    ├── ui/                                ← 5 skills
    │   ├── README.md
    │   ├── 04-design-system-as-core-module.md
    │   ├── 13-swiftui-custom-tab-bar-and-navigation.md
    │   ├── 16-localization-and-multi-language-patterns.md
    │   ├── 17-safe-area-inset-stacking-and-bottom-pinned-views.md
    │   └── 21-accessibility-voiceover-dynamic-type-patterns.md
    │
    ├── testing-and-debugging/             ← 6 skills
    │   ├── README.md
    │   ├── 05-swift-testing-and-tdd-patterns.md
    │   ├── 09-debug-modes-and-mock-service-strategy.md
    │   ├── 17-snapshot-testing-with-swift-snapshot-testing.md
    │   ├── 18-ui-testing-regression-and-smoke.md
    │   ├── 25-performance-monitoring-and-profiling-patterns.md
    │   └── 26-structured-logging-and-log-levels.md
    │
    ├── platform-frameworks/               ← 8 skills
    │   ├── README.md
    │   ├── 07-storekit2-intelligence-based-trial.md
    │   ├── 10-privacy-first-analytics-architecture.md
    │   ├── 11-notification-service-with-deep-linking.md
    │   ├── 12-eventkit-coredata-sync-architecture.md
    │   ├── 15-widgetkit-and-app-intents-integration.md
    │   ├── 20-fastlane-app-store-connect-publishing.md
    │   ├── 22-github-actions-ci-cd-for-ios.md
    │   └── 23-app-clips-and-shared-extensions-modular-architecture.md
    │
    └── ai-and-intelligence/               ← 1 skill
        ├── README.md
        └── 08-on-device-llm-with-apple-foundation-models.md

Contributions are welcome! Whether it's a new skill, a correction to an existing one, or an improvement to the project structure.

See CONTRIBUTING.md for the full guide — including the skill template, naming convention, category descriptions, and quality checklist.

Quick start:

1. Fork the repo
2. Create your skill: skills/<category>/XX-descriptive-name.md
3. Follow the Context → Pattern → Anti-Patterns structure
4. Add it to the relevant table in this README
5. Open a pull request

This project is licensed under the MIT License — see the LICENSE file for details.

Built with care by @alpozcan