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:

| Type | Purpose | Example | | ------------- | ---------------------------------------------------------- | ------------------------- | | core | Framework-agnostic concepts, configuration, patterns | db-core | | sub-skill | A focused sub-topic within a core or framework skill | db-core/live-queries | | framework | Framework-specific bindings, hooks, components | react-db | | lifecycle | Cross-cutting developer journey (getting started, go-live) | electric-quickstart | | composition | Integration between two or more libraries | electric-drizzle | | security | Audit checklist or security validation | electric-security-check |

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:

| 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 (`, `) | 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.

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:

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

## 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.]
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 Comp

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [TanStack](https://github.com/TanStack)
- **Source:** [TanStack/intent](https://github.com/TanStack/intent)
- **License:** MIT
- **Homepage:** https://tanstack.com/intent/latest

Install and usage instructions live in the source repository linked above.