Agent skill · writing content · dpearson2699
swift-api-design-guidelines
Apply Swift API Design Guidelines to name, label, and document Swift APIs. Covers argument label rules (prepositional phrase rule, grammatical phrase rule, first-label omission), mutating/nonmutating pair naming (-ed/-ing participle pattern, form- prefix, sort/sorted, formUnion/union), side-effect naming (noun for pure, verb for mutating), documentation comment structure (summary by declaration kind, O(1) complexity rule), clarity at call site, role-based naming, protocol naming (-able/-ible/-ing), default arguments over method families, casing conventions, and terminology. Use when designing new Swift APIs, reviewing naming and argument labels, writing documentation comments, or refactoring for call site clarity.
Why this skill is useful
Provides specific naming conventions and documentation structures for Swift APIs that the AI wouldn't reliably generate on its own.
What it needs
About 7k tokens when loaded. Last updated 2026-07-31. 973 stars on the source repository.
What this skill does
Swift API Design Guidelines Apply the Swift API Design Guidelines to naming, labels, documentation, and call-site clarity. For mixed requests, handle the API-design portion here and route language/type-system work to swift-language, concurrency to swift-concurrency, and lint configuration to swiftlint. Contents Argument Label Rules Side-Effect Naming Mutating and Nonmutating Pairs Documentation Comments Clarity and Naming Fluent Usage and Protocols General Conventions Common Mistakes Review Checklist References Argument Label Rules Argument labels determine how a call site reads. Apply the first matching row: Situation Rule Example ----------- ------ --------- First arg completes grammatical phrase Omit label, merge words into base name addSubview(y) Value-preserving init conversion Omit first label Int64(someUInt32) Arguments are indistinguishable peers Omit all labels min(x, y) First arg completes prepositional phrase Label with preposition fade(from: red) First two args form a single abstraction Fold preposition into base name moveTo(x: b, y: c) Everything else Label it split(maxSplits: 2) Load Argument Labels and Parameters when resolving abstraction boundaries, multiple prepositions, conversion initializers, indistinguishable peers, parameter naming, or default arguments. Side-Effect Naming Use imperative verbs for operations with side effects, result-describing noun or adjective phrases for operations without side effects, and assertion-style names for Boolean APIs. Load Side Effects and Mutating Pairs when reviewing extended pure/mutating examples or Boolean naming. Mutating and Nonmutating Pairs Name mutating/nonmutating pairs from the operation's natural description: For verb operations, use the imperative for mutation and a result-describing participle for the copy: sort()/sorted() or append(:)/appending(:). Prefer -ed; use -ing only when -ed is ungrammatical or describes the direct object instead of the returned result. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills dpearson2699/swift-api-design-guidelines