Documentation
Installation
Install ACT-iOS into your existing iOS project in two steps.
# Clone or download the toolkit
git clone https://github.com/yourusername/act-ios.git
# Install into your project
cd act-ios
./install.sh /path/to/your/ios-project
This copies the .claude/ directory (skills, agents, rules) into your project. It does not modify any of your source code.
What gets installed
45 skills, 3 research agents, 12 knowledge base files, and artifact directories (ai_specs/, ai_docs/).
Your First Command
Open Claude Code in your project and try the knowledge base:
cd /path/to/your/ios-project
claude
# Inside Claude Code:
/ios-development principles
This displays the 12 iOS development principles. Try /ios-development patterns or /ios-development mvvm to explore more.
Full Workflow
The standard development cycle follows six commands in sequence:
/act:spec feature-nameCreate a detailed feature specification. The codebase-researcher agent analyzes your project and asks clarifying questions.
/act:refine-specAdversarial review of the spec. Finds gaps, impossible states, missing error handling, and architecture violations.
/act:planGenerate a phased implementation plan with file creation order, dependencies, and test strategy.
/act:workExecute the plan phase-by-phase. Runs swift build after each phase, creates conventional commits.
/act:reviewCode review against the knowledge base. Checks architecture compliance, SwiftUI patterns, accessibility, concurrency.
/act:compoundCapture reusable insights from the session for future sessions.
Requirements
- ✓ Claude Code CLI or OpenCode CLI
- ✓ An LLM subscription or API key
- ✓ An existing iOS/Swift project (or use /ios-create)
- ✓ Xcode 15+ / Swift 5.9+
Workflow Skills
The core development lifecycle commands that orchestrate spec-driven development.
| Command | Description |
|---|---|
| /act:spec | Create detailed feature specifications with codebase analysis |
| /act:refine-spec | Adversarial review for gaps, impossible states, and anti-patterns |
| /act:plan | Generate phased implementation plan with dependencies and test strategy |
| /act:work | Execute the plan phase-by-phase with builds and conventional commits |
| /act:review | Code review against knowledge base for architecture and pattern compliance |
| /act:compound | Capture reusable insights and learnings from the current session |
Git Skills
Version control automation with conventional commits and pull request workflows.
| Command | Description |
|---|---|
| /act:commit | Create conventional commits (feat/fix/refactor) with scope and description |
| /act:push-make-pr | Push branch and create a GitHub pull request with structured description |
| /act:git-worktree | Set up git worktrees for parallel feature development |
iOS Skills
Project setup, testing, data persistence, third-party integrations, and platform capabilities.
| Command | Description |
|---|---|
| /ios-create | Scaffold a new iOS project with architecture, CI, and testing pre-configured |
| /ios-development | Access the knowledge base: principles, patterns, architecture guides |
| /ios-swift-testing | Generate Swift Testing tests with @Test, #expect, and parameterized traits |
| /ios-ui-testing | Generate UI tests with XCUITest, accessibility identifiers, and page objects |
| /ios-tdd | Test-driven development flow: write failing test, implement, refactor |
| /ios-swiftui-preview | Generate Xcode previews with mock data, dark mode, and device variants |
| /ios-swiftdata-setup | Configure SwiftData models, containers, and migration plans |
| /ios-coredata-migration | Generate Core Data migration mappings (lightweight and custom) |
| /ios-firebase-setup | Integrate Firebase (Auth, Firestore, Crashlytics, Analytics) |
| /ios-sentry-setup | Integrate Sentry error tracking with breadcrumbs and performance monitoring |
| /ios-storekit2-setup | Configure StoreKit 2 subscriptions, products, and receipt validation |
| /ios-tca-setup | Set up The Composable Architecture with reducers, store, and dependencies |
| /ios-accessibility | Audit and fix VoiceOver, Dynamic Type, and color contrast issues |
| /ios-localization | Set up String Catalogs, pluralization rules, and locale testing |
| /ios-spm-upgrade | Upgrade Swift Package Manager dependencies with compatibility checks |
| /ios-screenshot | Generate App Store screenshot automation with fastlane/snapshot |
Component Generator Skills
Production-ready SwiftUI components with design tokens, previews, accessibility, and tests.
| Command | Description |
|---|---|
| /ios-component-textfield | Styled text field with validation, error states, and floating label |
| /ios-component-button | Button system with primary/secondary/destructive variants and loading state |
| /ios-component-bottomsheet | Draggable bottom sheet with detents, snap points, and keyboard avoidance |
| /ios-component-dropdown | Dropdown selector with search, multi-select, and custom styling |
| /ios-component-card | Content card with image, title, subtitle, and action buttons |
| /ios-component-alert | Custom alert dialog with configurable actions and destructive styling |
| /ios-component-list | List with swipe actions, sections, pull-to-refresh, and pagination |
| /ios-component-form | Form builder with validation, sections, and field types (text, toggle, picker) |
| /ios-component-empty-state | Empty state view with illustration placeholder, message, and CTA button |
| /ios-component-loading | Loading indicators: skeleton views, progress bars, and shimmer effects |
| /ios-router | Type-safe navigation router with deep linking and NavigationStack |
Infrastructure & Platform Skills
Networking layers, security hardening, CI/CD pipelines, and platform integrations.
| Command | Description |
|---|---|
| /ios-network | Generate async/await networking layer with interceptors, retry logic, and caching |
| /ios-security | Keychain wrapper, certificate pinning, biometric auth, and data encryption |
| /ios-ci | GitHub Actions CI/CD pipeline with build, test, lint, and TestFlight deployment |
| /ios-widget | WidgetKit extension with timeline provider, multiple families, and intents |
| /ios-appstore | App Store metadata, screenshots config, review notes, and submission checklist |
| /ios-deeplink | Universal links and custom URL schemes with route parsing and handling |
Advanced Skills
Analytics integration, modularization, and migration tools for mature codebases.
| Command | Description |
|---|---|
| /ios-analytics | Analytics abstraction layer with provider-agnostic event tracking and consent management |
| /ios-modularize | Extract features into Swift packages with dependency graphs and interface modules |
| /ios-migrate | Migrate between architectures (UIKit to SwiftUI, ObservableObject to @Observable, etc.) |
| /ios-performance | Profile and optimize: Instruments automation, memory leak detection, launch time analysis |
MVVM Architecture
Model-View-ViewModel — the natural fit for SwiftUI with @Observable.
Features/
UserProfile/
Views/UserProfileView.swift
ViewModels/UserProfileViewModel.swift
Models/UserProfile.swift
Run /ios-development mvvm in Claude Code for the full guide with code examples.
TCA (The Composable Architecture)
Unidirectional data flow with composable reducers and exhaustive testing.
Features/
ItemList/
ItemListFeature.swift // @Reducer
ItemListView.swift
Run /ios-development tca for the full guide.
Clean Architecture
Layered architecture with strict dependency rules: inner layers never depend on outer layers.
Domain/ // Entities, UseCases, Repository protocols
Data/ // Implementations, DataSources, DTOs
Presentation/ // Views, ViewModels, Navigation
Run /ios-development clean for the full guide.
VIPER
Module-based architecture with strict single-responsibility per component.
Modules/Home/
HomeView.swift
HomeInteractor.swift
HomePresenter.swift
HomeRouter.swift
HomeBuilder.swift
Run /ios-development viper for the full guide.
Troubleshooting
"Unknown skill" error
The skills aren't installed in your project. Re-run the installer:
./install.sh /path/to/your/project
Duplicate skills in autocomplete
Claude Code loads .claude/ from parent directories too. If your project is inside the toolkit repo, skills appear twice. Move your project outside, or delete the nested .claude/ copy.
Skills don't appear after install
Exit Claude Code and reopen it. Skills are loaded at startup.
Swift build fails after code generation
Check that your deployment target matches the generated code. ACT-iOS targets iOS 17+ by default. For iOS 16, some patterns (like @Observable) need to be replaced with ObservableObject.
FAQ
See the FAQ on the home page.
Changelog
v1.0.0 — March 2026
- Initial release with 45 skills, 3 research agents, 12 knowledge base files
- 6-command workflow: spec, refine, plan, work, review, compound
- 11 component generators with design token system
- 4 architecture guides: MVVM, TCA, Clean, VIPER
- Networking, security, CI/CD, widget, and App Store skills