skills.rest
OMIXEC
OMIXECCOMMUNITY
Explore all skills by this author →
GitHub

swift-api-design-guidelines-skill

Review and improve Swift API naming, argument labels, and documentation comments.

1|Updated Aug 9, 2026
Search Tags:#code review#refactoring#api design#swift#naming conventions#argument labels#documentation comments
One-click install
npx skills add https://github.com/OMIXEC/all-in-one-swift-skills --skill swift-api-design-guidelines-skill-omixec
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: swift-api-design-guidelines-skill
Source: https://github.com/OMIXEC/all-in-one-swift-skills/tree/main/skills/swift-api-design-guidelines-skill
Command: npx skills add https://github.com/OMIXEC/all-in-one-swift-skills --skill swift-api-design-guidelines-skill-omixec

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Swift APIs often suffer from ambiguous names, redundant words, inconsistent argument labels, and missing documentation comments, making call sites hard to read and maintain. This Skill applies the official Swift API Design Guidelines to design, review, and refactor public API surfaces for clarity at the point of use. ## Core Features & Use Cases - API Review Workflow: Inspect declarations and call sites together using a structured decision tree covering naming, labels, documentation, and overload safety. - Naming and Fluency Rules: Apply conventions for mutating/nonmutating pairs, factory methods, Boolean assertions, and grammatical call-site phrasing. - Argument Label and Documentation Guidance: Enforce first-argument label rules, default parameter placement, and documentation comment standards with symbol markup. - Use Case: When refactoring a Swift package's public interface, use this Skill to rename ambiguous methods, fix argument labels so calls read as English phrases, and add documentation summaries to every declaration. ## Quick Start Review my Swift API in this file and suggest naming, argument label, and documentation improvements following the Swift API Design Guidelines.

Frequently Asked Questions about swift-api-design-guidelines-skill

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I name Swift methods according to the API Design Guidelines?▼

Name side-effect-free APIs as noun phrases and side-effecting APIs as imperative verbs. Keep mutating/nonmutating pairs consistent, such as sort and sorted or formUnion and union, and start factory methods with make.

How to choose argument labels in Swift functions?▼

Omit the first label when the argument forms a grammatical phrase with the base name, like addSubview. Include the label when the first argument is part of a prepositional phrase, and label all remaining arguments unless omission is clearly justified.

What should a Swift documentation comment include?▼

Every declaration should have a summary describing what it does and returns, what it accesses, creates, or is. Use recognized symbol markup such as Parameter, Returns, Throws, and Note, and document complexity for computed properties that are not O(1).

When should I use default parameter values in Swift APIs?▼

Use default values when one value covers the common case, preferring a single method with defaults over a family of overloads with shared semantics. Place defaulted parameters near the end of the parameter list.

Why are my Swift overloads ambiguous at call sites?▼

Overloads become ambiguous when they rely on weak types like Any or unconstrained generics, or differ only by return type. Disambiguate with explicit naming, such as append versus append(contentsOf:), so intent is clear at the call site.

Related Skills

Explore More Software Engineering Skills→
Roy-wonjiRoy-wonji

swift-api-design-guidelines-skill

Align Swift API naming, argument labels, and documentation with design guidelines.

Community
Intermediate
FelixRauchFelixRauch

swiftlint

Enforce Swift style and convention compliance via configurable lint rules.

Community
Advanced
jikig-aijikig-ai
12

semgrep-sast

Scan git-diff-selected source files with semgrep for vulnerability patterns.

Official
Intermediate
KuassKuass
1

swiftui-expert-skill

Review SwiftUI code for state management, performance, and modern APIs.

Community
Advanced