# swift-api-design-guidelines

Applies Apple's official Swift API Design Guidelines to codebases. It guides argument labels, naming conventions for mutating methods, and structured documentation comments.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 2800 installs · ★ 1237
- Author: dpearson2699
- License: LicenseRef-Unknown · policy=link-only · description only; the file stays with the author
- Source: https://github.com/dpearson2699/swift-ios-skills/tree/HEAD/skills/swift-api-design-guidelines/SKILL.md
- Updated: 2026-07-31
- HTML: https://affpapa.org/en/nevibecode/skills/swift-api-design-guidelines

## What it does

This skill guides developers through naming Swift functions, parameters, and types. It clarifies when to drop argument labels, how to integrate prepositions into call sites, and why mutating operations take imperative verbs like `sort()` while nonmutating copies take participles like `sorted()`.

A dedicated section covers documentation structure for public declarations. It expects summaries to state what a declaration creates or accesses, alongside symbol markup for parameters, errors, and algorithmic complexity. Because callers assume computed properties execute in O(1) time, the guidelines mandate explicit complexity notes for any property exceeding constant time.

Its scope centers strictly on naming ergonomics and call-site readability. When facing concurrency logic, deeper type-system mechanics, or linter configuration, the guide delegates to `swift-concurrency`, `swift-language`, or `swiftlint`.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add dpearson2699/swift-ios-skills --skill swift-api-design-guidelines -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/swift-api-design-guidelines/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/swift-api-design-guidelines/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add dpearson2699/swift-ios-skills --skill swift-api-design-guidelines -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/swift-api-design-guidelines/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add dpearson2699/swift-ios-skills --skill swift-api-design-guidelines -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/swift-api-design-guidelines/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install dpearson2699/swift-ios-skills swift-api-design-guidelines
```

2. **Manually: put the files in place**
- File: `.github/skills/swift-api-design-guidelines/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add dpearson2699/swift-ios-skills --skill swift-api-design-guidelines -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/dpearson2699/swift-ios-skills --path skills/swift-api-design-guidelines
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/swift-api-design-guidelines/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add dpearson2699/swift-ios-skills --skill swift-api-design-guidelines -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/dpearson2699/swift-ios-skills/tree/HEAD/skills/swift-api-design-guidelines/SKILL.md

## When to use it
- choose argument labels that read naturally at the call site
- name mutating and nonmutating method pairs following standard grammar patterns
- write documentation comments with parameter tags and return descriptions
- mark algorithmic complexity on computed properties that exceed O(1)

## Example prompts
- Review this Swift method signature and verify argument labels against the API guidelines.
- Help me choose a nonmutating name for an operation that modifies a custom collection.
- Draft a documentation comment for a computed property with O(n) complexity.

## Similar
- [swift-api-design-guidelines-skill](https://affpapa.org/en/nevibecode/skills/swift-api-design-guidelines-skill.md) — skill · 1200 installs
- [kotlin-api-design](https://affpapa.org/en/nevibecode/skills/kotlin-api-design.md) — skill · 949 installs
- [axiom-swift](https://affpapa.org/en/nevibecode/skills/axiom-swift.md) — skill · 1200 installs
- [swift-development](https://affpapa.org/en/nevibecode/skills/swift-development.md) — skill · 488 installs
- [guide-swift-concurrency](https://affpapa.org/en/nevibecode/skills/guide-swift-concurrency.md) — skill · 431 installs
- [public-api-design-review](https://affpapa.org/en/nevibecode/skills/public-api-design-review.md) — skill · 7800 installs

From the same set: [dpearson2699/swift-ios-skills](https://affpapa.org/en/nevibecode/by/dpearson2699/swift-ios-skills.md) — 86 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md