Terminal
Terminal/Skill
Generates a tree of SKILL.md files for a JavaScript or TypeScript library from an approved domain map and skill spec.
By TanStack
Works with
npx skills add tanstack/intent --skill tree-generatorYou 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, Codex, Gemini, Cursor, Copilot, and open-source models. Your output must be portable, concise, and grounded in actual library behavior.
Every skill has a metadata.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 npm exec --no -- 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: Review identified changes against existing guidance.
Before writing any skill, apply the shared writing rules.
You need one of:
skills/_artifacts/domain_map.yaml and skills/_artifacts/skill_spec.md from domain-discoveryIf starting from raw docs without a domain map, run a compressed discovery. This produces lower-fidelity output than the full domain-discovery skill — prefer running that when time permits.
If the maintainer uses a custom skills root, replace skills/ in the paths below with their chosen directory.
Focused batches use the format below through generate-skill’s planning record procedure, extending the existing tree with the batch. Reading this format does not start full-library discovery.
For the full-library scaffold workflow, produce a single artifact before writing any SKILL.md files:
skills/_artifacts/skill_tree.yamlThis 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: 'Use when [concrete developer tasks or conditions] with [library/framework]. [Adjacent-task boundary, when needed.]'
purpose: '[Descriptive explanation; emitted as metadata.purpose in SKILL.md.]'
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.
If tasks stand alone, there are no framework adapter packages, and a shared overview would add no necessary guidance, skip the core overview + sub-skill registry pattern. Instead:
skills/[skill-name]/SKILL.mdlist command is sufficient for discoverycore (not sub-skill) and stands alone without a parent registryThis avoids unnecessary scaffolding for focused libraries where the overhead of a hierarchical skill tree exceeds the navigation benefit.
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 (<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, produce only core skills.
Framework-integration domain decomposition: If the domain map from 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:
Use flat (skills/[skill-name]/SKILL.md) when:
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: Add a router only when its decision guidance helps agents choose between tasks that intent list and the skills' descriptions cannot adequately distinguish. Skill count alone does not justify a router.
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
Publishing configuration is separate from authoring. When the maintainer requests it, npm exec --no -- intent edit-package-json prepares the package; review its resulting diff.
When writing skill files (after the scaffold plan is approved), read the skill-writing procedures and templates. Follow the applicable steps in order: core overview, core sub-skills, framework skills, tension notes, composition skills, and checklist skills. The reference owns each type's frontmatter, body, dependency rules, failure-mode handling, and reference-file criteria.
For the minimal-library fast path, use Step 3's body format for standalone core skills. For scaffold-only requests, stop after skill_tree.yaml.
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 cover real failures | Preserve silent failures and necessary error handling |
| 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 parent directory | name: 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 | Every affected entry point routes to the authoritative failure guidance |
| 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 | Conditional adapter details have precise reading pointers |
| Dense API surfaces in references | Conditional API details are referenced by task relevance |
| Checklist skills use audit body | Security/go-live skills use checklist template, not Setup → Core Patterns → Common Mistakes |
When a library version, changelog, migration guide, or accuracy report requires updating existing skills, read the update workflow. Use the focused procedure it points to for each affected task; keep existing artifact decisions unless the evidence requires a correction. Apply the constraints below to every updated file.
| Check | Rule |
|---|---|
| Under 500 lines per SKILL.md | Use relevant references while retaining necessary guidance |
| 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 cover real failures | Preserve silent failures and necessary error handling |
| 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 parent directory | name: search-params → router-core/search-params/SKILL.md |
library_version in every frontmatter | Which version the skill targets |
| Cross-skill failures accessible | Each listed skill points to the authoritative failure guidance |
| Tensions cross-referenced | Tension notes in each involved skill point to the other |
| Skills ship with packages | "skills" in package.json files array |
| Checklist skills use audit template | Security/go-live skills use checklist body, not standard body |
Output is consumed by all major AI coding agents. To ensure consistency:
requiresWhen generating a complete skill tree:
When updating:
Return the evidence, focused diffs or justified no-ops, validation results, and unresolved uncertainty required by generate-skill.