diff --git a/skills/domain-discovery/SKILL.md b/skills/domain-discovery/SKILL.md
new file mode 100644
index 0000000..65ff394
--- /dev/null
+++ b/skills/domain-discovery/SKILL.md
@@ -0,0 +1,532 @@
+---
+name: skill-domain-discovery
+description: >
+  Analyze library documentation and source code, then interview maintainers
+  to discover capability domains and generate a structured domain map for
+  AI coding agent skills. Activate when creating skills for a new library,
+  organizing existing documentation into skill categories, or when a
+  maintainer wants help deciding how to structure their library's agent-facing
+  knowledge. Produces a domain_map.yaml and skill_spec.md that feed directly
+  into the skill-tree-generator skill.
+metadata:
+  version: "2.1"
+  category: meta-tooling
+  output_artifacts:
+    - domain_map.yaml
+    - skill_spec.md
+  skills:
+    - skill-tree-generator
+---
+
+# Domain Discovery & Maintainer Interview
+
+You are extracting domain knowledge for a library to produce a structured
+domain map. Your job is not to summarize documentation — it is to build a
+deep understanding of the library first, then use that understanding to
+surface the implicit knowledge that maintainers carry but docs miss.
+
+There are four phases. Always run them in order. Phases 1–2 are autonomous.
+Phase 3 is an interview that builds on what you learned. Phase 4 produces
+the final artifacts.
+
+---
+
+## Phase 1 — Read everything (autonomous)
+
+Read the library's documentation and source code. You are collecting raw
+material — not reasoning about structure yet.
+
+### Reading order
+
+Read in this exact order. Each step builds context for the next.
+
+1. **README and overview** — establishes vocabulary and core mental model
+2. **Getting started / quickstart** — reveals the happy path and setup
+3. **Every narrative guide** — the how-to content, not API reference tables
+4. **Migration guides** — highest-yield source for failure modes; every
+   breaking change is exactly what agents trained on older versions produce
+5. **API reference** — scan for exports, type signatures, option shapes
+6. **Changelog for major versions** — API renames, removed exports,
+   behavioral changes
+7. **GitHub issues and discussions** — scan for frequently reported
+   confusion, common misunderstandings, recurring questions. Also look
+   for what users are implicitly arguing for architecturally — not just
+   "people are confused about X" but "users keep expecting X to work
+   like Y, which reveals a tension between [design force] and [design force]"
+8. **Source code** — verify ambiguities from docs, check defaults, find
+   assertions and invariant checks
+
+### What to log
+
+Produce a flat concept inventory. One item per line. No grouping yet.
+
+Log every:
+- Named concept, abstraction, or lifecycle stage
+- Public export: function, hook, class, type, constant
+- Configuration key, its type, and its default value
+- Constraint or invariant (especially any enforced by `throw` or assertion)
+- Doc callout: any "note", "warning", "caution", "important", "avoid", "do not"
+- Dual API: any place the library has two ways to do the same thing (old/new,
+  verbose/shorthand, lower-level/higher-level)
+- Environment branch: any place behavior depends on SSR/CSR, dev/prod,
+  framework, bundler, or config flag
+- Type gap: any type documented as accepting X but source shows X | Y or
+  rejects a subtype of X
+- Source assertion: any `if (!x) throw`, `invariant()`, or `assert()` with
+  the error message text
+
+### What to extract from migration guides specifically
+
+For each breaking change between major versions:
+
+```
+Old pattern: [code that agents trained on older versions will produce]
+New pattern: [current correct code]
+What changed: [one sentence — the specific mechanism]
+Version boundary: [e.g. "v4 → v5"]
+```
+
+These become high-priority failure modes in Phase 2.
+
+---
+
+## Phase 2 — Draft domain map (autonomous)
+
+You now have the concept inventory. Derive domains and failure modes from
+it before involving the maintainer.
+
+### 2a — Group the concept inventory
+
+Move items into groups. Two items belong together when:
+- A developer reasons about them together when solving a problem
+- Solving one correctly requires understanding how the other works
+- They share a lifecycle, configuration scope, or architectural tradeoff
+- Getting one wrong tends to produce bugs in the other
+
+**Merge aggressively.** Target 4–7 domains. 5 sharp domains beats 12 thin ones.
+
+Do not create a group for:
+- A single hook, function, or class
+- A single doc or reference page
+- "Miscellaneous", "Advanced", or "Other"
+- Configuration knobs that only affect another group's behavior
+
+### 2b — Validate every group
+
+For each group:
+
+> "Can a developer perform three or more meaningfully different tasks using
+> the same mental model this group represents?"
+
+If no — merge it with the closest related group.
+
+### 2c — Flag subsystems within domains
+
+After grouping, check each domain for internal diversity. A domain may
+be conceptually unified (one mental model) but contain multiple
+independent subsystems with distinct config interfaces — for example,
+5 sync adapters that all solve "connectivity" but each with unique
+setup, options, and failure modes.
+
+For each domain, ask: "Does this domain contain 3+ backends, adapters,
+drivers, or providers that share a purpose but have distinct
+configuration surfaces?" If yes, list them as `subsystems` on the
+domain. These tell the skill-tree-generator to produce per-subsystem
+reference files rather than compressing everything into one skill.
+
+Also flag domains with dense API surfaces — if a single topic within
+the domain has >10 distinct operators, option shapes, or patterns
+(e.g. query operators, schema validation rules), note it as a
+`reference_candidates` entry. These need dedicated reference files
+for agents to have enough detail for implementation.
+
+### 2d — Name each group as a capability domain
+
+Names describe work being performed, not what the library provides:
+
+| If your name is... | It is wrong because... | Rewrite as... |
+|---------------------|------------------------|---------------|
+| A function/hook name | Feature-oriented | The work the function enables |
+| A doc section title | Mirrors existing structure | The developer intent it serves |
+| A noun phrase | Describes a thing, not work | Verb phrase or lifecycle name |
+| "Configuration" | Too generic | The specific config scope |
+
+### 2e — Extract failure modes from docs and source
+
+For each domain, extract failure modes that pass all three tests:
+
+- **Plausible** — An agent would generate this because it looks correct
+  based on the library's design, a similar API, or an older version
+- **Silent** — No immediate crash; fails at runtime or under specific conditions
+- **Grounded** — Traceable to a specific doc page, source location, or issue
+
+**Where to find them:**
+
+| Source | What to extract |
+|--------|----------------|
+| Migration guides | Every breaking change → old pattern is the wrong code |
+| Doc callouts | Any "note", "warning", "avoid" with surrounding context |
+| Source assertions | `throw` and `invariant()` messages describe the failure |
+| Default values | Undocumented or surprising defaults that cause wrong behavior |
+| Type precision | Source type more restrictive than docs imply |
+| Environment branches | `typeof window`, SSR flags, `NODE_ENV` — behavior differs silently |
+
+Target 3 failure modes per domain minimum. Complex domains target 5–6.
+
+**Cross-domain failure modes.** Some failure modes belong to multiple
+domains. A developer doing SSR work and a developer doing state management
+both need to know about "stale state during hydration" — they load
+different skills but need the same advice. When a failure mode spans
+domains, list all relevant domain slugs in its `domains` field. The
+skill-tree-generator will write it into every corresponding SKILL file.
+
+List a cross-domain failure mode once, under its primary domain. Set
+the `domains` field to all domain slugs it applies to. Do not duplicate
+the entry in the YAML — the skill-tree-generator handles duplication
+into multiple SKILL files at generation time.
+
+### 2f — Identify cross-domain tensions
+
+Look for places where design forces between domains conflict. A tension
+is not a failure mode — it's a structural pull where getting one domain
+right makes another domain harder. Examples:
+
+- "Getting-started simplicity conflicts with production operational safety"
+- "Type-safety strictness conflicts with rapid prototyping flexibility"
+- "SSR correctness requires patterns that hurt client-side performance"
+
+Tensions are where agents fail most because they optimize for one domain
+without seeing the tradeoff. Each tension should name the domains in
+conflict, describe the pull, and state what an agent gets wrong when it
+only considers one side.
+
+Target 2–4 tensions. If you find none, the domains may be too isolated —
+revisit whether you're missing cross-connections.
+
+### 2g — Identify gaps
+
+For each domain, explicitly list what you could NOT determine from docs
+and source alone. These become interview questions in Phase 3.
+
+Common gaps:
+- "Docs describe X but don't explain when you'd choose X over Y"
+- "Migration guide mentions this changed but doesn't say what the old
+  behavior was"
+- "Source has an assertion here but no doc explains what triggers it"
+- "GitHub issues show confusion about X but docs don't address it"
+- "I found two patterns for doing X — unclear which is current/preferred"
+
+### 2h — Discover composition targets
+
+Scan `package.json` for peer dependencies, optional dependencies, and
+`peerDependenciesMeta`. Scan example directories and integration tests
+for import patterns. For each frequently co-used library, log:
+
+- Library name and which features interact
+- Whether it's a required or optional integration
+- Any example code showing the integration pattern
+
+These become targeted composition questions in Phase 3e.
+
+### 2i — Produce the draft domain map
+
+Write the full `domain_map.yaml` (format in Output Artifacts below) with
+a `status: draft` field. Flag every gap in the `gaps` section.
+
+Present the draft to the maintainer before starting the interview:
+
+> "I've read the docs and source for [library] and produced a draft domain
+> map with [N] domains and [M] failure modes. Before we start the interview,
+> review this draft. I've flagged [K] specific gaps where I need your input."
+
+---
+
+## Phase 3 — Maintainer interview (builds on Phase 1–2)
+
+You have already read everything and formed a draft. The interview fills
+gaps, validates your understanding, and surfaces implicit knowledge.
+
+### Rules for the interview
+
+1. One topic per message for open-ended questions. You may batch 2–3
+   yes/no or short-confirmation questions in a single message when they
+   are factual checks (e.g. "Is X still the recommended pattern? Does Y
+   default apply in production? Is Z deprecated?"). Reserve single-question
+   format for any question requiring explanation or nuance.
+2. Each question must reference something specific from your reading.
+3. If the maintainer gives a short answer, probe deeper before moving on.
+4. Take notes silently. Do not summarize back unless asked.
+
+### 3a — Draft review (2–3 questions)
+
+Start by confirming or correcting your draft:
+
+> "I've organized [library] into [N] domains. Here's my proposed grouping:
+> [list domains with brief descriptions]. Does this match how you think
+> about your library? What would you move, merge, or split?"
+
+Follow up on any corrections. Then:
+
+> "I identified [M] failure modes from the docs and migration guides. Are
+> there important ones I missed — especially patterns that look correct
+> but fail silently?"
+
+### 3b — Gap-targeted questions (3–8 questions)
+
+For each gap flagged in Phase 2, ask a specific question. These are not
+generic — they reference what you found:
+
+**Instead of:** "What do developers get wrong?"
+**Ask:** "I noticed the migration guide from v4 to v5 changed how [X] works,
+but the docs don't show the old pattern. Do agents still commonly generate
+the v4 pattern? What does it look like?"
+
+**Instead of:** "Are there surprising interactions?"
+**Ask:** "The source throws an invariant error if [X] is called before [Y],
+but the docs don't mention ordering. How often do developers hit this?"
+
+**Instead of:** "What's different in SSR vs client?"
+**Ask:** "I found a `typeof window` check in [file] that changes behavior
+for [feature]. What goes wrong when developers test only in the browser
+and deploy with SSR?"
+
+Adapt from this bank of gap-targeted question templates:
+
+- "I found two patterns for [X] in the docs — [pattern A] and [pattern B].
+  Which is current, and does the old one still work?"
+- "The source defaults [config option] to [value], which seems surprising
+  for [reason]. Is this intentional? Do developers need to override it?"
+- "GitHub issues show [N] reports of confusion about [X]. What's the
+  underlying misunderstanding?"
+- "I couldn't find docs for how [feature A] interacts with [feature B].
+  What should an agent know about using them together?"
+- "The API reference shows [type signature], but the guide examples use
+  a different shape. Which is accurate?"
+
+### 3c — AI-agent-specific failure modes (2–4 questions)
+
+These target mistakes that AI coding agents make but human developers
+typically don't. Agent-specific failures are often the highest-value
+findings — in testing, maintainer answers to these questions produced
+the most critical failure modes.
+
+- "What mistakes would an AI coding agent make that a human developer
+  wouldn't? Think about: hallucinating APIs that don't exist, defaulting
+  to language primitives instead of library abstractions, choosing the
+  wrong adapter or integration path."
+- "When an agent generates code using your library, what's the first
+  thing you'd check? What pattern would make you immediately say
+  'an AI wrote this'?"
+- "Are there parts of your API where the naming or design is misleading
+  enough that an agent with no prior context would pick the wrong
+  approach? What would it pick, and what should it pick instead?"
+- "Are there features where the docs are comprehensive for human
+  developers but would still mislead an agent? For example, features
+  that require understanding unstated context, or where the 'obvious'
+  approach from reading the API surface is wrong."
+
+### 3d — Implicit knowledge extraction (3–5 questions)
+
+These surface knowledge that doesn't appear in any docs:
+
+- "What does a senior developer using your library know that a mid-level
+  developer doesn't — something that isn't written down anywhere?"
+- "Are there patterns that work fine for prototyping but are dangerous
+  in production? What makes them dangerous?"
+- "What question do you answer most often in Discord or GitHub issues
+  that the docs technically cover but people still miss?"
+- "Is there anything you'd change about the API design if you could break
+  backwards compatibility? What's the current workaround?"
+
+### 3e — Composition questions (if library interacts with others)
+
+Use what you discovered in Phase 2h. For each integration target
+identified from peer dependencies and example code, ask targeted
+questions:
+
+- "I see [library] is a peer dependency and [N] examples import it
+  alongside yours. What's the most common integration mistake?"
+- "When developers use [your library] with [other library], are there
+  patterns that only matter when both are present?"
+- "I found [specific integration pattern] in the examples. Is this the
+  recommended approach, or is there a better way that isn't documented?"
+
+---
+
+## Phase 4 — Finalize artifacts
+
+Merge interview findings into the draft domain map. For each interview answer:
+
+1. If it confirms a draft domain or failure mode — no action needed
+2. If it corrects something — update the domain map
+3. If it adds a new failure mode — add it with source "maintainer interview"
+4. If it reveals a new domain — evaluate whether to add or merge
+5. If it fills a gap — remove from gaps section
+
+Update `status: draft` to `status: reviewed`.
+
+---
+
+## Output artifacts
+
+### 1. domain_map.yaml
+
+```yaml
+# domain_map.yaml
+# Generated by skill-domain-discovery
+# Library: [name]
+# Version: [version this map targets]
+# Date: [ISO date]
+# Status: [draft | reviewed]
+
+library:
+  name: "[package-name]"
+  version: "[version]"
+  repository: "[repo URL]"
+  description: "[one line]"
+  primary_framework: "[React | Vue | Svelte | framework-agnostic]"
+
+domains:
+  - name: "[work-oriented domain name]"
+    slug: "[kebab-case]"
+    description: "[what a developer is doing, not what the library provides]"
+    covers:
+      - "[API/hook/concept 1]"
+      - "[API/hook/concept 2]"
+    tasks:
+      - "[example task 1]"
+      - "[example task 2]"
+      - "[example task 3]"
+    subsystems:                    # omit if domain has no independent subsystems
+      - name: "[adapter/backend name]"
+        package: "[npm package if separate]"
+        config_surface: "[brief description of unique config]"
+    reference_candidates:          # omit if no dense API surfaces
+      - topic: "[e.g. query operators, schema validation]"
+        reason: "[e.g. >10 distinct operators with signatures]"
+    failure_modes:
+      - mistake: "[5-10 word phrase]"
+        mechanism: "[one sentence]"
+        source: "[doc page, source file, issue link, or maintainer interview]"
+        priority: "[CRITICAL | HIGH | MEDIUM]"
+        status: "[active | fixed-but-legacy-risk | removed]"
+        version_context: "[e.g. 'Fixed in v5.2 but agents trained on older code still generate this']"
+        domains: ["[this-domain-slug]"]  # list all domains this belongs to; omit if single-domain
+    related_domains:
+      - "[other domain slug this one references]"
+    compositions:
+      - library: "[other library name]"
+        skill: "[composition skill name if applicable]"
+
+tensions:
+  - name: "[short phrase describing the pull]"
+    domains: ["[domain-slug-a]", "[domain-slug-b]"]
+    description: "[what conflicts — one sentence]"
+    implication: "[what an agent gets wrong when it only considers one side]"
+
+gaps:
+  - domain: "[domain slug]"
+    question: "[what still needs input]"
+    context: "[why this matters]"
+    status: "[open | resolved]"
+```
+
+### 2. skill_spec.md
+
+A human-readable companion document. Follow this structure:
+
+```markdown
+# [Library Name] — Skill Spec
+
+[2–3 sentences: what this library is, what problem it solves. Factual,
+not promotional.]
+
+## Domain Coverage
+
+| Domain | Skill name | What it covers | Failure modes | Tier |
+|--------|------------|----------------|---------------|------|
+| [name] | [lib]/[slug] | [exhaustive list] | [count] | [1|2] |
+
+## Failure Mode Inventory
+
+### [Domain name] ([count] failure modes)
+
+| # | Mistake | Priority | Source | Cross-domain? |
+|---|---------|----------|--------|---------------|
+| 1 | [phrase] | CRITICAL | [doc/source/interview] | [other domain slugs or —] |
+
+[Repeat table for each domain.]
+
+## Tensions
+
+| Tension | Domains | Agent implication |
+|---------|---------|-------------------|
+| [short phrase] | [slug-a] ↔ [slug-b] | [what agents get wrong] |
+
+## Subsystems & Reference Candidates
+
+| Domain | Subsystems | Reference candidates |
+|--------|------------|---------------------|
+| [slug] | [adapter1, adapter2, ...] or — | [topic needing depth] or — |
+
+## Remaining Gaps
+
+| Domain | Question | Status |
+|--------|----------|--------|
+| [slug] | [what still needs input] | open |
+
+[Omit this section if all gaps were resolved in the interview.]
+
+## Recommended Skill File Structure
+
+- **Core skills:** [list which domains become core sub-skills]
+- **Framework skills:** [list per-framework skills needed]
+- **Composition skills:** [list integration seams needing composition skills]
+- **Reference files:** [list domains needing references/ based on subsystems
+  or dense API surfaces]
+
+## Composition Opportunities
+
+| Library | Integration points | Composition skill needed? |
+|---------|-------------------|--------------------------|
+| [name] | [what interacts] | [yes/no — if yes, skill name] |
+```
+
+---
+
+## Constraints
+
+| Check | Rule |
+|-------|------|
+| Docs read before interview | Never start interviewing without completing Phase 1–2 |
+| Batch only confirmations | Yes/no questions may batch 2–3; open-ended questions get their own message |
+| Questions reference findings | No generic questions — cite what you found |
+| 4–7 domains | Merge aggressively; 5 sharp domains > 12 thin ones |
+| Work-oriented names | No function names, no doc section titles |
+| 3+ failure modes per domain | Complex domains target 5–6 |
+| Every failure mode sourced | Doc page, source file, issue link, or maintainer interview |
+| Gaps are explicit | Unknown areas flagged, not guessed |
+| No marketing prose | Library description is factual, not promotional |
+| domain_map.yaml is valid YAML | Parseable by any YAML parser |
+| Draft before interview | Always present draft for review first |
+| Agent-specific failures probed | Always ask AI-agent-specific questions in Phase 3c |
+| Compositions discovered from code | Scan peer deps and examples before asking composition questions |
+| Cross-domain failure modes tagged | Failure modes spanning domains list all relevant slugs in `domains` |
+| Tensions identified | 2–4 cross-domain tensions; if none found, revisit domain boundaries |
+| Subsystems flagged | Domains with 3+ adapters/backends list them as subsystems |
+| Dense surfaces flagged | Topics with >10 patterns noted as reference_candidates |
+
+---
+
+## Cross-model compatibility notes
+
+This skill is designed to produce consistent results across Claude, GPT-4+,
+Gemini, and open-source models. To achieve this:
+
+- All instructions use imperative sentences, not suggestions
+- Output formats use YAML (universally parsed) and Markdown tables
+  (universally rendered)
+- Examples use concrete values, not placeholders like "[your value here]"
+- Section boundaries use Markdown headers (##) for navigation and --- for
+  phase separation
+- No model-specific features (no XML tags in output, no tool_use assumptions)
diff --git a/skills/tree-generator/SKILL.md b/skills/tree-generator/SKILL.md
new file mode 100644
index 0000000..2e492c8
--- /dev/null
+++ b/skills/tree-generator/SKILL.md
@@ -0,0 +1,642 @@
+---
+name: skill-tree-generator
+description: >
+  Generate, update, and version a complete skill tree (collection of SKILL.md
+  files) for any JavaScript or TypeScript library. Produces core skills
+  (framework-agnostic) and framework skills (React, Solid, Vue bindings)
+  with dependency linking. Activate when producing skill files from a domain
+  map, updating existing skills after a library version change, or auditing
+  skill accuracy. Takes domain_map.yaml and skill_spec.md from
+  skill-domain-discovery as primary inputs.
+metadata:
+  version: "2.1"
+  category: meta-tooling
+  input_artifacts:
+    - domain_map.yaml
+    - skill_spec.md
+  skills:
+    - skill-domain-discovery
+---
+
+# Skill Tree Generator
+
+You produce and maintain a tree of SKILL.md files for a library. Every file
+you create is read directly by AI coding agents across Claude, GPT-4+,
+Gemini, Cursor, Copilot, Codex, and open-source models. Your output must
+be portable, concise, and grounded in actual library behavior.
+
+Skills are split into two layers:
+
+- **Core skills** — framework-agnostic concepts, configuration, and patterns
+- **Framework skills** — framework-specific bindings, hooks, components
+
+Agents discover skills via `tanstack playbook list` and read them directly
+from `node_modules`. Framework skills declare a `requires` dependency on
+their core skill so agents load them in the right order.
+
+There are two workflows. Detect which applies.
+
+**Workflow A — Generate:** Build a complete skill tree from a domain map.
+**Workflow B — Update:** Diff a library version change and update skills.
+
+---
+
+## Workflow A — Generate skill tree
+
+### Prerequisites
+
+You need one of:
+- A `domain_map.yaml` and `skill_spec.md` from skill-domain-discovery
+- Raw library documentation and source code (run a compressed domain
+  discovery first)
+
+If starting from raw docs without a domain map, run a compressed
+discovery. This produces lower-fidelity output than the full
+skill-domain-discovery skill — prefer running that when time permits.
+
+1. Build a concept inventory (every export, config key, constraint, warning)
+2. Group into 4–7 capability domains using work-oriented names
+3. Extract 3+ failure modes per domain (plausible, silent, grounded)
+4. Proceed to Step 1 below
+
+### Step 1 — Plan the file tree
+
+From the domain map, determine which skills are core (framework-agnostic)
+and which are framework-specific.
+
+**Core vs framework decision:**
+
+| Content | Goes in... |
+|---------|-----------|
+| Mental models, concepts, lifecycle | Core |
+| Configuration options and their effects | Core |
+| Type system, generics, inference | Core |
+| Common mistakes that apply to all frameworks | Core |
+| Hooks (`useX`, `createX`) | Framework |
+| Components (`<Link>`, `<Outlet>`) | Framework |
+| Provider setup and wiring | Framework |
+| SSR/hydration patterns specific to a framework | Framework |
+| Framework-specific gotchas | Framework |
+
+If a library has no framework adapters (e.g. Store, DB), produce only
+core skills.
+
+**Framework-integration domain decomposition:** If the domain map from
+skill-domain-discovery contains a single "Framework Integration" domain
+and the library has separate framework adapter packages, decompose it
+into per-framework skills co-located with each adapter package. Do not
+produce a single monolithic framework-integration skill that covers
+React, Vue, Solid, etc. in one file.
+
+**Adapter-heavy domains:** When a domain covers multiple backends or
+adapters with distinct config interfaces (e.g. 5 sync adapters, 3
+database drivers), keep one SKILL.md for the shared patterns but
+produce one reference file per adapter with its specific config,
+setup, and gotchas. The SKILL.md covers what's common; each
+`references/[adapter].md` covers what's unique.
+
+**Skill output structure:**
+
+```
+skills/
+├── [lib]-core/                   # Core skill for the library
+│   ├── SKILL.md                  # Core overview + sub-skill registry
+│   ├── [domain-1]/
+│   │   └── SKILL.md             # Core sub-skill
+│   ├── [domain-2]/
+│   │   └── SKILL.md
+│   └── references/              # Optional overflow content
+│       └── options.md
+├── react-[lib]/                  # React framework skill
+│   ├── SKILL.md                  # React overview + sub-skill registry
+│   ├── [domain-1]/
+│   │   └── SKILL.md             # React-specific sub-skill
+│   └── references/
+├── solid-[lib]/                  # Solid framework skill (if applicable)
+│   └── SKILL.md
+├── vue-[lib]/                    # Vue framework skill (if applicable)
+│   └── SKILL.md
+```
+
+**Source repository layout for npm distribution:**
+
+Skills must ship with their respective packages so they're available in
+`node_modules` after install. In a monorepo, co-locate skills with the
+package they document:
+
+```
+packages/
+├── [lib]/                        # Core package
+│   ├── src/
+│   ├── skills/                   # Core skills live here
+│   │   ├── [lib]-core/
+│   │   │   ├── SKILL.md
+│   │   │   └── [domain]/SKILL.md
+│   │   └── compositions/        # Composition skills with co-used libs
+│   └── package.json             # Add "skills" to files array
+├── react-[lib]/                  # React adapter package
+│   ├── src/
+│   ├── skills/                   # React framework skills live here
+│   │   └── react-[lib]/
+│   │       └── SKILL.md
+│   └── package.json             # Add "skills" to files array
+```
+
+Add `"skills"` to each package's `files` array in `package.json` so
+skill files are included in the published npm tarball:
+
+```json
+{
+  "files": ["dist", "src", "skills"]
+}
+```
+
+### Step 2 — Write the core skill
+
+The core skill is the foundational overview for the library. It covers
+framework-agnostic concepts and contains the sub-skill registry.
+
+**Frontmatter:**
+
+```yaml
+---
+name: [lib]-core
+description: >
+  [1–3 sentences. What this library does and the framework-agnostic
+  concepts it provides. Pack with keywords: function names, config
+  options, concepts. This is a routing key, not a human summary.]
+type: core
+library: [lib]
+library_version: "[version this targets]"
+---
+```
+
+**Body template:**
+
+```markdown
+# [Library Name] — Core Concepts
+
+[One paragraph: what this library is, what problem it solves. Factual,
+not promotional. Framework-agnostic.]
+
+## Sub-Skills
+
+| Need to... | Read |
+|------------|------|
+| [task 1] | [lib]-core/[domain-1]/SKILL.md |
+| [task 2] | [lib]-core/[domain-2]/SKILL.md |
+
+## Quick Decision Tree
+
+- Setting up for the first time? → [lib]-core/[setup-domain]
+- Working with [concept]? → [lib]-core/[concept-domain]
+- Debugging [issue]? → [lib]-core/[domain] § Common Mistakes
+
+## Version
+
+Targets [library] v[X.Y.Z].
+```
+
+### Step 3 — Write core sub-skills
+
+One SKILL.md per domain. Follow this structure exactly.
+
+**Frontmatter:**
+
+```yaml
+---
+name: [lib]-core/[domain-slug]
+description: >
+  [1–3 sentences. What this domain covers AND when to load it. Name
+  specific functions, options, or APIs. Dense routing key.]
+type: sub-skill
+library: [lib]
+library_version: "[version]"
+sources:
+  - "[repo]:docs/[path].md"
+  - "[repo]:src/[path].ts"
+---
+```
+
+**Body sections — in this order:**
+
+**1. Setup**
+
+Minimum working example for this domain.
+- Use the library's core API, not framework-specific hooks
+- Real package imports with exact names
+- No `// ...` or `[your code here]` — complete and copy-pasteable
+- If a concept is better explained with a framework hook, reference the
+  framework skill: "For React usage, see `react-[lib]/SKILL.md`"
+
+**2. Core Patterns**
+
+2–4 patterns. For each:
+- One-line heading: what it accomplishes
+- Complete code block using core API
+- One sentence of explanation only if not self-explanatory
+- No framework-specific code — use core abstractions
+
+**3. Common Mistakes**
+
+Each `failure_mode` entry from the domain map becomes a Common Mistake
+entry in the SKILL file. Minimum 3 entries. Complex domains target 5–6.
+
+**Cross-domain failure modes:** The domain map may contain failure modes
+with a `domains` list naming multiple domain slugs. Write these into
+every SKILL file whose domain is listed. A developer loading the SSR
+skill and a developer loading the state management skill both need to
+see "stale state during hydration" — the same advice must appear in
+both files. Do not deduplicate across skills at the cost of coverage.
+
+Format:
+
+```markdown
+### [PRIORITY] [What goes wrong — 5–8 word phrase]
+
+Wrong:
+```[lang]
+// code that looks correct but isn't
+```
+
+Correct:
+```[lang]
+// code that works
+```
+
+[One sentence: the specific mechanism by which the wrong version fails.]
+
+Source: [doc page or source file:line]
+```
+
+Priority levels:
+- **CRITICAL** — Breaks in production. Security risk or data loss.
+- **HIGH** — Incorrect behavior under common conditions.
+- **MEDIUM** — Incorrect under specific conditions or edge cases.
+
+Every mistake must be plausible (an agent would generate it), silent
+(no immediate crash), and grounded (traceable to doc or source).
+
+**Failure mode status from domain map:** The domain map may include a
+`status` field on failure modes. Handle as follows:
+- `active` — Include as a normal Common Mistake entry
+- `fixed-but-legacy-risk` — Include with a note: "Fixed in v[X] but
+  agents trained on older code may still generate this pattern"
+- `removed` — Do not include. The bug is fixed and the pattern is no
+  longer relevant.
+
+**4. References** (only when needed)
+
+```markdown
+## References
+
+- [Complete option reference](references/options.md)
+```
+
+Create reference files when any of these apply — not just length overflow:
+
+- **Length:** The skill would exceed 500 lines without them
+- **Multiple subsystems:** The domain covers 3+ independent backends,
+  adapters, or providers with distinct config interfaces. Create one
+  reference file per subsystem (e.g. `references/electric-adapter.md`,
+  `references/query-adapter.md`)
+- **Dense API surface:** A topic has >10 distinct API patterns, operators,
+  or option shapes that agents need for implementation. Move the full
+  reference to `references/` and keep only the most common 2–3 in the
+  SKILL.md
+- **Deep validation/schema patterns:** If the library has schema
+  validation, type transforms (TInput/TOutput), or similar deep
+  configuration surfaces, give them a dedicated reference file even if
+  they technically fit in the parent skill
+
+### Step 4 — Write framework skills
+
+Framework skills build on their core skill. They cover only what is
+specific to the framework — hooks, components, providers, and
+framework-specific patterns and mistakes.
+
+**Frontmatter:**
+
+```yaml
+---
+name: react-[lib]
+description: >
+  [1–3 sentences. React-specific bindings for [library]. Name the hooks,
+  components, and providers. Mention React-specific patterns like SSR
+  hydration if applicable.]
+type: framework
+library: [lib]
+framework: react
+library_version: "[version]"
+requires:
+  - [lib]-core
+---
+```
+
+**Body template:**
+
+```markdown
+This skill builds on [lib]-core. Read [lib]-core first for foundational
+concepts before applying React-specific patterns.
+
+# [Library Name] — React
+
+## Setup
+
+[React-specific setup: provider, hook wiring, app entry point]
+
+## Hooks and Components
+
+[React hooks and components with complete examples]
+
+## React-Specific Patterns
+
+[Patterns that only apply in React: concurrent features, Suspense
+integration, SSR/hydration, etc.]
+
+## Common Mistakes
+
+[Only React-specific mistakes. Do not repeat core mistakes. Examples:
+calling hooks outside provider, missing Suspense boundary, hydration
+mismatch, etc.]
+```
+
+**Framework sub-skills** follow the same pattern as core sub-skills but
+with the framework frontmatter:
+
+```yaml
+---
+name: react-[lib]/[domain-slug]
+description: >
+  [React-specific description for this domain.]
+type: sub-skill
+library: [lib]
+framework: react
+library_version: "[version]"
+requires:
+  - [lib]-core
+  - [lib]-core/[domain-slug]
+---
+
+This skill builds on [lib]-core/[domain-slug]. Read the core skill first.
+```
+
+### Step 5 — Write cross-domain tension notes
+
+The domain map may contain a `tensions` section listing design conflicts
+between domains. For each tension, add a brief note to the Common
+Mistakes section of every SKILL file whose domain is involved. Format:
+
+```markdown
+### HIGH Tension: [short phrase]
+
+This domain's patterns conflict with [other domain]. [One sentence
+describing the pull.] Agents optimizing for [this domain's goal]
+tend to [specific mistake] because they don't account for [other
+domain's constraint].
+
+See also: [lib]-core/[other-domain]/SKILL.md § Common Mistakes
+```
+
+The cross-reference ensures agents that load one skill are pointed
+toward the related skill where the other side of the tension lives.
+
+### Step 6 — Write composition skills (if applicable)
+
+Use the `compositions` entries from `domain_map.yaml` (populated during
+skill-domain-discovery Phase 2h) to identify which composition skills
+to produce.
+
+Composition skills cover how two or more libraries work together. These
+are framework-specific by default (the integration patterns depend on
+framework hooks and providers).
+
+**Frontmatter:**
+
+```yaml
+---
+name: compositions/[lib-a]-[lib-b]
+description: >
+  [How lib-a and lib-b wire together. Name the specific integration
+  points: functions, hooks, patterns.]
+type: composition
+library_version: "[version of primary lib]"
+requires:
+  - [lib-a]-core
+  - react-[lib-a]
+  - [lib-b]-core
+  - react-[lib-b]
+---
+
+This skill requires familiarity with both [lib-a] and [lib-b].
+Read their core and framework skills first.
+```
+
+**Body structure:**
+
+1. **Integration Setup** — How to wire the two libraries together
+2. **Core Integration Patterns** — 2–4 patterns showing them working in concert
+3. **Common Mistakes** — Mistakes that only occur at the integration boundary
+
+Do not duplicate content from either library's individual skills. Focus
+exclusively on the seam between them.
+
+### Step 7 — Write security/go-live skills (where applicable)
+
+For libraries that have security-sensitive surface area (server functions,
+auth, data exposure):
+
+```yaml
+---
+name: react-[lib]/security
+description: >
+  Go-live security validation for [library]. Checks [specific concerns].
+type: security
+library: [lib]
+framework: react
+library_version: "[version]"
+requires:
+  - react-[lib]
+---
+```
+
+Structure as a checklist the agent can run through before deployment:
+
+1. **Validation checks** — What to verify, with code showing correct config
+2. **Common security mistakes** — Wrong/correct pairs specific to this library
+3. **Pre-deploy checklist** — Ordered list of verifications
+
+### Step 8 — Validate the complete tree
+
+Run every check before outputting. Fix any failures before proceeding.
+
+| Check | Rule |
+|-------|------|
+| Every domain from domain_map has a skill | No orphaned domains |
+| Core/framework split is clean | No framework hooks in core skills |
+| Every framework skill has `requires` | Links to its core skill |
+| Framework skill opens with dependency note | "builds on [core]" prose line |
+| Every skill under 500 lines | Move excess to references/ |
+| Every code block has real imports | Exact package name, correct adapter |
+| No concept explanations | No "TypeScript is...", no "React hooks are..." |
+| No marketing prose | First body line is heading or dependency note |
+| Every code block is complete | Works without modification when pasted |
+| Common Mistakes are silent | Not obvious compile errors |
+| Common Mistakes are library-specific | Not generic TS/React mistakes |
+| Common Mistakes are sourced | Every mistake traceable to doc or source |
+| Core skills reference framework skills | "For React usage, see..." |
+| Framework skills don't repeat core content | Only framework-specific |
+| Composition skills don't repeat individual skills | Only the seam |
+| `name` matches directory path | `router-core/search-params` → `router-core/search-params/SKILL.md` |
+| `sources` filled in sub-skills | At least one repo:path per sub-skill |
+| Cross-domain failures in all relevant skills | Failure modes with multiple `domains` appear in each listed skill |
+| Tensions noted in affected skills | Each tension has notes in all involved domain skills |
+| Framework domains decomposed per-package | No single skill covering multiple framework adapters |
+| Adapter-heavy domains have references | 3+ adapters/backends → one reference file per adapter |
+| Dense API surfaces in references | >10 distinct patterns → reference file, not inline |
+
+---
+
+## Workflow B — Update existing skills
+
+### Trigger conditions
+
+Run when:
+- The library has released a new version
+- A maintainer reports skills produce outdated code
+- A changelog or migration guide has been published since skill creation
+- Feedback reports indicate skill content is inaccurate
+
+### Step 1 — Detect staleness
+
+Compare each skill's `library_version` against the current library version.
+
+1. Read changelog entries between the two versions
+2. Read migration guide (if one exists)
+3. For each skill, check if its `sources` files have changed
+
+Produce a staleness report:
+
+```yaml
+# staleness_report.yaml
+library: "[name]"
+library_version_in_skills: "[old]"
+library_version_current: "[new]"
+
+stale_skills:
+  - skill: "[skill name]"
+    reason: "[what changed]"
+    severity: "[BREAKING | DEPRECATION | BEHAVIORAL | ADDITIVE]"
+    changelog_entry: "[relevant entry]"
+    affected_sections:
+      - "[Setup | Core Patterns | Common Mistakes]"
+
+current_skills:
+  - skill: "[skill name]"
+    reason: "[no changes affect this domain]"
+```
+
+### Step 2 — Update stale skills
+
+**BREAKING changes:**
+1. Old pattern becomes a new Common Mistake entry (wrong/correct pair)
+2. Update Setup if initialization changed
+3. Update Core Patterns if idiomatic approach changed
+4. Bump `library_version` in frontmatter
+5. Check both core AND framework skills — breaking changes may affect both
+
+**DEPRECATION changes:**
+1. Add Common Mistake: deprecated API as wrong, replacement as correct
+2. Update Core Patterns to use non-deprecated API
+3. Bump `library_version`
+
+**BEHAVIORAL changes:**
+1. Default value changed → add Common Mistake entry
+2. Type signature more restrictive → add Common Mistake entry
+3. Update affected code blocks
+4. Bump `library_version`
+
+**ADDITIVE changes:**
+1. Evaluate if new feature belongs in existing domain or needs a new skill
+2. If existing: add to Core Patterns or references/
+3. If new skill needed: create it and update the parent skill's sub-skill
+   registry
+4. Bump `library_version`
+
+### Step 3 — Produce a changelog entry
+
+```markdown
+## [date]
+
+### Updated for [library] v[new version]
+
+**Breaking changes:**
+- [skill name]: [what changed and why]
+
+**Deprecation updates:**
+- [skill name]: [old API] → [new API]
+
+**New skills:**
+- [skill name]: [what it covers]
+```
+
+---
+
+## Constraints — verify for every file
+
+| Check | Rule |
+|-------|------|
+| Under 500 lines per SKILL.md | Move excess to references/; also create references for content depth |
+| Real imports in every code block | Exact package, correct adapter |
+| No external concept explanations | No "TypeScript is...", no "React hooks are..." — library-specific concepts are fine |
+| No marketing prose | First body line is heading, code, or dependency note |
+| Complete code blocks | Every block works without modification |
+| Common Mistakes are silent | Not obvious compile errors |
+| Common Mistakes are library-specific | Not generic TS/React mistakes |
+| Common Mistakes are sourced | Traceable to doc or source |
+| Core skills are framework-agnostic | No hooks, no components, no providers |
+| Framework skills have `requires` | Lists core dependency |
+| Framework skills open with dependency note | First prose line references core |
+| Composition skills require all dependencies | Lists all core + framework skills |
+| `name` matches directory | `router-core/search-params` → file at that path |
+| `library_version` in every frontmatter | Which version the skill targets |
+| Cross-domain failures duplicated | Each listed domain gets the failure mode |
+| Tensions cross-referenced | Tension notes in each involved skill point to the other |
+| Skills ship with packages | `"skills"` in package.json `files` array |
+
+---
+
+## Cross-model compatibility
+
+Output is consumed by all major AI coding agents. To ensure consistency:
+
+- Markdown with YAML frontmatter — universally parsed
+- No XML tags in generated skill content
+- Code blocks use triple backticks with language annotation
+- Section boundaries use ## headers
+- Descriptions are keyword-packed for routing
+- Examples show concrete values, never placeholders
+- Positive instructions ("Use X") over negative ("Don't use Y")
+- Critical info at start or end of sections (not buried in middle)
+- Each SKILL.md is self-contained except for declared `requires`
+
+---
+
+## Output order
+
+When generating a complete skill tree:
+
+1. Core overview SKILL.md — entry point for the library
+2. Core sub-skills in domain order
+3. Framework overview SKILL.md for each framework
+4. Framework sub-skills
+5. Composition skills (if applicable)
+6. Security skills (if applicable)
+7. references/ files for any skill that needs them
+8. CHANGELOG.md entry
+
+When updating:
+
+1. staleness_report.yaml
+2. Updated SKILL.md files (core then framework)
+3. CHANGELOG.md entry