技能生成
- 作者仓库星标 291
- 作者仓库 intent
- 领域
- 通用
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @TanStack · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
第 1 步 — 确定技能类型
阅读输入并对技能类型进行分类: 类型 · 何时使用 `core` · 与框架无关的概念、配置、模式 `sub-skill` · 核心或框架技能中的重点子主题 `framework` · 特定于框架的绑定、挂钩、组件
第 2 步 — 从源中提取内容
行预算:每个 SKILL.md 必须保持在 500 行以下。在写作之前,估计一下内容的大小。如果一项技能有 5 个以上的故障模式、3 个以上的主要模式和子系统详细信息,请在提取过程中主动规划参考文件 - 不要等到技能超出限制。通读源文档。只提取什么编码剂
第 5 步 — 验证
输出前运行每项检查。修复任何故障。检查 · 规则低于 500 行 · 将多余的内容移至引用/每个代码块中的真实导入 · 准确的包名称,正确的适配器 没有外部概念解释 · 没有“TypeScript 是...”,没有“React hooks 是...”
第 6 步 — 输出
在生成之前,询问维护者:“您想在我生成下一个技能之前单独检查每项技能,还是应该我生成所有技能,然后您一起检查它们?”尊重他们的喜好。输出完整的SKILL.md文件内容。如果需要参考文件,请输出这些文件及其相对路径。
# 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.
1. **Skill name** — format `library-group/skill-name` (e.g. `tanstack-query/core`,
`tanstack-router/loaders`, `db/core/live-queries`)
2. **Skill description** — what the skill covers and when an agent should load it
3. **Source documentation** — the docs, guides, API references, and/or source
files to distill from
4. **Domain map entry** (Mode A only) — the skill's entry from `domain_map.yaml`
including 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 — community feedback reveals
failure modes that docs miss.
**Search strategy:**
1. Search issues for the skill's primary APIs, hooks, and config options
by name (e.g. `useQuery invalidation`, `createRouter middleware`)
2. Filter to high-signal threads: sort by reactions/comments, focus on
closed bugs with workarounds and open questions with long threads
3. Search Discussions (if the repo uses them) for "how do I…" threads
related to the skill's topic
4. Check for issues labeled `bug`, `question`, `breaking-change` that
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 `Source` field.
- **Frequently asked questions** → if the answer is non-obvious, add it
to Core Patterns or as a dedicated pattern section
- **Misunderstandings about defaults** → add to Common Mistakes with the
incorrect assumption as the "wrong" pattern
- **Resolved issues that changed behavior** → if the old behavior is
still in agent training data, add as a migration-boundary mistake
**What NOT to incorporate:**
- One-off bugs already fixed with no broader pattern
- Feature requests for APIs that don't exist yet
- Issues about tooling, CI, or build that don't affect library usage
- Stale threads (>2 years old) about behavior that has fundamentally changed
**Fallback:** If no web access is available, check for FAQ.md,
TROUBLESHOOTING.md, or docs/faq in the repo. Also check whether the
domain_map.yaml already contains issue-sourced failure modes from
domain-discovery — use those directly.
### What NOT to extract
- TypeScript basics, React hooks concepts, general web dev knowledge
- Marketing copy, motivational prose, "why this library is great"
- Exhaustive API tables (move these to `references/` if needed)
- Content that duplicates another skill (reference it instead)
---
## Step 3 — Write the frontmatter
### Core skill frontmatter
```yaml
---
name: [library]/[skill-name]
description: >
[1–3 sentences. What this skill covers and exactly when an agent should
load it. Written for the agent — include the keywords an agent would
encounter when it needs this skill. Dense routing key.]
type: core
library: [library]
library_version: "[version this targets]"
sources:
- "[Owner/repo]:docs/[path].md"
- "[Owner/repo]:src/[path].ts"
---
```
### Sub-skill frontmatter
```yaml
---
name: [library]/[parent]/[skill-name]
description: >
[1–3 sentences. What this sub-topic covers and when to load it.]
type: sub-skill
library: [library]
library_version: "[version]"
sources:
- "[Owner/repo]:docs/[path].md"
---
```
### Framework skill frontmatter
```yaml
---
name: [library]/[framework]
description: >
[1–3 sentences. Framework-specific bindings. Name the hooks, components,
providers.]
type: framework
library: [library]
framework: [react | vue | solid | svelte | angular]
library_version: "[version]"
requires:
- [library]/core
sources:
- "[Owner/repo]:docs/framework/[framework]/[path].md"
---
```
### Frontmatter rules
- `description` must be written so the agent loads this skill at the right
time — not too broad (triggers on everything) and not too narrow (never
triggers). Pack with function names, option names, concept keywords.
- `sources` uses the format `Owner/repo:relative-path`. Glob patterns are
supported (e.g. `TanStack/query:docs/framework/react/guides/*.md`).
- `library_version` is the version of the source library this skill targets.
- `requires` lists skills that must be loaded before this one.
---
## Step 4 — Write the body
### Standard body (core, sub-skill, framework)
Follow this section order exactly:
**1. Dependency note** (framework and sub-skills only)
```markdown
This skill builds on [parent-skill]. Read it first for foundational concepts.
```
**2. Setup**
A complete, copy-pasteable code block showing minimum viable usage.
- Real package imports with exact names (`@tanstack/react-query`, not `react-query`)
- No `// ...` or `[your code here]` — complete and runnable
- No unnecessary boilerplate — include exactly the context needed
- For framework skills: framework-specific setup (provider, hook wiring)
- For core skills: framework-agnostic setup (no hooks, no components)
**3. Core Patterns** (or "Hooks and Components" for framework skills)
2–4 patterns. For each:
- One-line heading: what it accomplishes
- Complete code block
- One sentence of explanation only if not self-explanatory
**4. Common Mistakes**
Minimum 3 entries. Complex skills target 5–6. 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
- **Grounded** — traceable to a doc page, source file, or issue
If the domain map includes failure modes with a `skills` list naming
multiple skills, include those failure modes in every SKILL file listed.
**5. References** (only when needed)
```markdown
## References
- [Full option reference](references/options.md)
````
Create reference files when the skill would exceed 500 lines, when the
domain covers 3+ independent adapters/backends, or when a topic has >10
distinct API patterns.
### Checklist body (security, go-live, audit)
Use when the primary action is "check these things" not "learn patterns":
````markdown
# [Library Name] — [Security | Go-Live] Checklist
Run through each section before [deploying | releasing].
## [Category] Checks
### Check: [what to verify]
Expected:
```[lang]
// correct configuration
```
````
Fail condition: [what indicates this check failed]
Fix: [one-line remediation]
## Common Security Mistakes
[Wrong/correct pairs, same format as standard Common Mistakes]
## Pre-Deploy Summary
- [ ] [Verification 1]
- [ ] [Verification 2]
```
---
## Step 5 — Validate
Run every check before outputting. Fix any failures.
| Check | Rule |
|-------|------|
| Under 500 lines | Move excess to references/ |
| Real imports in every code block | Exact package name, correct adapter |
| No external concept explanations | No "TypeScript is...", no "React hooks are..." |
| No marketing prose | No "powerful", "elegant", "best-in-class" |
| 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 | Traceable to doc or source |
| `name` matches expected directory path | `db/core/live-queries` → `db/core/live-queries/SKILL.md` |
| `sources` filled for sub-skills | At least one Owner/repo:path |
| Framework skills have `requires` | Lists core dependency |
| Framework skills open with dependency note | First prose line references core |
| Description is a dense routing key | Not a human summary — agent-facing |
---
## Step 6 — Output
Before generating, ask the maintainer: "Would you like to review each skill
individually before I generate the next one, or should I generate all skills
and you review them together?" Respect their preference.
Output the complete SKILL.md file content. If reference files are needed,
output those as well with their relative paths.
If generating multiple skills in a batch (e.g. all skills for a library),
output in this order:
1. Core overview SKILL.md
2. Core sub-skills in domain order
3. Framework overview SKILL.md for each framework
4. Framework sub-skills
5. Composition skills
6. Security/checklist skills
7. Reference files
---
## Regeneration mode
When regenerating a stale skill (triggered by skill-staleness-check):
1. Read the existing SKILL.md and the source diff that triggered staleness
2. Scan GitHub issues and discussions opened since the skill was last
generated (use `library_version` or file timestamps as the baseline).
Look for new failure modes, resolved confusion, or changed patterns
related to this skill's topic. Apply the same search strategy from
Step 2b but scoped to the time window since last generation.
3. Determine which sections are affected by the source change AND by
any new issue/discussion findings
4. Update only affected sections — preserve all other content
5. If a breaking change occurred, add the old pattern as a new Common
Mistake entry (wrong/correct pair)
6. If issues/discussions reveal new failure modes not in the existing
skill, add them to Common Mistakes with issue URLs as sources
7. Bump `library_version` in frontmatter
8. Validate the complete file against Step 5 checks
Do not rewrite the entire skill for a minor source change. Surgical
updates preserve review effort and reduce diff noise.
---
## Constraints
| Rule | Detail |
|------|--------|
| Match the library's framework support | Generate framework skills only for adapters the library actually provides. If the library supports only React, only generate React examples. If it supports multiple frameworks, generate one skill per adapter. |
| All imports use real package names | `@tanstack/react-query`, not `react-query` |
| No placeholder code | No `// ...`, `[your value]`, or `...rest`. Idiomatic framework patterns like `{children}` or `{props.title}` in JSX are not placeholders — they are real code and are acceptable. |
| Agent-first writing | Only write what the agent cannot already know |
| Examples are minimal | No unnecessary boilerplate or wrapper components |
| Failure modes are high-value | Focus on plausible-but-broken, not obvious errors |
---
## 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`
---
## Meta-skill feedback
After generating all skills, run the `skill-feedback-collection` skill to
capture feedback about the scaffolding process (domain-discovery,
tree-generator, and generate-skill).
```
章节与文件索引
按说明文件中的顺序排列。
输入
第 1 步 — 确定技能类型
批次生成的子代理指南
第 2 步 — 从源中提取内容
提取什么
文件/命令 -> @tanstack/intent · domain_map.yaml · skill_spec.md · skills/ · package · packages/client/skills/core/SKILL.md · library-group/skill-name · tanstack-query/core
内容校验值 -> 7fb9ab7d8667
当前原文的自动摘译,尚未人工审校。
输入
您将收到:如果维护者使用自定义技能根目录,请将下面任何路径中的
skills/替换为他们选择的目录。 Monorepo:当技能树条目具有package字段时,将 SKILL.md 写入该包的技能目录(例如批次生成的子代理指南
生成多个技能时,为每个技能(或每个包组)生成一个单独的子代理。每个子代理都会收到domain_map.yaml、skill_tree.yaml 以及与其技能相关的源文档。这可以防止技能之间的上下文流失并允许并行生成。
提取什么
API 形状——函数签名、钩子参数、选项对象、返回类型。使用源中的实际 TypeScript 类型。设置模式 — 最小可行的初始化代码 主要模式 — 2-4 个最重要的使用模式 配置 — 重要的默认值、改变行为的选项