swift-language-expert

name	swift-language-expert
description	Use this skill for non-obvious Swift LANGUAGE and standard-library techniques -- features that make code clearer, safer, or faster but that developers routinely miss. Covers pattern matching (if/guard-case, switch over tuples); functions, closures, and key paths (variadics, autoclosures, rethrows); value semantics and custom types (copy-on-write, ~Copyable, callAsFunction, recursive enums, property wrappers); protocols and generics (associated types, opaque some vs existential any, phantom types); collections (lazy, RangeSet, InlineArray, sorting); strings and Unicode (grapheme-correct iteration, custom interpolation); concurrency and errors (async/await, task groups, AsyncStream, typed throws); and debugging and code organization (assertions, dump, enum namespaces, directives). Trigger for "how do I do X in Swift" and idiomatic refactors. Do NOT use for SwiftUI (swiftui-expert), app architecture or actor isolation in a layered app (ios-architecture-expert), or Swift Testing syntax (swift-testing-expert).
metadata	{"version":"1.0.0","author":"SwiftyJourney"}

Swift Language Expert

Non-obvious Swift language and standard-library techniques. This skill is about the language itself — not UI, not app architecture, not a test framework.

Agent Behavior Contract

When this skill is active, follow these rules strictly:

1. Language & stdlib only. SwiftUI → defer to swiftui-expert; app architecture / composition / where actor isolation goes in a layered app → ios-architecture-expert; Swift Testing (@Test/#expect) syntax → swift-testing-expert.
2. Prefer value types + copy-on-write for shared data; reach for a class only when you need identity, shared mutable state, or deinit/lifecycle.
3. Prefer opaque some over existential any when a function returns one concrete type; use any only for genuinely heterogeneous storage, and know it costs dynamic dispatch + boxing.
4. Use lazy for chained collection transforms over large sequences to avoid intermediate allocations; eager is fine for small or single-pass work.
5. Respect Unicode. Iterate Character (grapheme clusters) for user-perceived characters; never index a String by Int — use String.Index.
6. Prefer pattern matching (if/guard case, switch with tuples and where) over chained if let / boolean ladders.
7. Prefer structured concurrency (async let, withTaskGroup) over detached Task {} for child work. Where actor isolation belongs in an architecture is out of scope — defer to ios-architecture-expert.
8. Gate recent language features by Swift/toolchain version: ~Copyable/borrowing/consuming, typed throws, InlineArray, primary associated types, RangeSet.

---

Swift Technique Diagnostic Table

Symptom / goal	Reach for	Deep dive
Pyramid of nested if let / boolean ladders	guard/if case, optional patterns, switch over tuples	references/pattern-matching-and-control-flow.md
An argument is evaluated even when unused (e.g. assert, log)	@autoclosure (+ @escaping where needed)	references/functions-closures-keypaths.md
Passing "which property" around as data	key-path expressions (\.name), key-path-as-function	references/functions-closures-keypaths.md
A class used only to share/mutate a value	value type + copy-on-write (isKnownUniquelyReferenced)	references/custom-types.md
A type that must never be copied (handle, lock, token)	~Copyable + consuming/borrowing	references/custom-types.md
String-typed IDs of different kinds get mixed up	phantom types (a generic tag parameter)	references/protocols-and-generics.md
any Protocol everywhere / dynamic-dispatch cost	some (opaque) vs any (existential); primary associated types	references/protocols-and-generics.md
filter + map over a huge collection allocates twice	.lazy; RangeSet/DiscontiguousSlice for non-contiguous selection	references/collections.md
Splitting/counting a string gives wrong results on emoji/accents	grapheme-cluster iteration, String.Index, normalization	references/strings.md
Hand-rolled pluralization / building strings with +	custom StringInterpolation, raw strings	references/strings.md
Fan out concurrent work and collect results	async let, withTaskGroup / withThrowingTaskGroup	references/concurrency-and-errors.md
Bridge a delegate/callback API to async	AsyncStream, withCheckedContinuation	references/concurrency-and-errors.md
catch can't enumerate the errors a function throws	typed throws	references/concurrency-and-errors.md
Global let constants polluting the namespace	caseless enum namespace, type subscripts	references/debugging-and-organization.md

---

Guardrails

• Do not use a class where a struct (+ copy-on-write if needed) suffices — reach for reference types only for identity/shared-mutable-state/lifecycle
• Do not return any P when one concrete type is returned — use some P
• Do not index String by integer offsets — use String.Index; iterate Character for user-perceived characters
• Do not chain if let ladders where a guard case/switch reads clearer
• Do not spawn unstructured Task {} for child work that should be async let / a task group
• Do not solve SwiftUI, app architecture, or Swift Testing problems here — defer to the sibling skills
• Do not use bleeding-edge syntax without gating it by Swift/toolchain version

---

Reference Router

Open the smallest reference that matches the question:

• Control flow & functions
  • pattern-matching-and-control-flow.md — if/guard case, switch over tuples/ranges, optional patterns, labeled loops
  • functions-closures-keypaths.md — variadics, autoclosures, rethrows, overloading, key paths
• Types
  • custom-types.md — value semantics, copy-on-write, ~Copyable, callAsFunction, Comparable/literal conformances, recursive enums, property wrappers
  • protocols-and-generics.md — associated types, Self, some vs any, primary associated types, phantom types, constraints
• Data
  • collections.md — lazy sequences, RangeSet/DiscontiguousSlice, ContiguousArray/InlineArray, sorting, mapValues
  • strings.md — String.Index, grapheme/Unicode handling, normalization, raw strings, custom interpolation
• Concurrency & errors
  • concurrency-and-errors.md — async/await, structured concurrency, AsyncSequence/AsyncStream, typed throws
• Tooling
  • debugging-and-organization.md — assertions, dump, CustomDebugStringConvertible, type subscripts, enum namespaces, compiler directives