Claude Skill

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 nami

LLM Mart · 0 points · 0 0 0

Virus-scanned Reviewed automatically before listing.

Full trust report

Download wei18-apple-dev-skills-collaboration-skills_skills_skill-authoring-patterns-7ea7e61.zip · 8 KB

wei18/apple-dev-skills 18 0 forks MIT Updated 11d ago

Part of wei18/apple-dev-skills — 37 skills

Install

skills CLI npx skills add https://github.com/wei18/apple-dev-skills/tree/main/collaboration-skills/skills/skill-authoring-patterns

Claude Code

claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install wei18-apple-dev-skills@llmmart

Git git clone https://github.com/wei18/apple-dev-skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole wei18/apple-dev-skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

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.

Files (apple-dev-skills)

references

listing-budget.md 4.5 KB

# 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. Run `/skill-doctor` (≥ v2.1.252) or `/doctor` to see the actual per-session listing cost measured, rather than estimating it. ([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".

## Where this catalog stands against that budget

Measured total (an estimate — re-scan before quoting it; `mise run check` also prints each skill's `desc len`):

```
$ python3 - <<'EOF'
import re, glob
tot = 0; n = 0
for f in sorted(glob.glob('*/skills/*/SKILL.md')):
    fm = re.search(r'^---\n(.*?)\n---', open(f).read(), re.S).group(1)
    d = re.search(r'^description:\s*(.*?)(?=^\w[\w-]*:|\Z)', fm, re.S | re.M).group(1).strip()
    if d[0] == d[-1] and d[0] in "'\"": d = d[1:-1]
    tot += len(d); n += 1
print(f"skills={n} total_desc_chars={tot} avg={tot // n}")
EOF
skills=38 total_desc_chars=21953 avg=577
```

So the 38 first-party descriptions alone total ≈ 22k characters (2026-09-12 scan). On a 200k-token model the default 1% budget is ≈ 2,000 tokens ≈ 8,000 characters (4-chars-per-token rule of thumb) — this catalog by itself is close to 3× that before any other plugin's skills are counted, so on such a model the least-used skills here run with a bare name and never auto-route. On a 1M-context model the same 1% (≈ 40k chars) holds the whole catalog. The two truncations differ: budget overflow drops **whole** descriptions, least-used first; the per-entry 1,536-char cap cuts one entry from the end (hence "put the key use case first").

What each side can do about it:

- **Consumer**: raise `skillListingBudgetFraction` (`0.02` = 2%; `0.03` ≈ 24k chars on a 200k model — no longer enough for this catalog: a 2026-09-13 re-scan gives 23,044 description chars + 949 (bare) to 1,643 (plugin-prefixed) name chars ≈ 24.0k–24.7k, since the listing holds names as well as descriptions, so use `0.04` ≈ 32k chars) or set `SLASH_COMMAND_TOOL_CHAR_BUDGET` to a fixed character count; disable plugins you don't need via `/plugin`. `skillOverrides: "name-only"` does **not** help for this catalog — "Plugin skills are not affected by `skillOverrides`. Manage those through `/plugin` instead." ([Claude Code docs, Skills](https://code.claude.com/docs/en/skills))
- **Author (this repo)**: put the key use case in the first sentence, and treat every new skill as a permanent charge against the shared budget — see above.

`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 in `SKILL.md`). 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.

official-docs.md 1.3 KB

Official pages backing this skill's claims; read when verifying or updating a factual or version-sensitive claim.

| Page | URL | Backs |
|---|---|---|
| Extend Claude with skills | https://code.claude.com/docs/en/skills | Description section: `description` = what + when; `paths:` glob; `when_to_use` |
| Extend Claude with skills | https://code.claude.com/docs/en/skills#how-a-skill-gets-its-command-name | Naming section: a plugin skill's `name` sets the command's last segment; a personal/project skill's `name` is only a display label |
| All settings | https://code.claude.com/docs/en/settings-reference#skilllistingbudgetfraction | references/listing-budget.md: budget key; "drops the descriptions of the least-used skills" |
| Agent Skills | https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview | listing-budget.md 1,024-char limit; Level 3 resources "None until accessed" (why two-tier `references/`) |
| Skill authoring best practices | https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices | Two-tier depth: "Keep references one level deep from SKILL.md"; SKILL.md body under 500 lines |
| Specification | https://agentskills.io/specification | `name` "Must match the parent directory name" (backs the name==dir gate); reference files are loaded on demand |

SKILL.md 12.8 KB

---
name: skill-authoring-patterns
description: '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 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)

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

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.
- Official sources: when verifying or updating a factual or version-sensitive claim, read `references/official-docs.md`.

Comments (0)

No comments yet.

Reviews (0)

No reviews yet.

Claude Prompt

Tighten-my-prose editing prompt

Claude Skill

Adversarial code-review skill for Claude

Claude Workflow

Deep-research workflow (fan-out + verify)

Claude Skill

Conventional-commit writer for Claude