Swift Architecture Skill

Architecture guidance for AI coding tools — because LLMs default to MVVM for everything. This skill routes to the right pattern for your feature, keeps guidance scoped to your task, and gives you concrete code, anti-pattern fixes, and a PR checklist.

Supports the Agent Skills open format.

Features

• Routes to the right architecture: Describe your feature and the skill selects the best fit based on UI stack, state complexity, and existing conventions. Name a pattern yourself and it validates the fit before you commit.
• Scoped playbooks: Each architecture has its own reference — code patterns, anti-pattern fixes, testing strategy, and a PR checklist. Guidance never bleeds across patterns.
• Reference index: A dedicated _index.md gives agents a fast navigation hub and problem router before diving into a playbook.
• SwiftUI and UIKit: Every playbook covers both stacks with modern async/await and actor-based concurrency patterns throughout.
• Snippet validation: CI parses Swift fences across the playbooks so examples stay syntactically healthy as guidance evolves.

Supported Architectures

MVP · MVVM · MVI · TCA · Clean Architecture · VIPER · Coordinator · Reactive

Each has a dedicated playbook with overview, patterns, anti-pattern fixes, testing strategy, and PR checklist. Start with the reference index for quick routing, or use the selection guide when the architecture is still undecided.

Installation

skills.sh (recommended)

Works with any tool that supports the Agent Skills format:

npx skills add https://github.com/efremidze/swift-architecture-skill --skill swift-architecture-skill

Claude Code plugin

Install from the marketplace for personal use:

/plugin marketplace add efremidze/swift-architecture-skill
/plugin install swift-architecture-skill@swift-architecture-skill

Or enable it for an entire project by committing this to .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "swift-architecture-skill": {
      "source": {
        "source": "github",
        "repo": "efremidze/swift-architecture-skill"
      }
    }
  },
  "enabledPlugins": {
    "swift-architecture-skill@swift-architecture-skill": true
  }
}

Manual install

Clone the repo and copy the skill into your skills directory — ~/.claude/skills/ for personal use, or a project's .claude/skills/:

git clone https://github.com/efremidze/swift-architecture-skill.git
mkdir -p ~/.claude/skills  # or .claude/skills for a project
cp -r swift-architecture-skill/swift-architecture-skill ~/.claude/skills/swift-architecture-skill

Usage

Once installed, ask your agent:

Use swift-architecture-skill to recommend and scaffold architecture for this feature.

Example Prompts

I'm building a SwiftUI feed with pagination, pull-to-refresh, and live updates.
Which architecture should I use and why?

We're planning to use TCA for a simple settings screen with two toggles.
Is that the right call, or is it overkill for this feature?

This module started as MVVM but the ViewModel is doing too much — routing,
formatting, and business logic. Use swift-architecture-skill to refactor it
toward Clean Architecture and show me the layer boundaries.

We have a UIKit + MVP module we're migrating to SwiftUI. Should we keep MVP
or switch patterns during the migration, and how do we handle the transition
period where both coexist?

Skill Structure

swift-architecture-skill/
  SKILL.md                       # Routing logic and output requirements
  references/
    _index.md                    # Navigation hub and problem router
    selection-guide.md           # Decision framework across architectures
    mvp.md                       # MVP playbook
    mvvm.md                      # MVVM playbook
    mvi.md                       # MVI playbook
    tca.md                       # TCA playbook
    clean-architecture.md        # Clean Architecture playbook
    viper.md                     # VIPER playbook
    coordinator.md               # Coordinator playbook
    reactive.md                  # Reactive (Combine/RxSwift) playbook

Contributing

Contributions are welcome. A few things to keep in mind:

• Respect the token budget. SKILL.md is loaded on every invocation — keep additions concise.
• Don't repeat what LLMs already know. Focus on edge cases, common mistakes, and pattern-specific traps that models get wrong.
• One playbook per pattern. Keep guidance scoped; don't let patterns bleed into each other.

See CONTRIBUTING.md for full structure and quality requirements.

Related

• swift-patterns-skill

License

MIT. See LICENSE for details.