library-reference-distillation

# Library-Reference Distillation — Archetype Playbook Methodology distillation of the conventions that hold across shipped **library-reference distillations** in this repo — the archetype that turns one external library into an idiomatic-usage rule pack. Not a generator; a constraint set on the editorial decisions `/dev-skill:new` cannot make for you. This is the **archetype layer** that sits above `/dev-skill:new` and `/dev-skill:ingest`. The generator handles the structural shell. This skill handles the four decisions you re-make for every library-ref skill: where to source from, how to pin against version drift, how to shape categories and rules, and how to keep the metadata an honest checksum. ## When to Apply Use this skill when: - Starting a new library-ref distillation (the library has docs and a stable surface area you want to capture as idiomatic rules) - Evolving an existing library-ref skill against a new upstream release or major version bump - Reviewing a draft library-ref skill that "feels like the docs rewritten" - Picking categories and a prefix scheme for a new skill and the choices feel arbitrary - Deciding whether to pin the upstream version in `SKILL.md` heading or only in `metadata.json` - Refreshing a skill where you suspect rule drift from upstream (the `openai-codex-rust-patterns` lesson: codex-rs drifts hard between snapshots) This skill is **not** for: - **Code-atlas distillations** (e.g., `openai-codex-rust-patterns`, `opencode-ts`, `nextjs-ppr-patterns`) — sources are a real repo at a pinned HEAD, not upstream docs. Sibling archetype playbook still to be extracted. - **Methodology distillations** (e.g., `radical-simplification`, `deterministic-metric-design`) — sources are named humans and their canon, not a library. - **Scaffolders** (e.g., `expo-design-system-scaffolder`) — composition workflow, not a rulebook. ## How to Use The four categories are orthogonal decisions you make once per skill. Match the symptom to the move: | Symptom | Reach for | First rule to read | |---------|-----------|--------------------| | Don't know where to mine rules from | **Source** | [`source-priority-ladder`](references/source-priority-ladder.md) | | Rules feel like API restatement, not load-bearing | **Source** (failure-gap) | [`source-failure-gap`](references/source-failure-gap.md) | | Library changes fast — skill will rot | **Pin** | [`pin-by-velocity`](references/pin-by-velocity.md) | | Existing skill is drifting from upstream | **Pin** (refresh) | [`pin-refresh-vs-head`](references/pin-refresh-vs-head.md) | | Categories feel arbitrary | **Shape** | [`shape-category-ladder`](references/shape-category-ladder.md) | | When-to-Apply does not trigger reliably | **Shape** (When-to-Apply) | [`shape-when-to-apply-template`](references/shape-when-to-apply-template.md) | | Cite list and rule sources have drifted | **Meta** | [`meta-references-checksum`](references/meta-references-checksum.md) | For category overviews and ordering rationale, see [`references/_sections.md`](references/_sections.md). ## Rule Categories | # | Category | Prefix | Move | Rules | |---|----------|--------|------|-------| | 1 | Source Selection | `source` | Where to mine from; what makes a rule load-bearing | 2 | | 2 | Versioning | `pin` | How to pin against API velocity; how to refresh | 2 | | 3 | Rule Shape | `shape` | The universal 4-tier ladder; the When-to-Apply template | 2 | | 4 | Metadata Discipline | `meta` | references[] as honest cite-set checksum | 1 | ## Quick Reference ### 1. Source Selection - [`source-priority-ladder`](references/source-priority-ladder.md) — Docs → blog/changelog → GitHub discussions → types → examples; the ladder inverts only when the library publishes an `llms.txt` (Effect) - [`source-failure-gap`](references/source-failure-gap.md) — Privilege rules that capture what docs omit and production exposed; if a rule just restates the API, cut it ### 2. Versioning - [`pin-by-velocity`](references/pin-by-velocity.md) — Stable APIs (Zod, RHF) → version lives in `metadata.json` only; fast-moving APIs (nuqs v2.5–v2.8, Tailwind v4) → explicit range in `SKILL.md` heading - [`pin-refresh-vs-head`](references/pin-refresh-vs-head.md) — When evolving, diff your skill against upstream HEAD; codify the drift lessons (codex-rs `codex.rs` → `session/` split is the canonical example) ### 3. Rule Shape - [`shape-category-ladder`](references/shape-category-ladder.md) — Every shipped library-ref skill ladders CRITICAL setup → HIGH isolation/perf → MEDIUM composition/integration → LOW edge cases/polish; pick category names that map onto this, do not invent a new shape - [`shape-when-to-apply-template`](references/shape-when-to-apply-template.md) — 4 slots: import-statement trigger + problem-domain language + frequency signal + explicit NOT-to-do boundary pointing to sibling skills ### 4. Metadata Discipline - [`meta-references-checksum`](references/meta-references-checksum.md) — `metadata.references[]` is the exact set of URLs cited in rules — no superset, no subset; if it diverges, either the rules or the metadata is lying ## Related Skills - [`radical-simplification`](../../.curated/radical-simplification/SKILL.md) — The thinking layer above this skill; this playbook is itself an instance of the "reduce → constrain → name the invariant" moves applied to skill-authoring - [`skill-authoring`](../../.curated/skill-authoring/SKILL.md) — Cross-archetype skill-authoring conventions; this skill is the library-reference specialization - [`deterministic-metric-design`](../../.curated/deterministic-metric-design/SKILL.md) — Methodology-distillation sibling; demonstrates the same archetype patterns applied to a different archetype (proves the per-archetype playbook idea generalizes) ## Authoring Note These rules are **load-bearing**, not decorative. They were extracted by tracing where rules in 5 shipped library-ref skills cited their sources (nuqs, zod, react-hook-form, effect-ts, emilkowal-animations). Each rule names the wrong default the author makes when these conventions are absent. If a rule restates something `/dev-skill:new` already handles, cut it. Coverage is proven by `/dev-skill:eval` on real library-distillation prompts, not by rule count. When the next archetype playbook (code-atlas, methodology, scaffolder, runbook) is extracted, the patterns that re-appear here are candidates for promotion to a generic `skill-authoring` skill; the ones that diverge stay archetype-specific.