agentsclimarketplace

Swiftpm modularization

Skill wei18/apple-dev-skills/apple-dev-skills/skills/swiftpm-modularization

Default modularization shape for Apple-platform Swift Apps — single Swift Package, multi-target, thin App target, DI composition root, restricted Apple framework imports, one test target per production target. Invoke when starting a new project, writing Package.swift, deciding how to split modules, planning portability (e.g. Swift on Android), or when asked "single package or multi-package, how should I split modules".From its SKILL.md

Install
npx -y skills add wei18/apple-dev-skills --skill swiftpm-modularization

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 18 stars18 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

5.4 KB, ~1.1k tokens by cl100k_base, as published. Nobody here has run it

SwiftPM Modularization

When to invoke

  • Starting a new Swift App project and deciding how to split modules.
  • Writing the first version of Package.swift.
  • Wanting to reserve the option of shipping core logic to Android / cross-platform later.
  • Introducing CloudKit / GameKit / StoreKit and deciding the import scope.
  • User asks "single Package or multiple", "should the App target be thin", "how do I wire DI".

Default decisions

Single Package + multiple targets

  • Put all modules in one Swift Package, splitting by target (named e.g. <Project>Kit).
  • Don't start with multiple Packages — they only add Package.swift maintenance cost and CI resolution time.

Very thin App target

  • The App target only contains:
    • @main, the App struct
    • Info.plist, entitlements
    • Assets / Asset Catalog
    • A single DI composition root (wiring protocols to concrete implementations)
  • All views, logic, and Storage live in the Package.
  • The App target is not tested (it can't really be); all testable logic is in the Package.

Dependencies flow upward, never downward

Engine (pure Swift core)
   ↑
GameState / Domain
   ↑
Service modules (CloudKit / GameKit / Storage / Telemetry)
   ↑
UI module (SwiftUI)
   ↑
App target

Restricted Apple framework imports

  • CloudKit is imported only in its designated service target.
  • Same for GameKit / StoreKit.
  • The UI and logic layers consume these via injected protocols, never importing the framework directly.
  • This is the precondition for "core ports to Android / Linux" (Swift on Android can consume pure Swift modules directly).

One test target per production target

  • Each production target has a matching test target named <Module>Tests.
  • Shared fakes / stubs can be factored into a separate <Project>KitTesting target imported by multiple test targets.

Rationale

  • Single Package: the App's modules have no need for external publication, so multi-Package's marginal cost outweighs the benefit.
  • Thin App target: SwiftUI previews can run straight from the Package, yielding the fastest preview iteration loop.
  • Restricted framework imports: enables unit testing, keeps previews free of permission dialogs, and preserves the portability path.
  • One-to-one test targets: dependencies are clear, and CI can run only the modules that matter (paired with selective testing tooling).

Deviation considerations

  • A module needs to be published externally: upgrade to multi-Package; usually defer until the need is real.
  • A third-party dep is so heavy it harms build time: pin it inside a single target and fan out from logic layers.
  • Sharing across multiple Apps: extract into a standalone repo Swift Package.

Example shape

<Project>/
├── App/                          # thin shell
│   ├── <Project>App.swift        # @main + DI composition root
│   └── (Assets, Info.plist, entitlements)
└── Packages/
    └── <Project>Kit/
        ├── Package.swift
        └── Sources/
            ├── <Engine>/         # pure Swift core
            ├── <Domain>/         # domain logic
            ├── <Storage>/        # service module (CloudKit import restricted here)
            ├── <Telemetry>/      # Logger / Tracking facade
            └── <UI>/             # SwiftUI Views
        └── Tests/
            └── <Module>Tests/    # one-to-one

Common footguns

Pin parity across sibling apps

  • swift package resolve always re-resolves to the newest version each dependency's range allows — it does not consult a sibling app's committed pins. Running it to "materialize" a fresh Package.resolved for a second app silently drifts its pins away from the first app's committed versions.
  • To give app B pin-parity with app A: copy A's committed Package.resolved to B and swap only the originHash (obtained from one throwaway resolve on B), preserving the file's JSON formatting; then verify swift build leaves the file byte-identical (no churn). Diff the full pin list against the reference, not just the one dependency a task happened to mention.

Renaming a target or test directory

  • swift build plus an import-site grep are not sufficient verification for a target/test-directory rename. Non-Swift tooling — CI workflow files, task runners, code-gen scripts — often hard-code the path string, which compiles fine and passes the import grep but breaks at the tooling layer.
  • Before pushing a rename, also grep -rn '<OldName>' <tooling dirs> .github ci_scripts and run any gate that reads those paths (e.g. localization or fixture generation) locally to confirm it still resolves.

Related skills

  • swift6-concurrency: Package applies swiftLanguageModes: [.v6] in one place.
  • apple-platform-targets: Package platforms: aligned with App target.
  • swift-testing-baseline: test target framework and location.
  • telemetry-facade-pattern: why Telemetry is a standalone target.

What ships with it

Read from the repository

Just SKILL.md. No reference files, no scripts.

Keep looking

Skills are one crate of 610,677. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.