Skill Authoring Patterns

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

Claude Code loads a listing of every skill's name + description into context on every session so the model knows what's available; the listing's character budget scales at 1% of the model's context window (raise it with the skillListingBudgetFraction setting or the SLASH_COMMAND_TOOL_CHAR_BUDGET env var). Each entry's own description (+ when_to_use, if present — see below) is separately capped at 1,536 characters regardless of that budget (skillListingMaxDescChars). When the total listing overflows the budget, Claude Code truncates descriptions starting with the skills you invoke least — your most-used skills keep their full text, your least-used ones lose theirs first. (Claude Code docs, Skills)

The practical implication for this catalog: the scarce resource is not "can my one description fit" — this catalog already runs DESC_MAX = 800 in scripts/check-consistency.py, deliberately tighter than the official 1,536-char cap (and also under the 1,024-char hard limit the platform Agent Skills spec enforces for claude.ai / Skills API uploads), precisely because 38 skills' descriptions compete for one shared budget every session. Every new skill's description is a permanent tax on that shared budget, paid on every session regardless of whether the skill ever fires. 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".

when_to_use is a real frontmatter field (appended to description in the listing and counted toward the same 1,536-char cap) meant for trigger phrases / example requests. None of this catalog's 38 skills declares when_to_use in frontmatter (grep -l '^when_to_use:' **/SKILL.md → 0 hits; a plain grep -rl when_to_use also matches this paragraph's own mention of the field name, so target the frontmatter line specifically) — this catalog folds trigger phrasing directly into description instead (see the router form above). That's a deliberate, not accidental, choice: keeping trigger wording in one field is simpler to audit against DESC_MAX than splitting it across two fields that share a cap.

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:

• ## 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 lock-vs-actor guide, read references/synchronization.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. (Note: this is more than tooling hygiene — in a plugin skill, which is how every skill in this catalog ships, frontmatter name sets the command's last segment (/plugin:name), so a name ≠ directory mismatch silently renames the command a user types. Only for a personal/project skill does Claude Code derive the command from the directory and treat name as a mere label. Our gate keeps both paths identical.)
• 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 (real cases: a reviewer "corrected" an iPhone-14-Pro size that was already right; another pushed a deprecated CLI form).

Common Mistakes

1. Vague one-line description — the agent can't route to it. Use the precision-router form with API names.
2. No negative boundary on a skill that can over-fire — it produces unwanted artifacts.
3. Description as summary, not router — it restates the body instead of naming trigger conditions.
4. No scope-boundary line — two adjacent framework skills both claim the same request.
5. Decisions buried in prose instead of a table/triage when the agent must choose a path.
6. Deep reference material inlined into SKILL.md, bloating always-in-context cost — move to references/.
7. Generic Common-Mistakes ("write good code") instead of concrete, anti-pattern-named items.
8. Project-specific workaround presented as general guidance (e.g. "avoid .task, our build has bug #361") — ships wrong advice to every consumer.
9. 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.

Provenance

The structural patterns (router descriptions, bookend sections, two-tier references, naming) were distilled by studying high-quality public Swift/Apple skill collections — methodology only, no content copied — and combined with this catalog's own Rationale/Deviation convention and an evidence-based multi-reviewer CR doctrine. General skill-authoring doctrine is intentionally delegated to superpowers:writing-skills.