skill-tree-generator

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
4. Extract 3+ failure modes per skill (plausible, silent, grounded)
5. 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:

```[lang]
// 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)

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

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

```[lang]
// 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.

| Check | Rule |
|-------|------|
| Every skill from domain_map has a SKILL.md | No orphaned skills |
| 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-skill failures in all relevant files | Failure modes with multiple `skills` appear in each listed SKILL.md |
| 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 |
| Checklist skills use audit body | Security/go-live skills use checklist template, not Setup → Core Patterns → Common Mistakes |

---

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

```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

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

---