skill-generate
Generate a complete SKILL.md file for a library from source documentation and skill tree artifacts. Activate when bootstrapping skills for a new library, regenerating a stale skill after source changes, or producing a skill from a skill_tree.yaml entry. Takes a skill name, description, and source docs as inputs; outputs a validated SKILL.md that conforms to the tree-generator spec.
TanStack · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add TanStack/intent --skill skill-generate技能说明
name: skill-generate description: > Generate a complete SKILL.md file for a library from source documentation and skill tree artifacts. Activate when bootstrapping skills for a new library, regenerating a stale skill after source changes, or producing a skill from a skill_tree.yaml entry. Takes a skill name, description, and source docs as inputs; outputs a validated SKILL.md that conforms to the tree-generator spec. metadata: version: '1.0' category: meta-tooling input_artifacts: - skills/_artifacts/skill_tree.yaml - skills/_artifacts/domain_map.yaml - skills/_artifacts/skill_spec.md - source documentation output_artifacts: - SKILL.md skills: - skill-tree-generator - skill-domain-discovery
Skill Generation
You are generating a SKILL.md file for the @tanstack/intent agent skills
repo. Skills in this repo are written for coding agents (Claude Code, Cursor,
Copilot, Warp Oz, Codex), not for human readers. Your output will be loaded
into an agent's context window and used to guide code generation.
There are two modes. Detect which applies.
Mode A — Generate from domain map: A domain_map.yaml and skill_spec.md
exist. Generate the skill specified by name from these artifacts plus the
source documentation they reference.
Mode B — Generate from raw docs: No domain map exists. Generate directly from source documentation provided as input.
Inputs
You will receive:
If the maintainer uses a custom skills root, replace skills/ in any paths
below with their chosen directory.
Monorepo: When the skill tree entry has a package field, write the
SKILL.md into that package's skills directory (e.g.
packages/client/skills/core/SKILL.md), not a shared root.
- Skill path — format
library-group/skill-name(e.g.tanstack-query/core,tanstack-router/loaders,db/core/live-queries). This is the skill's directory path, and it is where theSKILL.mdlives. Only its last segment becomes the frontmattername(a spec-legal leaf): the full path is never written intoname, andnamemust contain no slashes. - Skill description — what the skill covers and when an agent should load it
- Source documentation — the docs, guides, API references, and/or source files to distill from
- Domain map entry (Mode A only) — the skill's entry from
domain_map.yamlincluding failure modes, subsystems, compositions, and source references
Step 1 — Determine skill type
Read the inputs and classify the skill type:
| Type | When to use |
|---|---|
core | Framework-agnostic concepts, configuration, patterns |
sub-skill | A focused sub-topic within a core or framework skill |
framework | Framework-specific bindings, hooks, components |
lifecycle | Cross-cutting developer journey (getting started, go-live) |
composition | Integration between two or more libraries |
security | Audit checklist or security validation |
The skill type determines the frontmatter and body structure. See skill-tree-generator for the full spec of each type.
Subagent guidance for batch generation
When generating multiple skills, spawn a separate subagent for each skill (or per-package group). Each subagent receives the domain_map.yaml, skill_tree.yaml, and the source docs relevant to its skill. This prevents context bleed between skills and allows parallel generation.
Step 2 — Extract content from sources
Line budget: Each SKILL.md must stay under 500 lines. Before writing, estimate the content size. If a skill has 5+ failure modes, 3+ primary patterns, and subsystem details, proactively plan reference files during extraction — don't wait until the skill exceeds the limit.
Read through the source documentation. Extract only what a coding agent cannot already know:
What to extract
- API shapes — function signatures, hook parameters, option objects, return types. Use the actual TypeScript types from source.
- Setup patterns — minimum viable initialization code
- Primary patterns — the 2–4 most important usage patterns
- Configuration — defaults that matter, options that change behavior
- Failure modes — patterns that look correct but break. Prioritize:
- Migration-boundary mistakes (old API that agents trained on older data produce)
- Silent failures (no crash, wrong behavior)
- Framework-specific gotchas (hydration, hook rules, provider ordering)
- Constraints and invariants — ordering requirements, lifecycle rules, things enforced by runtime assertions
- Issue/discussion-sourced patterns — real developer mistakes and confusion surfaced from GitHub issues and discussions (see below)
2b — Scan GitHub issues and discussions
Before writing the skill body, search the library's GitHub repo for issues and discussions relevant to THIS skill's topic. This step is important for both initial generation and regeneration — issue discussions reveal failure modes that docs miss.
Search strategy:
- Search issues for the skill's primary APIs, hooks, and config options
by name (e.g.
useQuery invalidation,createRouter middleware) - Filter to high-signal threads: sort by reactions/comments, focus on closed bugs with workarounds and open questions with long threads
- Search Discussions (if the repo uses them) for "how do I…" threads related to the skill's topic
- Check for issues labeled
bug,question,breaking-changethat mention concepts this skill covers
What to incorporate:
- Recurring bug workarounds → add as Common Mistakes entries with
wrong/correct code pairs. Cite the issue URL in the
Sourcefield. - Frequently asked questions → if the answer is non-obvious, add it