Skill Authoring Patterns (Apple/Swift catalog layer)

This is a thin complement, not a replacement. For the general discipline of writing a skill — whether a skill should exist at all, the test-first / RED-GREEN loop, matching the guidance form to the failure mode, and word-count budgets — use superpowers:writing-skills first. This skill adds only what is specific to this catalog and to Apple/Swift framework skills: how to word descriptions so an agent routes to the right framework skill, the section conventions we standardize on, and how we review skills.

When to invoke

Writing a new SKILL.md for this repo (especially an Apple/Swift framework skill).
Reviewing / CR-ing a skill for invocation precision and execution quality.
A skill's description routes wrong (or over-fires); you're rewording it.
A skill grew long and you're deciding what to move into references/.
Choosing a new skill's name and granularity.

Scope

This skill owns the catalog-specific and Apple/Swift-specific authoring conventions below. It does not own: the decision to create a skill, test-first skill development, or general prose-economy rules — route those to superpowers:writing-skills. Distribution/packaging (plugin vs marketplace, discovery) → claude-skill-plugin-packaging.

Description as a precision router

The description is the only part of a skill that stays in the model's context by default (the body loads when the skill is invoked, and the description is length-capped). So spend its words on routing, not summary.

Where this differs from superpowers:writing-skills: that skill's description rule says to write ONLY the trigger ("Use when…"), never what the skill does, aiming for under 500 characters. Its evidence is real but narrower than the rule it's stated as: an agent that reads a description summarizing a workflow's steps will follow the description instead of the body (this catalog's own gate encodes the same boundary as the "description may summarize workflow" MINOR). The official Claude Code and Agent Skills docs, by contrast, specify description as covering both what the skill does and when to use it. This catalog follows the official contract: one verb-anchored capability sentence (the result, not the steps) + trigger scenarios + a negative boundary when needed. A capability statement ("Resolve Swift 6 concurrency errors…") is not a workflow summary, so writing one doesn't reproduce the failure mode superpowers is guarding against — it still never enumerates workflow steps or numeric thresholds in the description. This catalog's DESC_MAX (800 chars) is also independent of superpowers' <500-char target; both are stricter than the official 1,536-char listing cap for unrelated reasons.

Verb-anchored to observable intent: "Resolve Swift 6 concurrency errors…", "Audit SwiftUI runtime performance…".
Embed the framework symbols / APIs that should trigger it — Sendable, @MainActor, MetricKit, AccessibilityFocusState. This is the highest-leverage delta for framework skills: an agent routing on "I'm getting a Sendable error" only lands here if Sendable is in the description.
Chain trigger scenarios as a short list ("Use when … ; when … ; when …").
Add a negative boundary when over-firing is a real risk (e.g. "discussing screens" vs "generate a mockup") — name when NOT to fire.
If the trigger is really a file type (*.xcstrings, Package.swift), prefer the official paths: frontmatter over a prose file trigger — it takes glob patterns, and Claude then loads the skill automatically only when working with matching files. mise run check flags prose file-triggers as candidate for paths:.
Routing is the model's judgment, not literal string matching — write for a reader deciding "is this my situation?", not for a regex.

BAD:  description: Helps with accessibility.
GOOD: description: VoiceOver / Dynamic Type / touch-target implementation for SwiftUI & UIKit.
      Use when adding or auditing user-facing UI; when asked "make this accessible" / "VoiceOver
      doesn't read this" / "does this pass WCAG"; before an App Review a11y pass. Covers
      accessibilityLabel/value/hint/traits, Dynamic Type + minimumScaleFactor, 44pt targets.
      Does NOT cover deep Rotor/Focus APIs — see <sibling>.

The listing budget is catalog-wide, not per-skill

Every enabled skill's description is always-on context, shared by a catalog-wide budget, not a per-skill one — so before adding a skill, ask "is this trigger phrase worth permanently occupying part of every session's listing budget?", not just "does this description fit under 800 chars". For the exact mechanism (the 1% context-window budget, the 1,536-char per-entry cap, least-used-first truncation, the when_to_use field, and the measurement tools), read references/listing-budget.md.

Section conventions we standardize

Order the middle by the topic's pedagogy, but keep these conventions. All four bookends below are required for new skills; none of them are retrofitted onto pre-existing skills — the gaps in the "today" column are historical debt, not evidence the convention is optional:

Heading	Purpose	Retrofit status	Today (of 38 skills)
`## Rationale`	why this default was chosen. Unique to this catalog.	Not retrofitted	20/38
`## Deviation considerations`	when to override the default, and the cost (e.g. "Drop to iOS 18 when an existing user base still runs it — every Liquid Glass API then needs an availability guard, and the pre-26 chrome must be snapshot-tested separately"). Also ours.	Not retrofitted	22/38
`## Common Mistakes`	concrete, anti-pattern-named items ("Using `DateFormatter()` in `body`"), as many as are real — do not pad to a number.	Not retrofitted; older skills express this as inline anti-pattern sections instead.	10/38
`## Review Checklist`	a `- [ ]` list at the end, runnable top-to-bottom.	Not retrofitted; older skills use a prose `## Verification checklist` instead.	26/38 (incl. the older prose form; `mise run check`'s section matrix)

## Related skills — siblings by name.

Use a scope-boundary line in the body wherever a sibling is close ("owns X; does NOT own Y → route to <sibling>") — this is what stops two framework skills both claiming the same request.

Skeleton (assembled)

---
name: <kebab-matches-folder>
description: <precision router — see above>
---
# <Title>
<1-paragraph scope: what it implements/reviews + target version>
## When to invoke
## Scope            ← what it does NOT own → sibling
## <body: triage/workflow → decision table → rules → code>
## Rationale
## Deviation considerations
## Common Mistakes
## Review Checklist
## References        ← only if it has references/
## Related skills

Structure aids (use where they fit — not universal)

Lead with a triage/workflow ("Step 1 capture context → 2 smallest fix → 3 verify") for procedural skills. Skip it for pure reference/glossary skills — don't manufacture a procedure.
Front-load a decision table (situation→fix, or option/best-for/complexity) wherever the agent must choose a path before implementing.
Add a ## Contents TOC only for genuinely long skills that a reader jumps around in — not by default; for a short linear skill it just costs tokens.

Two-tier depth (references/)

Keep SKILL.md scannable: decision logic, short paired WRONG/RIGHT snippets (one point each), quick tables. Move long migrations, full API references, and big samples into references/*.md and point to them from SKILL.md with a plain instruction ("for the full guide, read references/<topic>.md"). This is a documentation convention — the agent reads those files via normal file reads when your SKILL.md tells it to; there is no automatic lazy-load. It keeps the always-in-context cost low while letting depth exist.

Naming & granularity

name is kebab-case; our consistency gate requires name to equal the directory (run mise run check) for clean cross-references and tooling. This is more than tooling hygiene: in a plugin skill — how every skill in this catalog ships — a name ≠ directory mismatch silently renames the command a user types; that's the failure our gate exists to block. For exactly how Claude Code derives a skill's command name in each install path, read references/official-docs.md.
One surface area per skill. First-party skills in this catalog use a "topic + stance" compound name — storekit2-iap-defaults, swift6-concurrency, swiftui-navigation-architecture, cloudkit-schema-source-of-truth — rather than the bare Kit name. Bare Kit names (widgetkit, storekit, swift-concurrency) are already taken by the aggregated apple-skills plugin, so the compound name is also what keeps the two catalogs from routing to the same command. For cross-cutting topics use a descriptive compound at the right altitude — swiftui-navigation-architecture, not the too-broad swiftui nor the too-narrow swiftui-observable.

Reviewing a skill (CR)

When you CR a skill or a batch, apply the evidence-based, multi-lens doctrine (it caught real errors in this catalog):

Diverse lenses, not one reviewer — for a batch, dispatch reviewers with distinct expertise (correctness, a11y, security, performance, skill-authoring). Different lenses catch what redundancy can't.
Evidence for every falsifiable claim — a reviewer flagging "this API/version is wrong" cites the source (Apple docs / Swift Evolution / WCAG), not "looks off"; each lists "what I did NOT verify + confidence".
Reviewers can be wrong → the Leader adjudicates — don't take the union on faith. Verify disputed falsifiable claims yourself before accepting or overruling.

Common Mistakes

Vague one-line description — the agent can't route to it. Use the precision-router form with API names.
No negative boundary on a skill that can over-fire — it produces unwanted artifacts.
Description as summary, not router — it restates the body instead of naming trigger conditions.
No scope-boundary line — two adjacent framework skills both claim the same request.
Decisions buried in prose instead of a table/triage when the agent must choose a path.
Deep reference material inlined into SKILL.md, bloating always-in-context cost — move to references/.
Generic Common-Mistakes ("write good code") instead of concrete, anti-pattern-named items.
Project-specific workaround presented as general guidance (e.g. "avoid .task, our build has bug #361") — ships wrong advice to every consumer.
Stale/unverified API or version claim — cite the source; a wrong version gate emits needless #available guards or won't compile.

Review Checklist

(General discipline per superpowers:writing-skills, except its description rule — see §Description as a precision router.)
name equals the directory; mise run check passes.
description is router form: verb-anchored, embeds the triggering framework APIs, lists trigger scenarios; a negative boundary if it could over-fire.
A scope-boundary line names what the skill does NOT own and routes to the sibling.
Choices the agent must make are in a table/triage, not prose.
Deep material is in references/*.md with an in-body pointer; SKILL.md stays scannable.
(New skills) Rationale + Deviation present; code uses current APIs with version gates marked inline.
Common Mistakes are concrete and anti-pattern-named; no padding.
No project-specific workaround dressed up as general guidance.
Every falsifiable API/version claim spot-checked against an authoritative source (cite it).

Related skills

superpowers:writing-skills — read first for the general discipline this skill deliberately does not repeat.
claude-skill-plugin-packaging — packaging/distribution/discovery of the authored skill.
subagent-review-cycles — the round structure the evidence-based CR plugs into.
Official sources: when verifying or updating a factual or version-sensitive claim, read references/official-docs.md.

skill-authoring-patterns

Files3

SKILL.mdcollaboration-skills/skills/skill-authoring-patterns/SKILL.md