swift-ecosystem

name	Swift Ecosystem
description	This skill should be used when working with Swift projects, "Package.swift", "swift build/test/run", "swiftc", SwiftLint, SwiftFormat, or Swift language patterns. Provides comprehensive Swift 6.3 ecosystem patterns and best practices for cross-platform CLI and library development.
version	2.0.0

Provide comprehensive patterns for Swift language, Swift Package Manager, and toolchain configuration for cross-platform CLI and library development. Read - Analyze Package.swift and Swift source files Edit - Modify Swift code and SPM configuration Bash - Run swift build, swift test, swiftlint commands mcp__plugin_claude-code-home-manager_context7__query-docs - Fetch latest Swift documentation Structs and enums are value types with copy semantics; prefer over classes for data Optional types (T?) for values that may be absent; use if-let, guard-let, or ?? for safe unwrapping Define behavior contracts; use protocol-oriented programming for composition over inheritance Type parameters for reusable code; use where clauses for constraints async/await for asynchronous code; actors for safe mutable state; Sendable for thread-safe types

<swift_language> <type_system> Structs and enums are value types (copied); classes are reference types (shared) Prefer structs for data models without identity Use classes only when reference semantics or inheritance is required Enums with associated values for algebraic data types

<concept name="optionals">
  <description>Swift's nil-safety through Optional type</description>
  <pattern name="safe_unwrapping">
    <example>
      // if-let binding
      if let value = optionalValue {
        use(value)
      }

      // guard-let for early exit
      guard let value = optionalValue else { return }

      // nil-coalescing
      let value = optionalValue ?? defaultValue

      // optional chaining
      let result = object?.property?.method()
    </example>
  </pattern>
  <anti_pattern name="force_unwrap">
    <description>Using ! to force unwrap optionals</description>
    <instead>Use if-let, guard-let, or ?? instead of force unwrapping</instead>
  </anti_pattern>
</concept>

<concept name="protocols">
  <description>Define behavior contracts for types</description>
  <pattern name="protocol_oriented">
    <description>Prefer composition with protocols over class inheritance</description>
    <example>
      protocol Identifiable {
        var id: String { get }
      }

      protocol Timestamped {
        var createdAt: Date { get }
      }

      struct User: Identifiable, Timestamped {
        let id: String
        let createdAt: Date
        let name: String
      }
    </example>
  </pattern>
  <pattern name="protocol_extensions">
    <description>Provide default implementations via extensions</description>
    <example>
      protocol Describable {
        var description: String { get }
      }

      extension Describable {
        var description: String {
          String(describing: self)
        }
      }
    </example>
  </pattern>
</concept>

<concept name="generics">
  <description>Type-safe reusable code with type parameters</description>
  <pattern name="generic_constraints">
    <example>
      func process&lt;T: Codable &amp; Sendable&gt;(_ item: T) -&gt; Data {
        try! JSONEncoder().encode(item)
      }

      func compare&lt;T&gt;(_ a: T, _ b: T) -&gt; Bool where T: Comparable {
        a &lt; b
      }
    </example>
  </pattern>
</concept>

<concept name="noncopyable">
  <description>Types with unique ownership using ~Copyable (Swift 6+)</description>
  <example>
    struct UniqueResource: ~Copyable {
      consuming func release() { /* takes ownership */ }
    }

    func process(borrowing data: SomeData) { /* read-only */ }
    func consume(consuming data: SomeData) { /* takes ownership */ }
  </example>
  <rules priority="critical">
    <rule>Use for resources requiring unique ownership (file handles, locks)</rule>
    <rule>Mark methods with borrowing/consuming for explicit ownership</rule>
  </rules>
</concept>

</type_system>

<error_handling> Use throws for recoverable errors enum ParseError: Error { case invalidFormat case missingField(String) }

    func parse(_input: String) throws -> Config {
      guard !input.isEmpty else {
        throw ParseError.invalidFormat
      }
      // parsing logic
    }

    // Calling
    do {
      let config = try parse(input)
    } catch ParseError.invalidFormat {
      // handle specific error
    } catch {
      // handle other errors
    }
  </example>
</pattern>

<pattern name="result_type">
  <description>Use Result for async error handling or when throws is inconvenient</description>
  <example>
    func fetch(url: URL) -&gt; Result&lt;Data, NetworkError&gt; {
      // implementation
    }

    switch fetch(url: someURL) {
    case .success(let data):
      process(data)
    case .failure(let error):
      handle(error)
    }
  </example>
</pattern>

<pattern name="typed_throws">
  <description>Specify exact error type in function signature (Swift 6+)</description>
  <example>
    func parse(_ input: String) throws(ParseError) -&gt; Config {
      guard !input.isEmpty else { throw ParseError.invalidFormat }
      // parsing logic
    }

    // Caller knows exactly which errors to handle
    do {
      let config = try parse(input)
    } catch {
      // error is typed as ParseError, not any Error
      switch error {
      case .invalidFormat: handleInvalidFormat()
      case .missingField(let name): handleMissing(name)
      }
    }
  </example>
</pattern>

</error_handling>

Structured concurrency with async/await (Swift 5.5+) func fetchData() async throws -> Data { let (data, _) = try await URLSession.shared.data(from: url) return data }

    // Calling
    Task {
      do {
        let data = try await fetchData()
      } catch {
        // handle error
      }
    }
  </example>
</pattern>

<pattern name="actors">
  <description>Thread-safe mutable state with actors</description>
  <example>
    actor Counter {
      private var value = 0

      func increment() {
        value += 1
      }

      func getValue() -&gt; Int {
        value
      }
    }

    let counter = Counter()
    await counter.increment()
    let value = await counter.getValue()
  </example>
</pattern>

<pattern name="main_actor">
  <description>@MainActor ensures code runs on the main thread. Essential for UI updates.</description>
  <example>
    @MainActor
    class ViewModel: ObservableObject {
      @Published var items: [Item] = []

      func loadItems() async {
        items = await fetchItems()
      }
    }
  </example>
</pattern>

<pattern name="sendable">
  <description>Mark types safe for concurrent access</description>
  <example>
    // Implicitly Sendable (value types with Sendable properties)
    struct Config: Sendable {
      let timeout: Int
      let retries: Int
    }

    // Explicitly mark as Sendable
    final class ImmutableCache: Sendable {
      let data: [String: String]
      init(data: [String: String]) {
        self.data = data
      }
    }
  </example>
</pattern>

<pattern name="task_groups">
  <description>Parallel execution with structured concurrency</description>
  <example>
    func processAll(_ items: [Item]) async throws -&gt; [Result] {
      try await withThrowingTaskGroup(of: Result.self) { group in
        for item in items {
          group.addTask {
            try await process(item)
          }
        }
        return try await group.reduce(into: []) { $0.append($1) }
      }
    }
  </example>
</pattern>

<pattern name="strict_concurrency">
  <description>Enable complete strict concurrency checking for data race safety (Swift 6 default).</description>
  <example>
    // In Package.swift
    swiftSettings: [
      .swiftLanguageMode(.v6), // Enables strict concurrency
    ]

    // Or compiler flag:
    // -strict-concurrency=complete
  </example>
  <note>Swift 6 enables strict concurrency by default. For migration, use -strict-concurrency=complete with Swift 5 mode to find issues incrementally.</note>
</pattern>

<rules priority="critical">
  <rule>Use async/await over completion handlers for new code</rule>
  <rule>Use actors for shared mutable state instead of locks</rule>
  <rule>Mark types as Sendable when they cross concurrency boundaries</rule>
</rules>

<memory_management> Prevent retain cycles in closures and delegates class Controller { var onComplete: (() -> Void)?

      func setup() {
        service.fetch { [weak self] result in
          self?.handleResult(result)
        }
      }
    }
  </example>
</pattern>

<pattern name="unowned_references">
  <description>Non-optional weak reference when lifetime is guaranteed</description>
  <example>
    class Parent {
      var child: Child?
    }

    class Child {
      unowned let parent: Parent

      init(parent: Parent) {
        self.parent = parent
      }
    }
  </example>
</pattern>

<rules priority="critical">
  <rule>Always use [weak self] in escaping closures unless self lifetime is guaranteed</rule>
  <rule>Use unowned only when you can guarantee the referenced object outlives the closure</rule>
</rules>

</memory_management>

<common_patterns> Fluent API for complex object construction struct RequestBuilder { private var method: String = "GET" private var headers: [String: String] = [:]

      func method(_ m: String) -> RequestBuilder {
        var copy = self
        copy.method = m
        return copy
      }

      func header(_ key: String, _ value: String) -> RequestBuilder {
        var copy = self
        copy.headers[key] = value
        return copy
      }

      func build() -> Request {
        Request(method: method, headers: headers)
      }
    }
  </example>
</pattern>

<pattern name="result_builder">
  <description>DSL construction with @resultBuilder</description>
  <example>
    @resultBuilder
    struct ArrayBuilder&lt;Element&gt; {
      static func buildBlock(_ components: Element...) -&gt; [Element] {
        components
      }
    }

    func buildArray&lt;T&gt;(@ArrayBuilder&lt;T&gt; _content: () -&gt; [T]) -&gt; [T] {
      content()
    }
  </example>
</pattern>

<pattern name="property_wrappers">
  <description>Encapsulate property access patterns</description>
  <example>
    @propertyWrapper
    struct Clamped&lt;Value: Comparable&gt; {
      private var value: Value
      private let range: ClosedRange&lt;Value&gt;

      var wrappedValue: Value {
        get { value }
        set { value = min(max(newValue, range.lowerBound), range.upperBound) }
      }

      init(wrappedValue: Value, _ range: ClosedRange&lt;Value&gt;) {
        self.range = range
        self.value = min(max(wrappedValue, range.lowerBound), range.upperBound)
      }
    }

    struct Volume {
      @Clamped(0...100) var level: Int = 50
    }
  </example>
</pattern>

</common_patterns>

<anti_patterns> Using ! to force unwrap optionals Use if-let, guard-let, or nil-coalescing

<avoid name="force_try">
  <description>Using try! to ignore errors</description>
  <instead>Use do-catch or propagate with throws</instead>
</avoid>

<avoid name="class_for_data">
  <description>Using class for simple data containers</description>
  <instead>Use struct for value semantics</instead>
</avoid>

<avoid name="any_abuse">
  <description>Overusing Any or AnyObject types</description>
  <instead>Use generics or protocols with associated types</instead>
</avoid>

<avoid name="retain_cycles">
  <description>Strong reference cycles in closures</description>
  <instead>Use [weak self] or [unowned self] capture lists</instead>
</avoid>

</anti_patterns> </swift_language>

<swift_63_features> First Swift SDK for Android in stable. Enables native Android development in Swift, updating existing Swift packages for Android support, and integrating Swift code in Kotlin/Java apps via Swift Java and Swift Java JNI Core. The @c attribute lets developers expose Swift functions and enums to C code within a single project. @c func myFunction() -> Int32 { return 42 } Swift Build integration in Swift Package Manager is now available as opt-in, deduplicating build technologies and delivering consistent cross-platform build experience. Continued improvements for using Swift in embedded environments. </swift_63_features>

Is this synchronous code with recoverable errors? Use throws with do-catch Use Result type Use Optional Use typed throws

<decision_tree name="package_type"> What are you building? Library (.library product) Executable (.executable product) Multiple products with shared target </decision_tree>

<decision_tree name="reference_type_choice"> What is the relationship between objects? Use strong reference Use weak reference Use unowned reference </decision_tree>

<decision_tree name="type_choice"> What kind of type do you need? Use struct (value type) Use class (reference type) or actor Use enum with associated values Use ~Copyable struct (Swift 6+) </decision_tree>

<swift_package_manager> <project_structure> <standard_layout> . ├── Package.swift ├── Package.resolved ├── Sources/ │ ├── MyLibrary/ │ │ └── MyLibrary.swift │ └── MyCLI/ │ └── main.swift ├── Tests/ │ └── MyLibraryTests/ │ └── MyLibraryTests.swift └── Plugins/ └── MyPlugin/ └── plugin.swift </standard_layout>

<module_organization>
  <pattern name="single_target">
    <description>Simple library or executable</description>
  </pattern>
  <pattern name="multi_target">
    <description>Library with CLI tool or multiple modules</description>
  </pattern>
</module_organization>

</project_structure>

<package_swift> <basic_structure> // swift-tools-version: 6.3 import PackageDescription

  // For cross-platform (macOS + Linux), omit platforms array entirely
  // Only specify platforms when using platform-specific APIs
  let package = Package(
    name: "MyPackage",
    platforms: [
      .macOS(.v14)
    ],
    products: [
      .library(
        name: "MyLibrary",
        targets: ["MyLibrary"]
      ),
      .executable(
        name: "my-cli",
        targets: ["MyCLI"]
      )
    ],
    dependencies: [
      .package(url: "https://github.com/apple/swift-argument-parser", from: "1.5.0"),
      .package(url: "https://github.com/apple/swift-log", from: "1.6.0")
    ],
    targets: [
      .target(
        name: "MyLibrary",
        dependencies: [
          .product(name: "Logging", package: "swift-log")
        ]
      ),
      .executableTarget(
        name: "MyCLI",
        dependencies: [
          "MyLibrary",
          .product(name: "ArgumentParser", package: "swift-argument-parser")
        ]
      ),
      .testTarget(
        name: "MyLibraryTests",
        dependencies: ["MyLibrary"]
      )
    ]
  )
</basic_structure>

<dependency_specification>
  // Exact version
  .package(url: "...", exact: "1.2.3")

  // Version range
  .package(url: "...", from: "1.0.0") // 1.0.0 ..&lt; 2.0.0
  .package(url: "...", "1.0.0"..&lt;"2.0.0")

  // Branch or revision
  .package(url: "...", branch: "main")
  .package(url: "...", revision: "abc123")

  // Local package
  .package(path: "../LocalPackage")
</dependency_specification>

<swift_settings>
  .target(
    name: "MyTarget",
    swiftSettings: [
      .enableUpcomingFeature("StrictConcurrency"),
      .enableExperimentalFeature("AccessLevelOnImport"),
      .unsafeFlags(["-warnings-as-errors"], .when(configuration: .release))
    ]
  )
</swift_settings>

</package_swift>

Compile the package Compile with optimizations Build and run executable Run all tests Run specific test Resolve dependencies Update dependencies Show dependency tree Create new library package Create new CLI package Clean build artifacts Swift linter for enforcing style and conventions swiftlint lint

<configuration>
  <file_reference>.swiftlint.yml</file_reference>
  disabled_rules:
    - trailing_whitespace
    - line_length

  opt_in_rules:
    - empty_count
    - closure_spacing
    - force_unwrapping

  included:
    - Sources
    - Tests

  excluded:
    - .build
    - Packages

  line_length:
    warning: 120
    error: 200

  type_body_length:
    warning: 300
    error: 500

  file_length:
    warning: 500
    error: 1000
</configuration>

<common_rules>
  <rule name="force_unwrapping">Disallow force unwrapping with !</rule>
  <rule name="force_try">Disallow force try with try!</rule>
  <rule name="force_cast">Disallow force casting with as!</rule>
  <rule name="empty_count">Prefer isEmpty over count == 0</rule>
  <rule name="closure_spacing">Ensure spacing in closures</rule>
</common_rules>

Code formatter for consistent style (nicklockwood) swiftformat .

<configuration>
  <file_reference>.swiftformat</file_reference>
  --swiftversion 6.3
  --indent 4
  --indentcase false
  --trimwhitespace always
  --voidtype void
  --wraparguments before-first
  --wrapcollections before-first
  --maxwidth 120
  --self remove
  --importgrouping testable-last
  --semicolons never
  --commas always
</configuration>

<common_options>
  <option name="--swiftversion">Target Swift version</option>
  <option name="--indent">Indentation width (default: 4)</option>
  <option name="--maxwidth">Maximum line width</option>
  <option name="--self">Self keyword insertion (remove/insert)</option>
  <option name="--wraparguments">Argument wrapping style</option>
</common_options>

<sourcekit_lsp> Language server for IDE integration Bundled with Swift toolchain

<vscode_setup>
  <step order="1">

Install Swift extension (official) Workflow guidance Step completed Extension uses SourceKit-LSP automatically Workflow guidance Step completed Run swift build to generate index Workflow guidance Step completed </vscode_setup>

<features>
  <feature>Code completion</feature>
  <feature>Jump to definition</feature>
  <feature>Find references</feature>
  <feature>Diagnostics</feature>
  <feature>Code actions</feature>
</features>

</sourcekit_lsp>

<other_tools> Modern testing framework (stable since Swift 6.0) import Testing

    @Test func addition() {
      #expect(1 + 1 == 2)
    }

    @Test("Descriptive name")
    func subtraction() throws {
      let result = try compute()
      #expect(result > 0)
    }
  </example>
</tool>

<tool name="swift-format">
  <description>Apple's official formatter (alternative to SwiftFormat)</description>
  <note>Built into Xcode 16; use swift-format command</note>
</tool>

<tool name="swift-docc">
  <description>Documentation compiler for Swift</description>
  <usage>swift package generate-documentation</usage>
</tool>

</other_tools>

Modern testing framework, stable since Swift 6.0, with macro-based test declarations

<pattern name="basic_test">
  <example>
    import Testing

    @Test func addition() {
      #expect(1 + 1 == 2)
    }

    @Test("Descriptive name")
    func subtraction() throws {
      let result = try compute()
      #expect(result &gt; 0)
    }
  </example>
</pattern>

<pattern name="parameterized_test">
  <example>
    @Test(arguments: [1, 2, 3])
    func multipleInputs(value: Int) {
      #expect(value &gt; 0)
    }
  </example>
</pattern>

<pattern name="test_suite">
  <example>
    @Suite("Calculator Tests")
    struct CalculatorTests {
      @Test func add() { #expect(1 + 1 == 2) }
      @Test func multiply() { #expect(2 * 3 == 6) }
    }
  </example>
</pattern>

<pattern name="async_test">
  <example>
    @Test func fetchData() async throws {
      let data = try await service.fetch()
      #expect(!data.isEmpty)
    }
  </example>
</pattern>

<note>swift-testing does not yet support performance testing or UI testing</note>

</swift_testing>

Legacy testing framework for existing codebases

<migration>
  <step order="1">

Replace XCTAssert with #expect Workflow guidance Step completed Replace XCTAssertEqual with #expect(a == b) Workflow guidance Step completed Replace XCTestCase class with @Test functions Workflow guidance Step completed Use @Suite for test grouping Workflow guidance Step completed

<best_practices> Use swift-testing for new test code Organize tests in Tests/ directory with TestTarget suffix Use @Test for individual test functions Use @Suite for grouping related tests Use parameterized tests for testing multiple inputs </best_practices>

<context7_integration> Use Context7 MCP for up-to-date Swift documentation

<swift_libraries> </swift_libraries>

<usage_patterns> resolve-library-id libraryName="swift" Workflow guidance Step completed get-library-docs context7CompatibleLibraryID="/swiftlang/swift" topic="concurrency" Workflow guidance Step completed

<pattern name="package_configuration">
  <step order="1">

get-library-docs context7CompatibleLibraryID="/swiftlang/swift" topic="Package.swift" Workflow guidance Step completed

<pattern name="library_usage">
  <step order="1">

get-library-docs context7CompatibleLibraryID="/alamofire/alamofire" topic="request" Workflow guidance Step completed </usage_patterns> </context7_integration>

<best_practices> Use swift build for compilation; swift test for testing Run swiftlint before committing Format with swiftformat for consistent style Prefer value types (structs) over reference types (classes) Use async/await for asynchronous code Mark types as Sendable for concurrency safety Document public API with /// doc comments Write tests alongside implementation Use Swift Testing framework for new test code Specify swift-tools-version in Package.swift </best_practices>

<anti_patterns> Using ! to force unwrap optionals Use if-let, guard-let, or nil-coalescing Using try! to ignore errors Use do-catch or propagate with throws Using class for simple data containers Use struct for value semantics Overusing Any or AnyObject types Use generics or protocols with associated types Strong reference cycles in closures Use [weak self] or [unowned self] capture lists </anti_patterns>

Run swiftlint before committing; fix all warnings Never use force unwrap (!) in library code Use async/await over completion handlers for new code Use swiftformat for consistent formatting Prefer structs over classes for data types Write unit tests in Tests/ directory Use guard for early exit patterns Understand Swift code requirements 1. Check Package.swift for package configuration Workflow guidance Step completed 2. Review existing patterns and protocols Workflow guidance Step completed 3. Identify concurrency requirements Workflow guidance Step completed Write safe, idiomatic Swift code 1. Design with value types and protocols Workflow guidance Step completed 2. Use optionals and error handling correctly Workflow guidance Step completed 3. Follow Swift API design guidelines Workflow guidance Step completed Verify Swift code correctness 1. Run swift build for compilation check Workflow guidance Step completed 2. Run swiftlint for style/safety lints Workflow guidance Step completed 3. Run swift test for testing Workflow guidance Step completed

<error_escalation inherits="core-patterns#error_escalation"> SwiftLint warning about style Type safety error or optional handling issue Breaking change in public API Force unwrap or unsafe code in library </error_escalation>

Prefer value types over reference types Use optionals and proper error handling Follow Swift API design guidelines Using force unwrap (!) in library code Using force try (try!) in production code Completion handlers when async/await is available

<related_skills> Navigate protocol implementations and module structure Fetch Swift language and library documentation Debug type errors, optional handling, and concurrency issues </related_skills> <related_agents> Locate code patterns and references in this skill domain Review implementation quality against this skill guidance Analyze code complexity and suggest refactoring improvements </related_agents>