# Skill Authoring Patterns

> The Apple/Swift-and-this-catalog layer for authoring or reviewing a SKILL.md, on top of superpowers:writing-skills. Use when writing or CR-ing a skill for this repo, wording a description so it routes precisely, splitting a skill into references/, or choosing granularity and naming. Adds: precision-router descriptions with framework API names, the Common-Mistakes + Review-Checklist bookends, two-tier references/, the Rationale/Deviation convention, evidence-based multi-reviewer CR. Does NOT cover general skill discipline (TDD-for-skills, when-not-to-create, token budgets) → superpowers:writing-skills.

- Skill: `wei18/skill-authoring-patterns` (Agent Skill)
- Install (CLI): `npx skillmds@latest add wei18/skill-authoring-patterns`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wei18/skill-authoring-patterns/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: wei18 (https://skillmd.com/u/wei18)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/wei18/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](https://code.claude.com/docs/en/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:

| 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. | 25/38 (incl. the older prose form) |

- **`## 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)

```markdown
---
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`.