CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

swift-api-design-guidelines

Apply Swift API Design Guidelines to name, label, and document Swift APIs. Covers argument label rules (prepositional phrase rule, grammatical phrase rule, first-label omission), mutating/nonmutating pair naming (-ed/-ing participle pattern, form- prefix, sort/sorted, formUnion/union), side-effect naming (noun for pure, verb for mutating), documentation comment structure (summary by declaration kind, O(1) complexity rule), clarity at call site, role-based naming, protocol naming (-able/-ible/-ing), default arguments over method families, casing conventions, and terminology. Use when designing new Swift APIs, reviewing naming and argument labels, writing documentation comments, or refactoring for call site clarity.

Quality

97%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

The canonical home for this skill is dpearson2699/swift-ios-skills

SKILL.md
Quality
Evals
Security

Quality

Content

92%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A well-engineered skill body: actionable tables and GOOD/BAD examples, explicit decision procedures, excellent one-level-deep progressive disclosure with real reference files, and a verification checklist. The only weakness is token redundancy — the Review Checklist and TOC largely restate content already present, which costs tokens without adding new guidance.

Suggestions

Trim or compress the Review Checklist (lines 272-299) so each item is a short verification cue rather than a restatement of the rule, or move the full checklist into a reference file and keep a pointer plus category headers in SKILL.md.

Remove the 10-line Contents table of contents; the section headings are already self-describing and the list duplicates them token-for-token.

The two similar remove(at:) GOOD/BAD pairs in the Clarity section (lines 145-161) illustrate nearly the same point — merge them into one example pair and keep only one differing one.

DimensionReasoningScore

Conciseness

The body is dense with rules and GOOD/BAD examples and never explains basics Claude already knows, but there is trimmable redundancy: the ~28-line Review Checklist ("First argument follows the correct label rule…", "Mutating methods use imperative verb form") restates rules already stated in the preceding sections, and the Contents TOC duplicates section headers. This fits the score-4 anchor (efficient, minor instances that could be trimmed) rather than 5, whose "every token earns its place" standard the checklist duplication violates; it is well above 3 because there is no padded or unnecessary explanation.

4 / 5

Actionability

Guidance is fully concrete: decision tables with specific examples ("Omit label, merge words into base name | addSubview(y)"), copy-paste-ready Swift snippets for every rule ("array.sort()", "employees.remove(at: position)"), GOOD/BAD contrast pairs, and explicit decision procedures ("Apply the first matching row"). This matches the score-5 anchor (specific examples cover the common cases) and exceeds score 4 because no key detail is left abstract.

5 / 5

Workflow Clarity

The skill defines clear execution structure for a single-purpose review/design task: routing guidance at the top ("route language/type-system work to swift-language…"), a precedence-ordered decision table ("Apply the first matching row"), per-section "Load … when …" conditions, and a grouped Review Checklist (Argument Labels, Naming Semantics, Documentation, Conventions) that serves as explicit verification checkpoints. Per the simple-skill exception, the single action is unambiguous and checkpoints are present, so it meets the score-5 anchor rather than 4; no destructive or batch operations exist that would impose a cap.

5 / 5

Progressive Disclosure

Structure is exemplary: core rules inline in SKILL.md, four verified one-level-deep reference files (argument-labels-and-parameters.md, naming-and-clarity.md, side-effects-and-mutating-pairs.md, conventions-and-special-rules.md) each linked from its own section with a load condition ("Load [Argument Labels and Parameters]… when resolving abstraction boundaries…") and summarized again in a References section. All referenced paths and the -ed/-ing decision-tree anchor resolve to real files, and no reference nests further references, matching the score-5 anchor exactly.

5 / 5

Total

19

/

20

Passed

Description

100%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

An excellent description: specific, comprehensive, in third person, with explicit and natural use-when triggers covering the design/review/refactor lifecycle of Swift API work. It clearly distinguishes this skill from adjacent Swift-language or tooling skills.

DimensionReasoningScore

Specificity

The description lists multiple specific concrete actions with comprehensive coverage: "name, label, and document Swift APIs" plus enumerated sub-capabilities such as "prepositional phrase rule", "-ed/-ing participle pattern, form- prefix, sort/sorted, formUnion/union", "O(1) complexity rule", and "default arguments over method families". It clearly matches the score-5 anchor (multiple specific concrete actions, comprehensive) rather than score 4 (minor gaps in coverage), as no significant guideline area is omitted.

5 / 5

Completeness

Both questions are answered explicitly and concretely: the "what" is the detailed capability enumeration ("Covers argument label rules… mutating/nonmutating pair naming… side-effect naming…"), and the "when" is the explicit clause "Use when designing new Swift APIs, reviewing naming and argument labels, writing documentation comments, or refactoring for call site clarity". This matches the score-5 anchor verbatim in structure; it is not score 4 because the when-clause is fully specific rather than improvable.

5 / 5

Trigger Term Quality

Natural trigger phrases a user would actually say are comprehensively covered: "designing new Swift APIs", "reviewing naming and argument labels", "writing documentation comments", "refactoring for call site clarity", plus synonyms like "naming", "casing conventions", "documentation comment". It sits at the score-5 anchor rather than 4 because the phrasing spans the full range of natural user requests for this domain with no notable missing synonyms (file extensions do not apply to a non-file skill).

5 / 5

Distinctiveness Conflict Risk

The description occupies a clear niche (Swift API design guidelines) with distinct triggers like "argument labels", "mutating/nonmutating pair naming", and "Swift APIs". It is narrowly scoped to API naming/labeling/documentation rather than general Swift language work, so conflict risk with adjacent skills (e.g., general Swift language or lint skills) is minimal — matching the score-5 anchor, not score 4's "minor overlap risk with closely related skills".

5 / 5

Total

20

/

20

Passed

Validation

100%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository

dpearson2699/swift-ios-skills

Path

skills/swift-api-design-guidelines/SKILL.md

Reviewed

Table of Contents

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.