Imported from pproenca/dot-skills (
skills/.experimental/library-reference-distillation/SKILL.md). Install upstream withnpx skills add pproenca/dot-skills --skill library-reference-distillation. Copyright stays with the author.
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.mdheading or only inmetadata.json - Refreshing a skill where you suspect rule drift from upstream (the
openai-codex-rust-patternslesson: 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 |
| Rules feel like API restatement, not load-bearing | Source (failure-gap) | source-failure-gap |
| Library changes fast — skill will rot | Pin | pin-by-velocity |
| Existing skill is drifting from upstream | Pin (refresh) | pin-refresh-vs-head |
| Categories feel arbitrary | Shape | shape-category-ladder |
| When-to-Apply does not trigger reliably | Shape (When-to-Apply) | shape-when-to-apply-template |
| Cite list and rule sources have drifted | Meta | meta-references-checksum |
For category overviews and ordering rationale, see 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— Docs → blog/changelog → GitHub discussions → types → examples; the ladder inverts only when the library publishes anllms.txt(Effect)source-failure-gap— Privilege rules that capture what docs omit and production exposed; if a rule just restates the API, cut it
2. Versioning
pin-by-velocity— Stable APIs (Zod, RHF) → version lives inmetadata.jsononly; fast-moving APIs (nuqs v2.5–v2.8, Tailwind v4) → explicit range inSKILL.mdheadingpin-refresh-vs-head— When evolving, diff your skill against upstream HEAD; codify the drift lessons (codex-rscodex.rs→session/split is the canonical example)
3. Rule Shape
shape-category-ladder— 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 shapeshape-when-to-apply-template— 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—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— The thinking layer above this skill; this playbook is itself an instance of the "reduce → constrain → name the invariant" moves applied to skill-authoringskill-authoring— Cross-archetype skill-authoring conventions; this skill is the library-reference specializationdeterministic-metric-design— 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.
