---
name: skills-writer
description: Creates and updates skill files (.claude/skills/*/SKILL.md). Triggers: creating/updating a skill, documenting a subsystem for agent context.
---

# Skills Writer

## Mental Model

A skill is **a map and a list of landmines**, not an encyclopedia. It points an agent at the right code and docs and warns about what isn't obvious from reading them. If a fact already lives in source or the docs site, **link, don't restate**.

A good skill answers three things and stops: **where** the relevant code/docs live, **what gotchas** aren't obvious from reading them, and **what patterns** recur. Default to prose-free pointers and tables; include code only when the snippet is a pattern that can't be conveyed by pointing at a file. Every line is re-read into context on every load, so a skill that says *less* but points *accurately* beats a thorough one.

## Growing a Skill — Damped Response

A skill is rarely written whole; it grows as questions pull on it. Two **independent axes** govern what a pull adds — conflating them is the most common way this section gets misapplied.

**Axis 1 — coverage: how much of the answer's territory you write down.** This is what "damped" governs. Picture the skill as an object resting in sand: a question pulls it toward a fuller answer, it moves **damped** (covers part of the conceptual ground, not all) and **retains** that position — the sand doesn't snap back. Repeated pulls settle the skill at the *average* of real demand instead of overfitting to one question. **Default: a 100% pull moves ~20%** — add only the one signpost that would have shortest-circuited the problem (the file/class/relationship to check first, plus a one-sentence shape of the answer), not the walkthrough or the second-order cases. A genuinely recurring question reaches full coverage over a few pulls; a one-off never bloats the skill past its signpost.

Why damped: chasing every specific detail into the skill bloats it, scatters its focus, and front-loads context future agents won't need — most questions are one-offs.

**Axis 2 — prose density: always terse, at every coverage level.** Independent of axis 1; never relaxes, not even for a full-coverage landmine. State each fact once — no restating the same point from a second angle. Skip examples unless the pattern truly can't be conveyed by naming the file/symbol. Omit narrated history (see "War stories" under Exclude) and anything a reader can derive from the code you're pointing at. A landmine written at full axis-1 coverage should still read as tight rule-plus-consequence, not a paragraph.

**Example — same gotcha, axis 1 held constant, axis 2 fixed:**

Bad (states the same thing twice): *"Animation frames don't always drive the Sprite's color directly — some channels fall back to a default unless a frame explicitly sets them. Assuming every frame controls color can therefore misread a null channel as intentional, since it's silently skipped instead of applied."*

Good (one pass, no restatement): *"`Sprite.UpdateToAnimationFrame` applies color per-channel and skips any channel left null on the frame — check for nulls before assuming a frame drives full color."*

**Two exceptions to axis 1's damping — place these by hand, at full coverage, not through the elastic:**

1. **Landmines.** A non-obvious, expensive-to-rediscover gotcha that *isn't* evident from the source you point at is a sharp fact, not a sample to be averaged. Write the whole gotcha: what triggers it, what breaks, what to check. (This is the "list of landmines" half of the mental model above.)
2. **Bimodal pull.** When a skill is dragged toward a low-density middle between two genuinely distinct sub-topics, don't settle in the valley — it serves neither. Split into two skills, each with its own focus. A pull toward the empty middle *is* the signal to fission.

**Signpost quality bar.** A nudge must name *where to look* — a file, class, or relationship — not merely assert that something exists. "Animation frames interact with the Sprite" raises a question without reducing search cost; "see `Sprite.UpdateToAnimationFrame` — color is applied there, gated on null per-frame channels" reduces it. A vague signpost is worse than none: it costs context and resolves nothing.

## Authoritative Sources (do not duplicate)

Before writing anything, identify where the ground truth already lives:

- **Source code** — class outlines, property lists, method signatures, call sites.
- **The docs site** ([docs.flatredball.com](https://docs.flatredball.com)) — user-facing behavior, engine APIs, Glue reference, tutorials. If a topic has a docs page, link to it rather than restating it. (The docs are hosted GitBook, not checked into this repo.)
- **Other skills** — cross-reference instead of copying. When two skills cover a shallow-vs-deep split of the same topic, point between them rather than duplicating the overlap.

## Process

1. Read the relevant source files.
2. Check [docs.flatredball.com](https://docs.flatredball.com) for an existing user-facing page on the topic — link it instead of restating.
3. Skim a few existing skills in `.claude/skills/` to match style and depth.
4. Write only the non-obvious distillation.
5. Before saving, re-read every sentence you just added — against each other **and** against existing sections you didn't touch: does it restate a nearby sentence from a different angle, include an example that a file/symbol pointer would replace, or narrate history instead of stating a timeless rule? Cut what fails.

## Skill File Rules

- **Length**: not a target — a byproduct. The damped-response process above is what keeps a skill short: most edits are ~20% pulls (a signpost, not a walkthrough), so length only grows where demand genuinely, repeatedly pulls. Don't pad toward a line count, and don't treat headroom under a number as license to add more than the current pull warrants. Hard ceiling 500 lines as a bloat backstop, not a goal.
- **Naming**: kebab-case noun phrases (e.g., `sprite-animation`, `glue-codegen`).
- **Frontmatter**: `name` and `description`. **The description is loaded into every session's skill listing** — it pays for itself in context tokens forever. Keep it brutally short. See "Writing the description" below.
- **Structure**: `##` sections. Tables for file maps. Prose for relationships and gotchas.
- **Progressive disclosure**: keep SKILL.md to high-level architecture; spill advanced content into sibling files (e.g., `[advanced-topic.md](advanced-topic.md)`) only when it's bulky enough to justify a second file.

## Writing the description

The description's **only job** is to tell future-Claude *when this skill is relevant*. It is a trigger, not a summary.

**Hard rules:**
- **One sentence. Under ~250 chars.** Ideally under 200. The skill body covers the rest.
- **Drop boilerplate.** No "Reference guide for…", no "Load this when working on…", no "Covers FlatRedBall's…". The fact that this is a skill is implicit — these phrases are dead weight on every entry.
- **Lead with the topic, then trigger identifiers.** Format: `<Topic> — <one-line hook>. Triggers: <distinctive identifiers, file paths, or scenarios>.`
- **Pick the 3–8 most distinctive triggers, not all of them.** Generic words ("file", "system", "behavior") don't help; specific class names, file paths, and method names do. The rest belong inside the file.
- **No multi-line YAML (`description: >`).** Keep it on one line. It folds anyway, and one line is easier to scan when auditing.

**Example.** Same triggers, ~40% fewer tokens:

Good:
```
description: FlatRedBall sprite texture-flip animation. Triggers: AnimationChain, AnimationFrame, .achx, Sprite.AnimationChains, UpdateToCurrentAnimationFrame.
```

Bad (boilerplate, padded):
```
description: Reference guide for FlatRedBall's sprite animation system. Load this when working on animation behavior, AnimationChains, AnimationFrame, .achx files, Sprite.AnimationChains, or UpdateToCurrentAnimationFrame.
```

## Plain Language

Write skills in plain English. Short sentences, small words, no jargon, no invented hyphenated terms. Don't open a sentence with a heavy qualifier or dramatic emphasis. Assume the reader has no special vocabulary — use a technical term only when the topic actually needs it, and prefer the term this codebase already uses over a fancier synonym.

❌ "This skill delivers a robust, developer-focused deep-dive into the nuanced, multi-faceted intricacies of undo state."

✅ "This skill explains how undo state works and where it breaks."

## Include

- Architecture: how major pieces fit together and why.
- Gotchas: surprising behavior, ordering dependencies, naming mismatches, "looks like X but actually Y."
- Key file map: one-line table of file → purpose.
- Pointers: links to relevant docs pages, key source files, and related skills.
- Specific identifiers only when the name itself is misleading or the behavior is surprising.

## Exclude

- Anything already on the docs site — link instead of restating.
- Full class outlines or property lists — read source directly.
- Code examples unless the snippet captures an irreplaceable pattern.
- **In-flight migration / refactor STATE** — what's done *now*, what currently blocks what, what's left, "X is already converted," "Y can't move until Z." This **inverts to false the moment the work lands**, turning the skill into an active liar that every future agent re-reads as fact. Skills hold *timeless* structure only. Transient progress belongs in the ephemeral working ledger, not the skill — and that includes versions and dates, any time-sensitive fact.
- **War stories — "Issue #N: X happened" / "PR #N caught this" framing, even for a landmine that never expires.** State the rule and the gotcha in pure present-tense, timeless form: what to check, what breaks if you don't, why. Never narrate it as an event that occurred on a numbered issue/PR — that framing is what keeps getting written despite this rule, because a durable fact wrapped in "Issue #N: ..." *reads* like it satisfies "state landmines fully," so the incident-number wrapper slips through. The test: could this sentence be true independent of which issue surfaced it? If removing "Issue #N:" and rephrasing as a bare rule loses no information, the issue number was never required — cut it. If you need a concrete illustration, name the *pattern* (a type, a method, a symbol) instead of the ticket.
- Anything Claude already knows from general C# or .NET knowledge.

## Output

Write to `.claude/skills/<skill-name>/SKILL.md`. Create the directory if needed. Add sibling detail files only when content is too large for the main file.