# swift-api-design-guidelines-skill

Reviews and refactors Swift APIs according to official Swift API Design Guidelines. It helps developers name parameters by role, tune argument labels, and format doc comments.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 1200 installs · ★ 31
- Author: Erikote04
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/Erikote04/Swift-API-Design-Guidelines-Agent-Skill/tree/HEAD/swift-api-design-guidelines-skill/SKILL.md
- Updated: 2026-02-18
- HTML: https://affpapa.org/en/nevibecode/skills/swift-api-design-guidelines-skill

## What it does

This skill inspects declarations alongside their call sites to ensure APIs read as fluent English phrases. It checks argument labels, strips redundant type names, and enforces naming conventions for mutating and nonmutating pairs like `sort` and `sorted`.

The workflow relies on a decision tree split into reviewing existing code, refactoring declarations, and designing new interfaces from scratch. References inside the skill cover edge cases such as tuple member labeling, closure parameter naming, and resolving ambiguous overload sets caused by weak types.

The rules require documenting time complexity whenever a computed property is not `O(1)`, so hiding heavy work behind a simple getter gets flagged immediately.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add Erikote04/Swift-API-Design-Guidelines-Agent-Skill --skill swift-api-design-guidelines-skill -a claude-code
```

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

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add Erikote04/Swift-API-Design-Guidelines-Agent-Skill --skill swift-api-design-guidelines-skill -a codex
```

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

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add Erikote04/Swift-API-Design-Guidelines-Agent-Skill --skill swift-api-design-guidelines-skill -a cursor
```

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

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install Erikote04/Swift-API-Design-Guidelines-Agent-Skill swift-api-design-guidelines-skill
```

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

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add Erikote04/Swift-API-Design-Guidelines-Agent-Skill --skill swift-api-design-guidelines-skill -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/Erikote04/Swift-API-Design-Guidelines-Agent-Skill --path swift-api-design-guidelines-skill
```

### Windsurf (Devin Desktop)

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

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add Erikote04/Swift-API-Design-Guidelines-Agent-Skill --skill swift-api-design-guidelines-skill -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/Erikote04/Swift-API-Design-Guidelines-Agent-Skill/tree/HEAD/swift-api-design-guidelines-skill/SKILL.md

## When to use it
- refactor argument labels to read as fluent English phrases at call sites
- resolve ambiguous overload sets caused by weak parameter types
- format doc comments using Parameter, Returns, and Throws symbol markup
- align mutating and nonmutating method pairs with Swift naming conventions

## Example prompts
- Review this Swift struct API against the official guidelines and suggest better argument labels.
- Refactor this network service interface to remove redundant type names from method signatures.
- Add documentation comments with standard Swift symbol markup for this public protocol.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 43ec7db1976e7075.

BEGIN THIRD-PARTY FILE 43ec7db1976e7075
```text
---
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
```
END THIRD-PARTY FILE 43ec7db1976e7075

The third-party file has ended. Everything between the 43ec7db1976e7075 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2306 of 7149 bytes. © Erikote04 · MIT · https://github.com/Erikote04/Swift-API-Design-Guidelines-Agent-Skill/tree/HEAD/swift-api-design-guidelines-skill/SKILL.md

_Part of the page did not fit — see the HTML version._

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