programming-swift— agent skill

Overview

Use for Swift language implementation and review across packages, services, and apps. Keep platform UI, persistence, and distribution decisions in their platform context; focus here on values, APIs, concurrency, and explicit failures.

Mental model

Value semantics control mutation; actor isolation controls access; task structure controls lifetime. None substitutes for the others. Make these contracts visible instead of quieting compiler diagnostics with unchecked annotations or detached tasks.

Version and isolation gate

As of 2026-10: Swift 6.4 is the current release (September 2026, shipped in Xcode 27). Check the repository's toolchain, swift-tools-version, language mode, upcoming-feature flags, default isolation, and deployment targets separately. A Swift 6 compiler can compile in Swift 5 language mode.

• Swift 6 language mode enables data-race safety checks. Migrate boundaries deliberately; don't assume a toolchain upgrade changes the package's language mode.
• Swift 6.2 adds opt-in default MainActor isolation and NonisolatedNonsendingByDefault, under which nonisolated async functions inherit caller isolation. Read actual settings before inferring where a function runs. async does not mean background execution.
• @concurrent on supported toolchains explicitly moves eligible async work to the concurrent executor. Use it for computation that must leave an actor, not as an annotation on every async function.
• Swift 6.2 also introduces InlineArray and Span; use them for demonstrated fixed-storage or borrowing requirements. Swift 6.3 adds @c interoperability; prefer supported declarations over underscored attributes when the compiler and C contract permit them.
• Swift 6.4 adds withTaskCancellationShield (SE-0504) for cleanup that must finish despite cancellation, awaited async calls in defer (SE-0493), @diagnose for in-source warning control (SE-0522), module selectors (Module::name, SE-0491), and noncopyable containers (UniqueBox, UniqueArray). Shield only bounded cleanup, not ordinary work; don't use @diagnose to silence a diagnostic whose cause is unresolved.

Values and API design

• Prefer structs for independent values and enums with associated values for distinct states. Use classes for identity or shared lifecycle; don't impose reference semantics merely to enable inheritance.
• A struct containing a mutable class reference is not deeply independent. Keep mutation private, and validate invariants at creation rather than distributing checks through callers.
• Read APIs at their call sites. Labels should distinguish meaning (remove(at:) versus remove(_:)); expose minimal access and document non-obvious ownership, failure, or complexity contracts.
• Use generics or some Protocol when one concrete type remains statically determined. Use any Protocol for a heterogeneous existential contract; neither guarantees value semantics.
• Add protocols where substitution or a boundary is useful, not for every concrete type. Keep computed properties predictable; expensive or failing work usually deserves an explicit method.
• Model valid absence with Optional. Use throws for failures and typed throws only when a stable error set benefits callers; don't replace informative failures with try?, sentinel values, or empty collections.

Concurrency and resource lifetime

• Actors protect isolated mutable state. Actor references can cross isolation boundaries; accessing isolated members requires the appropriate isolation, often await. Transfer data using Sendable values or valid ownership transfer, not unsafe shared references.
• An actor method can interleave with other work at each await. Recheck state after suspension when correctness depends on it; serial access does not make a multi-await operation atomic.
• Prefer async let and task groups for child work that belongs to the current operation. Bound large fan-out. A Task {} is unstructured and may inherit actor context; retain its handle when explicit cancellation or result observation is needed.
• Task.detached loses inherited context and structured cancellation. Use only for a deliberate independent boundary, with explicit lifetime and failure handling.
• Cancellation is cooperative. Propagate cancellation rather than displaying it as failure; check it in long computations and before publishing stale results. Don't assume cancellation guarantees an underlying callback or I/O operation stopped.
• Checked continuations must resume exactly once on every path; bridge cancellation and callback lifetimes explicitly. Use defer for synchronous cleanup and deliberate asynchronous cleanup where necessary.
• @unchecked Sendable, nonisolated(unsafe), and force operations require a documented invariant; don't use them to bypass an unresolved ownership problem.

Packages and checks

• Preserve the dependency manager and target layout. Create an SPM target only for a real reusable or independently testable boundary; macros require their supported compiler-plugin setup. Swift 6.4 makes Swift Build SwiftPM's default build system; if a package build changes behavior after a toolchain upgrade, check that first.
• Follow existing formatters and tests. Swift Testing supports modern unit tests; XCTest remains appropriate for existing suites, UI automation, and XCTest-specific facilities. On Swift 6.4, XCTAssert works inside Swift Testing and #expect inside XCTest, so suites can migrate incrementally; don't migrate tests merely for syntax.
• Test actor reentrancy, cancellation, and invalid input when affected. Distinguish source review from checks actually executed under the supported toolchain.

Example

Keep an actor's invariant inside a non-suspending operation:

actor Inventory {
    private var available = 10

    func reserve(_ quantity: Int) -> Bool {
        guard quantity > 0, quantity <= available else { return false }
        available -= quantity
        return true
    }
}

A caller uses await inventory.reserve(2) across isolation. If remote authorization is added before mutation, state must be revalidated after that await or reserved with an explicit rollback protocol.

Checklist

• [ ] Compiler, language mode, isolation flags, and deployment target are known.
• [ ] Value ownership and actor access remain correct across suspension.
• [ ] Every task and callback bridge has a lifetime and failure path.
• [ ] Absence, cancellation, and failure remain distinct.
• [ ] Relevant checks were run when authorized; skipped checks are stated.

References

• Swift 6.4, Swift 6.3, and Swift 6.2
• Compiler and SDK matrix
• Concurrency
• Migration guide
• API design guidelines