Write, review, or improve Swift APIs using Swift API Design Guidelines for naming, argument labels, documentation comments, terminology, and general conventions. Use when designing new APIs, refactoring existing interfaces, or reviewing API clarity and fluency.
name: swift-api-design-guidelines-skill
description: Write, review, or improve Swift APIs using Swift API Design Guidelines for naming, argument labels, documentation comments, terminology, and general conventions. Use when designing new APIs, refactoring existing interfaces, or reviewing API clarity and fluency.
Swift API Design Guidelines Skill
Overview
Use this skill to design and review Swift APIs that are clear at the point of use, fluent in call sites, and aligned with established Swift naming and labeling conventions. Prioritize readability, explicit intent, and consistency across declarations, call sites, and documentation comments.
Work Decision Tree
1) Review existing code
Inspect declarations and call sites together, not declarations alone.
Check naming clarity and fluency (see references/promote-clear-usage.md, references/strive-for-fluent-usage.md).
Check argument labels and parameter naming (see references/parameters.md, references/argument-labels.md).
Check documentation comments and symbol markup (see references/fundamentals.md).
Check conventions and overload safety (see references/general-conventions.md, references/special-instructions.md).
2) Improve existing code
Rename APIs that are ambiguous, redundant, or role-unclear.
Refactor labels to improve grammatical call-site reading.
Replace weakly named parameters with role-based names.
Resolve overload sets that become ambiguous with weak typing.
Strengthen documentation summaries to describe behavior and returns precisely.
3) Implement new feature
Start from use-site examples before finalizing declarations.
Choose base names and labels so calls read as clear English phrases.
Add defaults only when they simplify common usage.
Define mutating/nonmutating pairs with consistent naming.
Add concise documentation comments for every new declaration.
Core Guidelines
Fundamentals
Clarity at the point of use is the top priority.
Clarity is more important than brevity.
Every declaration should have a documentation comment.
Summaries should state what the declaration does, returns, accesses, creates, or is.
Use recognized Swift symbol markup (Parameter, Returns, Throws, Note, etc.).
Promote Clear Usage
Include all words needed to avoid ambiguity.
Omit needless words, especially type repetition.
Name parameters and associated types by role, not type.
Add role nouns when type information is weak (Any, NSObject, String, Int).
Strive For Fluent Usage
Prefer method names that produce grammatical, readable call sites.
Start factory methods with make.
Name side-effect-free APIs as noun phrases; side-effecting APIs as imperative verbs.