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, Codex, Gemini, Cursor, Copilot, and open-source models. Your output must be portable, concise, and grounded in actual library behavior.

Skill types

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.

---

Workflow A — Generate skill tree

Prerequisites

You need one of:

• skills/_artifacts/domain_map.yaml and skills/_artifacts/skill_spec.md from 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 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. Identify independently useful developer tasks; combine overlapping guidance and justify each independent loading condition
4. Extract the failure modes supported by the sources for each task
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.

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

Minimal library fast path

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:

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

• Developer tasks cluster cleanly into 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: 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.

Steps 2–7 — Write skills

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.

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

---

Workflow B — Update existing skills

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.

Constraints — verify for every 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

---

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 state distinct loading conditions
• 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:

Return the evidence, focused diffs or justified no-ops, validation results, and unresolved uncertainty required by generate-skill.

---