modern-swift-api-design

Use when designing or reviewing Swift protocols, generics, `some`/`any`, enums, domain types, associated types, typed throws, or public API resilience. Do not invoke for a local implementation change with no API decision.

Jump to install

Repository: christopherkarani/Agent-Skills
Last source activity: August 26, 2026 at 22:10
Detected SKILL.md language: English
Stars: 0
Forks: 0

Install options

The review-first prompt is selected by default. You can switch to a direct command or download a local copy.

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

A direct command skips the review prompt. Inspect the source before running it.

npx skills add https://github.com/christopherkarani/Agent-Skills --skill modern-swift-api-design

The command stays on one line. Scroll horizontally to inspect it before copying.

Prefer a local copy? Download the files currently available to SkillsMP.

Review the source files

Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.

File Explorer

4 files

SKILL.md

Source instructions · Read-only preview

Back to search Back to installation

Modern Swift API design

Preserve relationships in the type system and introduce abstraction only for a demonstrated boundary.

Procedure

State who chooses the concrete type: the implementation, the caller, or runtime data. This determines concrete types, opaque types/generics, or existentials.

Model the domain states and invalid combinations. Prefer an enum or constrained value over correlated booleans and stringly typed cases.

Decide the boundary's resilience, specialization, and heterogeneity requirements. Start concrete; use some when one hidden type is returned, generics when a relationship must be preserved, and any when heterogeneous runtime values are required.

Define protocol requirements around capabilities, not the current implementation. Do not create a protocol solely for mocking or to hide one private type.

Keep errors untyped by default. Use typed throws only for a stable closed error contract, generic error preservation, or a proven constrained environment.

Compile client-like examples, including inference, error handling, and the intended evolution point.

Guardrails

any P erases relationships; do not use it where two values must share an associated type or generic parameter.

some P hides one concrete type; it does not mean “any conformer” and is not a universal abstraction marker.

A primary associated type improves constraints but does not remove the need to reason about identity and type relationships.

Public API choices include source, ABI, and resilience consequences. Check library-evolution requirements before changing a shipped signature.

Typed throws is additive precision, not a mandate to convert every throws declaration.

Read references/type-choice-guide.md for the decision table and review traps. Use the compiler to validate inference rather than relying on remembered syntax.

Completion contract

Report the caller/implementation choice, the abstraction boundary, the invalid states excluded, the error contract, and client-facing proof.