Swift API Design Guidelines Skill

Expert guidance for any AI coding tool that supports the Agent Skills open format - focused on Swift API naming, argument labels, terminology, documentation comments, and conventions.

This repository distills the Swift API Design Guidelines into actionable, concise references for agents and code review workflows.

Who this is for

• Teams designing or reviewing Swift APIs and SDK surfaces
• Developers refactoring existing APIs for clarity at the point of use
• Anyone who wants APIs that read fluently and reduce ambiguity in call sites

How to Use This Skill

Option A: Using skills.sh (recommended)

Install this skill with a single command:

npx skills add https://github.com/Erikote04/Swift-API-Design-Guidelines-Agent-Skill --skill swift-api-design-guidelines-skill

Then use the skill in your AI agent, for example:

Use the swift-api-design-guidelines skill and review this code for naming, argument labels, and API clarity.

Option B: Claude Code Plugin

Personal Usage

To install this skill for your personal use in Claude Code:

1. Add the marketplace:

/plugin marketplace add Erikote04/Swift-API-Design-Guidelines-Agent-Skill

2. Install the skill:

/plugin install swift-api-design-guidelines@swift-api-design-guidelines-skill

Project Configuration

To automatically provide this skill to everyone working in a repository, configure .claude/settings.json:

{
  "enabledPlugins": {
    "swift-api-design-guidelines@swift-api-design-guidelines-skill": true
  },
  "extraKnownMarketplaces": {
    "swift-api-design-guidelines-skill": {
      "source": {
        "source": "github",
        "repo": "Erikote04/Swift-API-Design-Guidelines-Agent-Skill"
      }
    }
  }
}

When team members open the project, Claude Code will prompt them to install the skill.

Option C: Manual install

1. Clone this repository.
2. Install or symlink the swift-api-design-guidelines-skill/ folder following your tool's official skills installation docs.
3. Use your AI tool as usual and ask it to use the swift-api-design-guidelines skill for API design tasks.

Where to Save Skills

Follow your tool's official documentation:

• Codex: Where to save skills
• Claude: Using Skills
• Cursor: Enabling Skills

How to verify:

• Your agent should reference workflows/checklists in swift-api-design-guidelines-skill/SKILL.md
• It should then load the relevant file from swift-api-design-guidelines-skill/references/ for topic-specific guidance

What This Skill Offers

This skill gives your AI coding tool practical guidance for Swift API design. It can:

Guide API Design Decisions

• Improve naming clarity at the point of use
• Apply argument-label rules based on grammar and meaning
• Enforce consistent mutating/nonmutating naming pairs
• Improve terminology use and reduce ambiguity

Improve API Documentation

• Produce concise, useful declaration summaries
• Apply recognized symbol markup (Parameter, Returns, Throws, Note, etc.)
• Encourage documentation that matches actual API semantics

Strengthen API Review Quality

• Catch overloaded APIs that become ambiguous with weak typing
• Flag redundant type words and role-unclear identifiers
• Encourage defaults and parameter ordering that improve readability

What Makes This Skill Different

Non-opinionated: Focuses on API correctness and clarity, not architecture or folder structures.

Guidelines-first: Anchored in Swift API Design Guidelines semantics and established conventions.

Practical and concise: Optimizes for real review and implementation workflows, not theoretical style debates.

Skill Structure

swift-api-design-guidelines-skill/
  SKILL.md
  references/
    argument-labels.md - Rules for first-argument labels, grammar, and conversion cases
    fundamentals.md - Core priorities and documentation-comment principles
    general-conventions.md - Complexity docs, casing, free-function exceptions, overload conventions
    parameters.md - Parameter naming, defaults, ordering, and file literal guidance
    promote-clear-usage.md - Naming clarity, omitted words, and role-based identifiers
    special-instructions.md - Tuple/closure naming and weak-type overload disambiguation
    strive-for-fluent-usage.md - Fluent call-site phrasing and mutating/nonmutating naming pairs
    use-terminology-well.md - Terms of art, abbreviations, and precedent

Contributing

Contributions are welcome! This repository follows the Agent Skills open format, which has specific structural requirements.

Please read CONTRIBUTING.md for:

• How to contribute improvements to SKILL.md and the reference files
• Format requirements and quality standards
• Pull request process

About the author

Created by Erik Sebastian de Erice Jerez.

License

This skill is open-source under the MIT License. See LICENSE for details.