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:

For category overviews and ordering rationale, see `references/_sections.md`.

Rule Categories

Quick Reference

1. Source Selection

• `source-priority-ladder` — Docs → blog/changelog → GitHub discussions → types → examples; the ladder inverts only when the library publishes an llms.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 in metadata.json only; fast-moving APIs (nuqs v2.5–v2.8, Tailwind v4) → explicit range in SKILL.md heading
• `pin-refresh-vs-head` — 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` — 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` — 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-authoring
• `skill-authoring` — Cross-archetype skill-authoring conventions; this skill is the library-reference specialization
• `deterministic-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.

Skill Authoring Methodology

Version 0.1.0 dot-skills May 2026

---

Abstract

Methodology distillation of the conventions that hold across shipped library-reference distillation skills (nuqs, zod, react-hook-form, effect-ts, emilkowal-animations) — the archetype that turns one external library into an idiomatic-usage rule pack. 7 rules across 4 orthogonal categories — Source Selection, Versioning, Rule Shape, Metadata Discipline — each naming a wrong default the author makes when starting a new library-reference skill, the convention that corrects it, and a concrete trace from an existing skill showing the convention in use. The skill is the meta-archetype playbook above /dev-skill:new and /dev-skill:ingest — it does not generate skills, it constrains the editorial decisions that the generator cannot make. Sibling playbooks for code-atlas, methodology, scaffolder, and runbook archetypes are still to be extracted.

---

Table of Contents

1. Source Selection

• 1.1 Mine sources in order — docs, then blog/changelog, then issues, then types, then examples
• 1.2 Privilege rules that capture the failure gap, not the API surface

2. Versioning

• 2.1 On evolve, diff the skill against upstream HEAD and codify the drift
• 2.2 Pin version by API velocity — metadata only for stable, explicit range in SKILL.md for moving

3. Rule Shape

• 3.1 Fill four When-to-Apply slots — import trigger, problem domain, frequency, not-to-do boundary
• 3.2 Ladder categories CRITICAL setup, HIGH isolation, MEDIUM composition, LOW edge cases

4. Metadata Discipline

• 4.1 [Treat metadata.references[] as a cite-set checksum — exact match with rule cites](references/meta-references-checksum.md)

---

References

1. https://nuqs.dev/docs 2. https://zod.dev/api 3. https://react-hook-form.com/docs 4. https://effect.website/docs 5. https://emilkowal.ski/ui

---

Source Files

This document was compiled from individual reference files. For detailed editing or extension:

Sections

This file defines the four orthogonal decision categories that hold across shipped library-reference distillations in this repo. The prefix in parentheses is the filename prefix that groups rules. Categories are ordered by the sequence in which the decisions actually come up when authoring: you cannot pin a version before you have sources; you cannot shape a category ladder before you know what kind of rules you are mining; you cannot make a metadata checksum honest until rules exist.

The four categories are orthogonal — getting one right does not help with the others. Match the decision in front of you to the category, do not walk them in order:

• "Where do I read to find rules?" → source
• "Which version of the library is this skill against?" → pin
• "What are the categories and how does each rule land?" → shape
• "Is the cite list honest?" → meta

This skill is a methodology distillation about a distillation archetype. The reference set behind these rules is empirical: 5 library-ref skills (nuqs, zod, react-hook-form, effect-ts, emilkowal-animations) traced rule-by-rule to their cited sources. Each rule below names the wrong default the author makes when this convention is absent.

---

1. Source Selection (source)

Description: Where rules come from and what makes a rule earn its place. The default failure mode is treating the library's official API reference as the source of rules — which produces an API-restatement skill that adds no judgment. Across all 5 traced skills, the most load-bearing rules came from secondary sources (author blog posts, changelogs, GitHub discussions on edge cases) and from production-failure stories that contradict or extend what the docs say. Covers the source-priority ladder (docs → blog/changelog → issues → types → examples) and the failure-gap exemplar heuristic.

2. Versioning (pin)

Description: How the skill stays honest as the upstream library moves. The default failure mode is either pinning too tightly (every minor version invalidates the skill) or not at all (the skill silently rots). Across all 5 traced skills, pinning inverts with API velocity: stable libraries (Zod 4, RHF v7) record only the skill version in metadata.json; fast-moving libraries (nuqs v2.5–v2.8, Tailwind v4 features) declare an explicit range in the SKILL.md heading itself. Covers initial pinning and the refresh-vs-HEAD move applied during /dev-skill:evolve.

3. Rule Shape (shape)

Description: How categories and individual rules land on the page. The default failure mode is inventing a new category structure for each skill and phrasing "When to Apply" as a vague paragraph. Across all 5 traced skills, a universal 4-tier category ladder appears (CRITICAL setup → HIGH isolation/perf → MEDIUM composition → LOW edge cases) and a 4-slot "When to Apply" template (import-statement trigger + problem-domain language + frequency signal + explicit NOT-to-do boundary). Covers both.

4. Metadata Discipline (meta)

Description: Making the skill auditable from metadata.json alone. The default failure mode is metadata.references[] becoming an aspirational reading list rather than a checksum of cites actually used in rules. The invariant across all 5 traced skills: metadata.references[] is the exact set of URLs cited in rules — no aspirational entries, no missing cites. If the two diverge, one of them is lying. Covers this single discipline.

Treat metadata.references[] as a cite-set checksum — exact match with rule cites

By default metadata.references[] accretes as an aspirational reading list — URLs the author scanned, intended to use, or thought looked relevant. Over time it diverges from the URLs rules actually cite. When the skill is audited or migrated, this divergence is the first signal that either the rules or the metadata is lying. The convention is to treat metadata.references[] as the exact set of URLs cited in rules — no superset, no subset, no aspirational entries.

The invariant (must hold at every commit):

  set( URLs cited in references/*.md "Reference:" lines )
    ==
  set( metadata.json "references": [ ... ] )

Diff procedure (run before /dev-skill:validate):

  1. grep -h "^Reference:" skills/<skill>/references/*.md \
       | extract URLs → set A
  2. jq -r ".references[]" skills/<skill>/metadata.json → set B
  3. set A XOR set B should be empty.
     - In A but not B: a rule cites a source the metadata hides.
     - In B but not A: metadata lists a source no rule uses.

Both directions are bugs:

  In-A-not-in-B (under-listed):
    The metadata under-credits the skill's actual provenance. An
    auditor reading metadata.json alone cannot reconstruct what
    the skill is built from. Add the missing URL.

  In-B-not-in-A (over-listed / aspirational):
    The metadata claims influence the rules do not show. Either
    the rule that should have cited it is missing — write it — or
    the URL was never load-bearing — remove it.

Anti-pattern: "I read this and it shaped my thinking, so it goes
in references." If it shaped your thinking, it should have shaped
at least one rule. If no rule cites it, it did not actually shape
anything — it was background reading.

The mechanical trigger: add the diff procedure as a one-line check in your skill's CI or pre-commit. The shipped library-ref skills that age well have this invariant hold; the ones that decay have references[] drift into a graveyard of links nobody reads. Make the cite-set a checksum, not a reading list.

Reference: [zod skill's metadata.references[] matches the exact URLs cited in references/*.md rule bodies](../../../../skills/.curated/zod/metadata.json)

Pin version by API velocity — metadata only for stable, explicit range in SKILL.md for moving

By default the agent either pins nothing (the skill silently rots when upstream breaks an API) or pins everything (every minor version bump invalidates the skill). The convention across shipped library-ref skills is to let API velocity decide the pinning surface. Pinning is not a uniform discipline — it is a tradeoff between staleness signal and false invalidation.

Stable APIs (Zod 4, React Hook Form v7, MSW v2):
  - SKILL.md heading: NO version mentioned
  - metadata.json:   "version": "1.x.y" (the SKILL version, not the
                      library version)
  WHY: The library's public API has been stable for years. Naming
  the library version in SKILL.md adds noise and creates false
  staleness — readers think the skill expired when it didn't.

Fast-moving APIs (nuqs v2.5–v2.8, Tailwind v4 features in
                  emilkowal-animations):
  - SKILL.md heading: explicit version RANGE
    e.g. "Rules apply to nuqs v2.5 through v2.8"
  - metadata.json:   skill version, plus references[] pointing to
                     pinned changelog URLs
  WHY: The author shipped breaking idiom changes recently. The
  range in the heading is a tripwire — when the upstream releases
  v2.9 with a new pattern, the skill's range is now visibly stale
  and triggers /dev-skill:evolve.

The discriminator:
  - Have ≥2 breaking-idiom changes shipped in the last 12 months?
    → fast-moving → explicit range in SKILL.md
  - Is the public API surface dominated by a few stable verbs the
    author has not touched in years (parse, useForm, http)?
    → stable → metadata only

Anti-pattern:
  Pinning the library version inside metadata.json's "version"
  field. That field is the SKILL's semver, not the library's.
  Conflating them breaks /dev-skill:check-versions.

The test: re-read your SKILL.md six months from now. If a stable-API skill names a version it tempts a reader into thinking the skill is outdated when it isn't; if a fast-moving-API skill doesn't name a version range, the rules will silently lie. Pin to match the velocity, not to a uniform discipline.

Reference: nuqs SKILL.md with explicit "nuqs v2.5–v2.8" range vs zod SKILL.md with no library version

On evolve, diff the skill against upstream HEAD and codify the drift

By default /dev-skill:evolve is treated as "look for things to add." This misses the more dangerous case: the skill's existing rules silently lie because the upstream renamed, restructured, or removed the very API they cite. The move is to diff your skill against the upstream HEAD before adding anything new, and codify each drift as either a rule update or a deprecation note. Skills do not grow by accretion; they grow by reconciling with reality.

The drift pattern (canonical case: openai-codex-rust-patterns):

  Skill written against codex-rs at HEAD abc1234 (Jan 2026)
    Rule: "codex.rs::Session never holds connection state directly"

  Six months later, refresh vs HEAD 8a94430 (May 2026)
    codex.rs has been SPLIT into:
      session/lifecycle.rs
      session/transport.rs
      session/state.rs
    The rule's absolute "never does X" is now structurally
    unverifiable — the file it cites no longer exists.

The refresh-vs-HEAD checklist (apply at every /dev-skill:evolve):

  1. Re-clone or pull the upstream repo at HEAD; record the SHA.
  2. For every rule that cites a specific file path, function, or
     type name — grep the upstream for that exact identifier.
       grep -r "codex.rs::Session" .  → 0 matches → drift.
  3. For every rule with an absolute claim ("never", "always",
     "exactly", "only"), grep-check the claim. Codex drift lesson:
     absolutes age the fastest.
  4. For every changelog entry since the last refresh, ask: does
     this entry invalidate or extend any existing rule?
  5. ONLY THEN consider net-new rules.

Output of the refresh: a diff of the skill, not a feature list.
Sometimes the right outcome is "deleted 3 rules, updated 5,
added 1" — and that is healthier than "added 10 new rules" on a
skill whose existing rules secretly drifted.

The mechanical trigger: before any /dev-skill:evolve work, run a grep-check pass on every absolute claim and every file-path cite. The skills that hold up across upstream changes are the ones where this pass is non-negotiable.

Reference: openai-codex-rust-patterns skill, refreshed vs HEAD 8a94430 — codex.rs to session/ split

Ladder categories CRITICAL setup, HIGH isolation, MEDIUM composition, LOW edge cases

By default the agent invents a fresh category taxonomy for every library-ref skill, picking names that mirror the library's own module structure (parser/schema/middleware/plugin). The resulting skills are unreadable as a group — a reader who knows one cannot navigate another. Across shipped library-ref skills in this repo the same 4-tier ladder appears under different names. Pick category names that map onto the ladder; do not invent a new shape.

The universal ladder, observed across nuqs, zod, react-hook-form,
effect-ts, and emilkowal-animations:

  Tier 1 — CRITICAL setup / correctness
    "What you must get right or nothing works."
    Examples by skill:
      nuqs              → parser-*, setup-*
      zod               → schema-*, parse-*
      react-hook-form   → formcfg-*, sub-*
      effect-ts         → getting-*, error-*, schema-*
      emilkowal         → ease-*, timing-*

  Tier 2 — HIGH isolation / performance
    "How to keep this from making your app slow or re-rendery."
    Examples:
      nuqs              → perf-*
      react-hook-form   → ctrl-*
      effect-ts         → conc-*, resource-*
      emilkowal         → props-*, interact-*

  Tier 3 — MEDIUM composition / integration
    "How this fits with other libraries and your stack."
    Examples:
      react-hook-form   → integ-*
      effect-ts         → req-*, plat-*
      zod               → compose-*, refine-*
      emilkowal         → tw-*

  Tier 4 — LOW edge cases / polish
    "Things you only need when you hit a sharp corner."
    Examples:
      nuqs              → debug-*, history-*
      effect-ts         → test-*, migration-*
      emilkowal         → polish-*, strategy-*
      zod               → error-*, object-*

The discriminator when picking a category name:
  Ask "which tier does this rule belong in?" before "what should I
  call this category?" If a rule does not fit any of the 4 tiers,
  treat the rule as mis-scoped (not the ladder) and re-scope it
  to one tier, or split it into two rules each fitting one tier.

The test: print the categories from your draft skill alongside the table above. If a reader who has used one of your other skills can immediately tell which category to read first, the ladder is honest. If they can't, you invented a shape — go back and re-name to the tiers.

Reference: Empirical cross-skill table in the explore-agent trace of 5 library-ref skills

Fill four When-to-Apply slots — import trigger, problem domain, frequency, not-to-do boundary

By default the agent writes "When to Apply" as a vague paragraph: "Use this skill when you are working with library X." This does not trigger reliably — the dispatcher cannot tell from the paragraph whether a specific user prompt should invoke the skill or a sibling. Across shipped library-ref skills, the "When to Apply" section has the same 4-slot structure. Fill all four slots explicitly.

Slot 1 — Import-statement trigger
  The exact code patterns that, when present in user-shown code,
  should invoke this skill.

  Bad:   "When working with form state."
  Good:  "When code imports useForm, Controller, FormProvider, or
         useFormContext from react-hook-form."

Slot 2 — Problem-domain language
  The words the user uses (not the library uses) that signal this
  problem space.

  Bad:   "Form validation."
  Good:  "When the user says 'controlled vs uncontrolled', 'too
         many re-renders', 'isSubmitting stuck', 'validation runs
         twice', or 'I need to read form state without subscribing
         to it'."

Slot 3 — Frequency signal
  How often the triggering pattern fires — used to disambiguate
  from skills with overlapping surface area.

  Bad:   (none — most skills omit this).
  Good:  "When the user is debugging re-renders that fire on every
         keystroke" (RHF), or "When animating high-frequency user
         actions like cursor moves" (emilkowal-animations).

Slot 4 — NOT-to-do boundary (with sibling routing)
  The cases where this skill is wrong and which sibling owns them.

  Bad:   (none — most skills omit this).
  Good:  "NOT for React 19 Server Actions form-handling (→ use
         react-19-component-scaffolder). NOT for OpenAPI schema
         generation from zod (→ use orval). NOT for general
         TypeScript narrowing (→ use typescript)."

Full template before drafting:

  ## When to Apply

  Use this skill when:
  - [Slot 1: import X from "lib"; pattern Y in code]
  - [Slot 2: user says "..." or "..." or "..."]
  - [Slot 3: at frequency/scale "..."]

  This skill is NOT for:
  - [Slot 4a: case + sibling skill it routes to]
  - [Slot 4b: case + sibling skill it routes to]

The test: hand your "When to Apply" to someone unfamiliar with the library and ask "could you tell from this alone whether to invoke this skill or react-19-component-scaffolder for a given prompt?" If they can't, a slot is missing or vague. The 4 slots together are the dispatcher's input — treat them as a contract, not as marketing copy.

Reference: nuqs SKILL.md "When to Apply" naming useQueryState, parser kinds, and explicit boundaries with react-19 and orval

Privilege rules that capture the failure gap, not the API surface

By default the agent writes one rule per public API method. The resulting skill has 60 rules that collectively say "the API does what the API says" — adding no judgment beyond the docs. The move that earns each rule its place is the failure gap: a rule is load-bearing only if it captures something the docs omit and production exposed. If you can't name the failure the rule prevents, cut it.

Two rules from shipped skills, same library surface area:

Rule A (cut — pure API restatement):
  "z.object() creates an object schema. Pass a shape object mapping
  keys to schemas. Call .parse() to validate input."
  → This is what zod.dev/api already says. Adds zero judgment.

Rule B (keep — failure gap):
  "Never trust JSON.parse output even after a Zod parse — the JSON
  type system is structural, not nominal. A request body with the
  right keys but wrong meaning (e.g. user_id as a number where you
  meant a UUID string) will parse cleanly and corrupt downstream.
  Use z.string().uuid() at every boundary."
  → This is the production-failure story zod.dev does NOT tell.
  → It earns its place because it prevents a specific real bug.

The discriminator (apply per rule before keeping):
  - Can I cite a GH issue, blog post, or postmortem where someone
    got bitten by the absence of this rule? → keep.
  - Did I just transcribe the API reference? → cut.
  - Is the rule "the framework's headline feature"? → keep ONLY if
    you can name the failure mode of NOT using it.

The mechanical filter: after drafting, for each rule ask "what does this prevent?" If the answer is "nothing, it just describes how to call X", cut. The shipped library-ref skills that hold up over time are the ones where every rule has a falsification — a concrete bug it stops. Rule count drops to ~30–60, signal density rises.

Reference: react-hook-form's `formstate-async-submit-lifecycle` rule, which cites GH discussion #10103

Mine sources in order — docs, then blog/changelog, then issues, then types, then examples

By default the agent treats the library's official API reference as the only source. The resulting skill restates the API in markdown and adds no judgment a tsc/JSDoc reader could not get for free. Walk the 5-tier ladder instead — each tier surfaces a different kind of rule, and the load-bearing ones rarely come from tier 1.

Tier 1 — Official docs                 (e.g. zod.dev/api, nuqs.dev/docs)
  WHAT to write. Defines vocabulary, names the canonical idioms,
  marks deprecations. Rules from here are the table-of-contents.

Tier 2 — Author blog posts & changelogs (e.g. emilkowal.ski/ui/*,
                                         nuqs.dev/blog/nuqs-2.5)
  WHY each idiom exists. Authors explain motivation, the design
  alternatives they rejected, and "if you only learn one thing"
  rules. This tier produces the highest-leverage rules.

Tier 3 — GitHub discussions/issues       (e.g. react-hook-form #10103)
  WHERE docs and code disagree. "isSubmitting doesn't recover when
  submit handler throws" — the kind of rule docs never include
  because they cover the happy path. Failure-gap goldmine.

Tier 4 — TypeScript .d.ts / type files
  GROUND TRUTH. When docs and types contradict, types win. Inferred
  return types reveal generic constraints the docs hide.

Tier 5 — examples/ + playground/ dirs in the repo
  REAL USAGE. Authors test their own API here; idioms they didn't
  bother to document end up here as the "how I'd use it" reference.

Inversion: if the library publishes an llms.txt (Effect), it
collapses tiers 1–2 into a single AI-facing artifact — prefer it
over scraping HTML docs.

Trace check before committing: for any rule in your draft skill, you should be able to say which tier its source came from. If every rule cites tier 1 only, the skill is API documentation in disguise and you should drop ~half the rules and re-mine from tiers 2–3.

Reference: Empirical trace across nuqs, zod, react-hook-form, effect-ts, emilkowal-animations skills in this repo