version: "1.0.1" 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: '3.0' category: meta-tooling input_artifacts:

• skills/_artifacts/domain_map.yaml
• skills/_artifacts/skill_spec.md

output_artifacts:

• skills/_artifacts/skill_tree.yaml

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.

Skill types

Every skill has a type field in its frontmatter. Valid types:

Agents discover skills via npx @tanstack/intent 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:

• skills/_artifacts/domain_map.yaml and skills/_artifacts/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 capability domains using work-oriented names (let library complexity drive the count — 2–3 for focused libraries, more for large frameworks)
3. Enumerate 10–20 task-focused skills from the intersection of domains

and developer tasks

1. Extract 3+ failure modes per skill (plausible, silent, grounded)
2. Proceed to Step 1 below

Scaffold flow output

If the maintainer uses a custom skills root, replace skills/ in the paths below with their chosen directory.

For the scaffold workflow, produce a single artifact before writing any SKILL.md files:

• skills/_artifacts/skill_tree.yaml

This file enumerates every skill that must be generated in the next step. Do not write SKILL.md files yet unless explicitly asked.

Use this format:

# skills/_artifacts/skill_tree.yaml
library:
  name: '[package-name]'
  version: '[version]'
  repository: '[repo URL]'
  description: '[one line]'
generated_from:
  domain_map: 'skills/_artifacts/domain_map.yaml'
  skill_spec: 'skills/_artifacts/skill_spec.md'
generated_at: '[ISO date]'
 
skills:
  - name: '[task-focused skill name]'
    slug: '[kebab-case]'
    type: 'core | sub-skill | framework | lifecycle | composition | security'
    domain: '[domain slug]'
    path: 'skills/[path]/SKILL.md'
    package: '[package directory, e.g. packages/client]' # monorepo only — which package this skill belongs to
    description: '[1–2 sentence agent-facing routing key]'
    requires:
      - '[other skill slugs]' # omit if none
    sources:
      - '[Owner/repo]:docs/[path].md'
      - '[Owner/repo]:src/[path].ts'
    subsystems:
      - '[adapter/backend name]' # omit if none
    references:
      - 'references/[file].md' # omit if none

Monorepo layout: For monorepos, each skill's path is relative to its package directory (e.g. packages/client/skills/core/SKILL.md). Set the package field so generate-skill knows where to write the file. The domain map artifacts stay at the repo root.

Minimal library fast path

If the domain map contains fewer than 5 skills and no framework adapter packages, skip the core overview + sub-skill registry pattern. Instead:

• Use flat structure — each skill gets its own skills/[skill-name]/SKILL.md
• No router skill — the intent CLI list command is sufficient for discovery
• No core overview skill — go directly to individual skill files
• Each skill is type core (not sub-skill) and stands alone without

a parent registry

• Skip Step 2 (core overview) and Step 3 (sub-skills) — go directly to

writing individual skills as standalone core skills using Step 3's body format

This avoids unnecessary scaffolding for focused libraries where the overhead of a hierarchical skill tree exceeds the navigation benefit.

Step 1 — Plan the file tree

From the domain map, each entry in the skills list becomes a SKILL.md file. The type field on each skill (core, framework, lifecycle, composition) determines where it goes. Determine the file tree:

Core vs framework decision:

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.

Flat vs nested structure:

Choose the structure that matches how the domain map's skills are shaped.

Use nested ([lib]-core/[domain]/SKILL.md) when:

• Developer tasks cluster cleanly into 3–5 conceptual domains
• The library has a clear core + framework adapter split
• Skills build on each other in a layered way

Use flat (skills/[skill-name]/SKILL.md) when:

• Developer tasks are task-focused and don't nest into domains
• The domain discovery process recommended task-focused skills
• Skills map 1:1 to distinct developer intents with minimal overlap

Both are valid. The domain map's type field and structure will signal which fits. When in doubt, prefer flat — it's simpler and each skill is independently discoverable.

Nested 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

Flat structure:

skills/
├── [lib]-shapes/                 # Task-focused skill
│   ├── SKILL.md
│   └── references/
│       └── shape-options.md
├── [lib]-auth/                   # Another task skill
│   └── SKILL.md
├── [lib]-proxy/
│   └── SKILL.md
├── [lib]-quickstart/             # Lifecycle skill
│   └── SKILL.md
├── [lib]-go-live/                # Lifecycle skill
│   └── SKILL.md
├── [lib]-drizzle/                # Composition skill
│   └── SKILL.md

Router skill: A router skill (lightweight entry point with a decision table) is optional. If the intent CLI provides list and show commands, agents can discover skills directly without a router. Only create a router skill if the skill set is large enough (15+) that browsing the list is insufficient, or if the nested structure needs an entry point to guide agents to the right sub-skill. Libraries with fewer than 5 skills should never have a router skill.

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

Run npx @tanstack/intent@latest edit-package-json to wire each package's package.json automatically (adds "skills", "bin", and "!skills/_artifacts" to the files array, and adds the bin entry if missing).

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:

---
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.]
metadata:
  type: core
  library: '[lib]'
  library_version: '[version this targets]'
---

Body template:

# [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:

---
name: '[domain-slug]'
description: >
  [1–3 sentences. What this domain covers AND when to load it. Name
  specific functions, options, or APIs. Dense routing key.]
metadata:
  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-skill failure modes: The domain map may contain failure modes with a skills list naming multiple skill slugs. Write these into every SKILL file whose skill 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:

### [PRIORITY] [What goes wrong — 5–8 word phrase]
 
Wrong:
 

// code that looks correct but isn't

Correct:

// 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)
 

References

• Complete option reference

 
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:**
 

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.] metadata: type: framework library: '[lib]' framework: react library_version: '[version]' requires:

• '[lib]-core'

 
**Body template:**
 

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:
 

name: '[domain-slug]' description: > [React-specific description for this domain.] metadata: 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:
 

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.
 
Also check the domain map's `cross_references` section for non-tension
relationships between skills. For each cross-reference, add a "See also"
line at the end of the relevant skill's body:
 

See also: [other-skill]/SKILL.md — [reason]

 
### Step 6 — Write composition skills (if applicable)
 
Use the `compositions` entries from `domain_map.yaml` (populated during
skill-domain-discovery Phase 3h) 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:**
 

name: '[lib-a]-[lib-b]' description: > [How lib-a and lib-b wire together. Name the specific integration points: functions, hooks, patterns.] metadata: 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 checklist/audit skills (where applicable)
 
Some skills don't fit the standard body structure (Setup → Core Patterns
→ Common Mistakes). Security, go-live, and some lifecycle skills are
audit-oriented — the agent runs through a checklist to verify correctness
rather than learning patterns. Use the alternative body structure below
for these skill types.
 
**When to use the checklist body:**
 
- `security` type skills — pre-deploy security validation
- `lifecycle` type skills focused on verification (go-live, migration)
- Any skill where the primary action is "check these things" not "learn
  these patterns"
 
**Frontmatter:**
 

name: security description: > Go-live security validation for [library]. Checks [specific concerns]. metadata: type: security library: '[lib]' framework: react library_version: '[version]' requires:

• 'react-[lib]'

 
**Alternative body template (checklist/audit):**
 

[Library Name] — [Security | Go-Live | Migration] Checklist

Run through each section before [deploying | releasing | migrating].

[Category 1] Checks

Check: [what to verify]

Expected:

// correct configuration or code

 
Fail condition: [what indicates this check failed]
Fix: [one-line remediation]
 
### Check: [what to verify]
 
[same structure]
 
## [Category 2] Checks
 
[same structure]
 
## Common Security Mistakes
 
[Wrong/correct pairs specific to this library, same format as
Common Mistakes in standard skills]
 
## Pre-Deploy Summary
 
- [ ] [Verification 1]
- [ ] [Verification 2]
- [ ] [Verification 3]
 

The key differences from the standard body:

• No "Setup" section — the agent already has the app running
• Checks replace "Core Patterns" — each check is a verification, not a

teaching pattern

• The summary checklist at the end gives agents a quick pass/fail list
• Common Mistakes section is still present for wrong/correct pairs

Step 8 — Validate the complete tree

Run every check before outputting. Fix any failures before proceeding.

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
• Issue 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:

# 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

1. Bump library_version

Step 3 — Produce a changelog entry

## [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

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