# Swift API Design Guidelines

Apply Swift API Design Guidelines to name, label, and document Swift APIs.

- Repository: https://github.com/dpearson2699/swift-ios-skills (1266 stars)
- Category: Design
- License: see repository
- Last updated: 2026-07-31
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add dpearson2699/swift-ios-skills --skill swift-api-design-guidelines -g -a claude-code -y`
Codex: `npx skills add dpearson2699/swift-ios-skills --skill swift-api-design-guidelines -g -a codex -y`
Cursor: `npx skills add dpearson2699/swift-ios-skills --skill swift-api-design-guidelines -g -a cursor -y`
Gemini CLI: `npx skills add dpearson2699/swift-ios-skills --skill swift-api-design-guidelines -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add dpearson2699/swift-ios-skills`

## Description

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.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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](#argument-label-rules)
- [Side-Effect Naming](#side-effect-naming)
- [Mutating and Nonmutating Pairs](#mutating-and-nonmutating-pairs)
- [Documentation Comments](#documentation-comments)
- [Clarity and Naming](#clarity-and-naming)
- [Fluent Usage and Protocols](#fluent-usage-and-protocols)
- [General Conventions](#general-conventions)
- [Common Mistakes](#common-mistakes)
- [Review Checklist](#review-checklist)
- [References](#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](references/argument-labels-and-parameters.md)
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.

The rest: https://github.com/dpearson2699/swift-ios-skills/blob/HEAD/skills/swift-api-design-guidelines/SKILL.md