SkillAgentSearch skills...

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 n…

Install / Use

npx skills add dpearson2699/swift-ios-skills --skill swift-api-design-guidelines

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

89/100

Supported Platforms

Universal

Our assessment of swift-api-design-guidelines

swift-api-design-guidelines scores 89/100 on our quality scale, 525th of 1,155 Content & Media skills we index (top 46%).

Its SKILL.md is 13 KB long, well organised into 19 sections with 13 code examples: a thorough specification that gives an agent plenty to work with.

With 1,143 GitHub stars, it is one of the more widely adopted skills in the catalogue.

Substance
30/30
Structure
20/20
Description
15/15
Adoption
13/20
Freshness
11/15

Maintenance, license and trust

  • The repository was last updated about 4 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
  • Our last check on 2026-10-31 found the source still online.
  • No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
  • Its trust signals score 86/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-10-04. Automated pattern scan on 2026-10-04. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

swift-api-design-guidelines compared with similar skills

All 4 of these similar skills score higher than swift-api-design-guidelines; compare them before choosing.

SkillScoreStarsUpdatedFormat
swift-api-design-guidelines (this skill)by dpearson2699891.1k4mo agoSKILL.md
taste-skillby Leonxlnx100116.8k8d agoCLAUDE.md
Agent-Reachby Panniantong100112.3k8d agoCLAUDE.md
headroomby headroomlabs-ai10079.8ktodayCLAUDE.md
Claude-Code-Game-Studiosby Donchitos10039.7k7d agoCLAUDE.md

Frequently asked questions

How do I install swift-api-design-guidelines?
Run npx skills add dpearson2699/swift-ios-skills --skill swift-api-design-guidelines. The install tabs above show the steps for each supported agent.
Which AI agents does swift-api-design-guidelines work with?
It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
Is swift-api-design-guidelines safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It declares no license and scores 86/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is swift-api-design-guidelines still maintained?
The repository was last updated about 4 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.

name: swift-api-design-guidelines 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."

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 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.

array.sort()
array.append(newElement)
let d = point.distance(to: origin)
line.isEmpty
set.contains(element)

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.
  • For noun operations, use the noun for the copy and form + noun for mutation: union(_:) / formUnion(_:).
  • Prefix factories that create new values with make.

Load the -ed/-ing Decision Tree when the returned-result grammar is unclear. The same reference contains expanded form-prefix, Boolean, and factory patterns.

Documentation Comments

Every public declaration must have a documentation comment.

Summary rules by declaration kind

| Declaration | Summary describes | |-------------|-------------------| | Function / method | What it does and what it returns | | Subscript | What it accesses | | Initializer | What it creates | | Type / property / variable | What it is |

Write summaries as a single sentence fragment, beginning with a verb (for actions) or a noun phrase (for entities), ending in a period.

/// Returns the element at the specified index.
func element(at index: Int) -> Element { ... }

/// The number of elements in the collection.
var count: Int { ... }

/// Creates a new array with the given elements.
init(_ elements: some Sequence<Element>) { ... }

/// Accesses the element at the specified position.
subscript(index: Int) -> Element { ... }

Symbol markup

Use standard symbol markup after the summary when relevant:

  • - Parameter name: for individual parameters
  • - Parameters: block for multiple parameters
  • - Returns: for the return value
  • - Throws: for errors thrown
  • - Complexity: for algorithmic complexity
/// Removes and returns the element at the specified position.
///
/// - Parameter index: The position of the element to remove.
/// - Returns: The removed element.
/// - Complexity: O(*n*), where *n* is the length of the collection.
mutating func remove(at index: Int) -> Element { ... }

O(1) complexity rule

Document the complexity of any computed property that is not O(1). Callers assume properties are O(1) by default. If a property does more than constant-time work, state the complexity explicitly.

/// The total weight of all items.
///
/// - Complexity: O(*n*), where *n* is the number of items.
var totalWeight: Double {
    items.reduce(0) { $0 + $1.weight }
}

For documentation patterns and examples, see references/conventions-and-special-rules.md.

Clarity and Naming

Clarity at the point of use is the most important goal. Every design decision serves the person reading a call site.

Clarity over brevity. Longer names are acceptable when they remove ambiguity. Do not abbreviate.

// GOOD
employees.remove(at: position)

// BAD — ambiguous: remove the element? remove at position?
employees.remove(position)

Include words needed to avoid ambiguity. If omitting a word makes the call site unclear, keep it.

// GOOD — "at" clarifies the argument's role
friends.remove(at: index)

// BAD — is "index" the element to remove or the position?
friends.remove(index)

Omit needless words. Do not repeat type information already available from the context.

// GOOD
allViews.remove(cancelButton)

// BAD — "Element" repeats the type
allViews.removeElement(cancelButton)

Name variables and parameters by role, not type. Use the entity's role in the current context, not its type name.

// GOOD — describes the role
var greeting: String
func add(_ observer: NSObject, for keyPath: String)

// BAD — names the type
var string: String
func add(_ object: NSObject, for string: String)

Compensate for weak type information. When a parameter type is Any, AnyObject, or a fundamental type like Int or String, add role-clarifying words to the name.

// GOOD — role is clear despite weak types
func addObserver(_ observer: NSObject, forKeyPath path: String)

// BAD — what does "string" mean here?
func add(_ object: NSObject, for string: String)

For extended naming examples and patterns, see references/naming-and-clarity.md.

Fluent Usage and Protocols

Call sites read as grammatical English. Prefer names that form grammatical phrases at the point of use.

// GOOD — reads fluently
x.insert(y, at: z)          // "x, insert y at z"
x.subviews.remove(at: i)    // "x's subviews, remove at i"
x.makeIterator()             // "x, make iterator"

// BAD — ungrammatical
x.insert(y, position: z)
x.subviews.remove(i)

Initializer first argument. The first argument to an initializer should not form a phrase continuing the type name.

// GOOD
let foreground = Color(red: 32, green: 64, blue: 128)

// BAD — "Color with red" reads awkwardly
let foreground = Color(havingRGBValuesRed: 32, green: 64, blue: 128)

Protocol naming conventions:

| Protocol describes | Naming pattern | Examples | |--------------------|----------------|----------| | What something is | Noun | Collection, IteratorProtocol | | A capability | -able, -ible, or -ing suffix | Equatable, Hashable, Sendable |

General Conventions

Casing. Types and protocols use UpperCamelCase. Everything else uses lowerCamelCase. Acronyms that are commonly all-caps in American English appear uniformly upper- or lower-cased based on position.

var utf8Bytes: [UTF8.CodeUnit]
var isRepresentableAsASCII = true
var userSMTPServer: SMTPServer

Methods and properties over free functions. Prefer methods and properties. Use free functions only when:

  1. There is no obvious self — min(x, y)
  2. The function is an unconstrained generic — print(value)
  3. The function syntax is established domain notation — sin(x)

Default arguments over method families. Prefer a single method with default parameters over a family of methods that differ only in which parameters they accept. Place defaulted parameters at the end. Parameters with default values should always have argument labels — defaulted parameters are usually omitted at call sites, so their labels must be clear when they do appear.

// GOOD — labeled with defaults
func decode(_ data: Data, encoding: String.Encoding = .utf8) -> String?

// BAD — method family
func decode(_ data: Data) -> String?
func decode(_ data: Data, encoding: String.Encoding) -> String?

Overload safety. Methods may share a base name when they operate in different type domains or when their meaning is clear from context. Avoid return-type-only overloads that cause ambiguity at the call site.

For casing edge cases, overload patterns, and tuple/closure naming, see references/conventions-and-special-rules.md.

Common Mistakes

| Mistake | Correction | |---|---| | Ambiguous or missing labels | Make the call read grammatically, such as remove(at:). | | Wrong mutating/nonmutating form | Use imperative verbs for mutation and a grammatical -ed/-ing or noun form for copies. | | Names describe types or implementation | Name roles and semantic effects. | | Public API lacks purpose or complexity docs | Add a concise summary and document non-O(1) properties. | | form or factory prefixes are misapplied | Reserve form for noun operations; use make for factories. | | Type information is repeated | Remove words already clear from the declaration and context. | | Overloads differ only by return type | Add a semantic name or parameter distinction. | | Tuple or closure components are positional | Label public components and closure parameters. |

Review Checklist

Argument Labels

  • [ ] First argument follows the correct label rule (grammatical phrase, prepositional, conversion, or labeled)
  • [ ] Prepositional labels do not incorrectly group independent arguments
  • [ ] Value-preserving conversion initializers omit the first label
  • [ ] All non-special-case arguments have labels

Naming Semantics

  • [ ] Mutating methods use imperative verb form
  • [ ] Nonmutating methods use -ed/-ing or noun form
  • [ ] Mutating/nonmutating pairs follow the correct pattern (verb pair or noun/form-noun pair)
  • [ ] Boolean properties read as assertions (isEmpty, isValid, contains)
  • [ ] Variables and parameters are named by role, not type

Documentation

  • [ ] Every public declaration has a doc comment
  • [ ] Summaries are single sentence fragments ending in a period
  • [ ] Summaries describe the correct thing per declaration kind (action, access, creation, entity)
  • [ ] Non-O(1) computed properties document their complexity
  • [ ] Parameters, return values, a

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars1.1k
CategoryContent
Updated3mo ago
Forks58

Languages

Python

Trust signals

86/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

1 medium1 info
swift-api-design-guidelines — Universal Skill: Install & Safety Check | SkillAgent