From f5281fbab4acc6e1e07b43b831395a4937357de7 Mon Sep 17 00:00:00 2001 From: LadyBluenotes Date: Mon, 9 Mar 2026 12:07:46 -0700 Subject: [PATCH 1/7] refactor: streamline overview documentation for clarity and focus on core functionalities --- docs/overview.md | 94 ++++++++++++++++-------------------------------- 1 file changed, 30 insertions(+), 64 deletions(-) diff --git a/docs/overview.md b/docs/overview.md index ecb0d91..711ec44 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -1,84 +1,50 @@ --- title: Overview +id: overview --- -`@tanstack/intent` is a CLI for library maintainers to generate, validate, and ship [Agent Skills](https://agentskills.io) alongside their npm packages. +`@tanstack/intent` is a CLI for shipping and consuming Agent Skills as package artifacts. -## The problem +Skills are published with npm packages, discovered from installed dependencies, and mapped into agent configuration in a reviewable way. -Your docs are good. Your types are solid. Your agent still gets it wrong. +## What Intent is for -Docs target humans who browse. Types check individual API calls but can't encode intent. Training data snapshots the ecosystem as it _was_, mixing versions with no way to tell which applies. Once a breaking change ships, models develop a permanent split-brain — training data contains _both_ versions forever with no way to disambiguate. +Intent supports two workflows: -The ecosystem already moves toward agent-readable knowledge — Cursor rules, CLAUDE.md files, skills directories. But delivery is stuck in copy-paste: hunt for a community-maintained rules file, paste it into your config, repeat for every tool. No versioning, no update path, no staleness signal. +- **Consumers (app teams):** discover skills in `node_modules` and map them into your agent config. +- **Maintainers (library teams):** scaffold skill content, validate it, and ship it in the same release + CI pipeline as code. -## Skills: versioned knowledge in npm +Across both workflows, the core capabilities are: -A skill is a short, versioned document that tells agents how to use a specific capability of your library — correct patterns, common mistakes, and when to apply them. Skills ship inside your npm package and travel with the tool via `npm update` — not the model's training cutoff, not community-maintained rules files, not prompt snippets in READMEs. Versioned knowledge the maintainer owns, updated when the package updates. +- **Discovery:** find intent-enabled packages and their skills. +- **Configuration:** generate instructions for an `intent-skills` mapping block. +- **Authoring + validation:** scaffold skills and enforce `SKILL.md` + packaging rules. +- **Staleness checks:** detect drift between skill metadata, source, and published versions. -Each skill declares its source docs. When those docs change, the CLI flags the skill for review. One source of truth, one derived artifact that stays in sync. +## Choose your path -The [Agent Skills spec](https://agentskills.io) is an open standard already adopted by VS Code, GitHub Copilot, OpenAI Codex, Cursor, Claude Code, Goose, Amp, and others. +If you are consuming libraries: -## For library consumers +- Start with [Installation](./getting-started/installation.md) +- Then run [Quick Start (Consumers)](./getting-started/quick-start-consumers.md) +- Use [Setting Up Agent Config](./guides/consumers/agent-config-setup.md) and [Listing & Inspecting Skills](./guides/consumers/listing-skills.md) for ongoing usage -Set up skill-to-task mappings in your project's agent config files (CLAUDE.md, .cursorrules, etc.): +If you are publishing libraries: -```bash -npx @tanstack/intent@latest install -``` +- Start with [Installation](./getting-started/installation.md) +- Then run [Quick Start (Maintainers)](./getting-started/quick-start-maintainers.md) +- Use [Scaffolding Skills](./guides/maintainers/scaffolding-skills.md), [Validation](./guides/maintainers/validation.md), and [CI Integration](./guides/maintainers/ci-integration.md) -No per-library setup. No hunting for rules files. Install the package, run `npx @tanstack/intent@latest install`, and the agent understands the tool. Update the package, and skills update too. +## Core commands -List available skills from installed packages: +- `npx @tanstack/intent@latest list` discovers installed skills (`--json` for script output) +- `npx @tanstack/intent@latest install` prints instructions for updating `intent-skills` mappings +- `npx @tanstack/intent@latest scaffold` and `npx @tanstack/intent@latest validate` drive skill authoring + checks +- `npx @tanstack/intent@latest stale` reports version/source drift -```bash -npx @tanstack/intent@latest list -``` +For complete command details, use the [CLI Reference](./cli/intent-list.md). -## For library maintainers +## Where to go deeper -Generate skills for your library by telling your AI coding agent to run: - -```bash -npx @tanstack/intent@latest scaffold -``` - -This walks the agent through domain discovery, skill tree generation, and skill creation — one step at a time with your review at each stage. - -Validate your skill files: - -```bash -npx @tanstack/intent@latest validate -``` - -Check for skills that have fallen behind their sources: - -```bash -npx @tanstack/intent@latest stale -``` - -Copy CI workflow templates into your repo so validation and staleness checks run on every push: - -```bash -npx @tanstack/intent@latest setup-github-actions -``` - -## Keeping skills current - -The real risk with any derived artifact is staleness. `npx @tanstack/intent@latest stale` flags skills whose source docs have changed, and CI templates catch drift before it ships. - -The feedback loop runs both directions. `npx @tanstack/intent@latest feedback` lets users submit structured reports when a skill produces wrong output — which skill, which version, what broke. That context flows back to the maintainer, and the fix ships to everyone on the next `npm update`. Every support interaction produces an artifact that prevents the same class of problem for all future users — not just the one who reported it. - -## CLI Commands - -| Command | Description | -| --- | --- | -| `npx @tanstack/intent@latest install` | Set up skill-to-task mappings in agent config files | -| `npx @tanstack/intent@latest list [--json]` | Discover intent-enabled packages | -| `npx @tanstack/intent@latest meta` | List meta-skills for library maintainers | -| `npx @tanstack/intent@latest scaffold` | Print the guided skill generation prompt | -| `npx @tanstack/intent@latest validate [dir]` | Validate SKILL.md files | -| `npx @tanstack/intent@latest setup-github-actions` | Copy CI templates into your repo | -| `npx @tanstack/intent@latest stale [--json]` | Check skills for version drift | -| `npx @tanstack/intent@latest feedback` | Submit skill feedback | +- **Concepts:** [What Are Skills](./concepts/what-are-skills.md), [Discovery](./concepts/discovery.md), [Staleness & Versioning](./concepts/staleness.md) +- **Specification:** [package.json Configuration](./specification/package-json.md), [SKILL.md Format](./specification/skill-format.md) From 40c6b7991d106d348c8954559efd1632b3fb64b3 Mon Sep 17 00:00:00 2001 From: LadyBluenotes Date: Mon, 9 Mar 2026 12:50:41 -0700 Subject: [PATCH 2/7] feat: add documentation for intent commands including install, list, meta, scaffold, setup, stale, and validate --- docs/cli/intent-install.md | 37 +++++++++++++++++ docs/cli/intent-list.md | 67 ++++++++++++++++++++++++++++++ docs/cli/intent-meta.md | 32 +++++++++++++++ docs/cli/intent-scaffold.md | 40 ++++++++++++++++++ docs/cli/intent-setup.md | 56 +++++++++++++++++++++++++ docs/cli/intent-stale.md | 81 +++++++++++++++++++++++++++++++++++++ docs/cli/intent-validate.md | 58 ++++++++++++++++++++++++++ 7 files changed, 371 insertions(+) create mode 100644 docs/cli/intent-install.md create mode 100644 docs/cli/intent-list.md create mode 100644 docs/cli/intent-meta.md create mode 100644 docs/cli/intent-scaffold.md create mode 100644 docs/cli/intent-setup.md create mode 100644 docs/cli/intent-stale.md create mode 100644 docs/cli/intent-validate.md diff --git a/docs/cli/intent-install.md b/docs/cli/intent-install.md new file mode 100644 index 0000000..e4503e8 --- /dev/null +++ b/docs/cli/intent-install.md @@ -0,0 +1,37 @@ +--- +title: intent install +id: intent-install +--- + +`intent install` prints instructions for setting up an `intent-skills` mapping block in your project guidance file. + +```bash +npx @tanstack/intent@latest install +``` + +The command prints text only. It does not edit files. + +## Output + +The printed instructions include this tagged block template: + +```yaml + +# Skill mappings — when working in these areas, load the linked skill file into context. +skills: + - task: "describe the task or code area here" + load: "node_modules/package-name/skills/skill-name/SKILL.md" + +``` + +They also ask you to: + +1. Check for an existing block first +2. Run `intent list` to discover installed skills +3. Add task-to-skill mappings +4. Preserve all content outside the tagged block + +## Related + +- [intent list](./intent-list) +- [Setting Up Agent Config](../guides/consumers/agent-config-setup) diff --git a/docs/cli/intent-list.md b/docs/cli/intent-list.md new file mode 100644 index 0000000..16da99e --- /dev/null +++ b/docs/cli/intent-list.md @@ -0,0 +1,67 @@ +--- +title: intent list +id: intent-list +--- + +`intent list` discovers skill-enabled packages and prints available skills. + +```bash +npx @tanstack/intent@latest list [--json] +``` + +## Options + +- `--json`: print JSON instead of text output + +## What you get + +- Scans installed dependencies for intent-enabled packages and skills +- Includes warnings from discovery +- If no packages are discovered, prints `No intent-enabled packages found.` +- Summary line with package count, skill count, and detected package manager +- Package table columns: `PACKAGE`, `VERSION`, `SKILLS`, `REQUIRES` +- Skill tree grouped by package +- Optional warnings section (`⚠ ...` per warning) + +`REQUIRES` uses `intent.requires` values joined by `, `; empty values render as `–`. + +## JSON output + +`--json` prints the `ScanResult` object: + +```json +{ + "packageManager": "npm | pnpm | yarn | bun | unknown", + "packages": [ + { + "name": "string", + "version": "string", + "intent": { + "version": 1, + "repo": "string", + "docs": "string", + "requires": ["string"] + }, + "skills": [ + { + "name": "string", + "path": "string", + "description": "string", + "type": "string (optional)", + "framework": "string (optional)" + } + ] + } + ], + "warnings": ["string"] +} +``` + +`packages` are ordered using `intent.requires` when possible. + +## Common errors + +- Scanner failures are printed as errors +- Unsupported environments: + - Yarn PnP without `node_modules` + - Deno projects without `node_modules` diff --git a/docs/cli/intent-meta.md b/docs/cli/intent-meta.md new file mode 100644 index 0000000..b21891b --- /dev/null +++ b/docs/cli/intent-meta.md @@ -0,0 +1,32 @@ +--- +title: intent meta +id: intent-meta +--- + +`intent meta` lists bundled meta-skills or prints one meta-skill file. + +```bash +npx @tanstack/intent@latest meta +npx @tanstack/intent@latest meta +``` + +## Arguments + +- `` is a meta-skill directory under `node_modules/@tanstack/intent/meta/` +- Rejected values: any name containing `..`, `/`, or `\\` + +## Output + +- Without ``: + - one line per meta-skill + - `name` + description from frontmatter + - description is normalized and truncated to 60 characters +- With ``: + - raw markdown from `meta//SKILL.md` + +## Common errors + +- Meta directory not found +- Invalid `` format +- Unknown `` (message suggests running `npx @tanstack/intent meta`) +- Read failure for target `SKILL.md` diff --git a/docs/cli/intent-scaffold.md b/docs/cli/intent-scaffold.md new file mode 100644 index 0000000..a7abe41 --- /dev/null +++ b/docs/cli/intent-scaffold.md @@ -0,0 +1,40 @@ +--- +title: intent scaffold +id: intent-scaffold +--- + +`intent scaffold` prints a phased scaffold prompt for generating skills. + +```bash +npx @tanstack/intent@latest scaffold +``` + +## Behavior + +- Prints prompt text to stdout +- Does not create files + +## Output + +The printed prompt defines three ordered phases: + +1. `domain-discovery` +2. `tree-generator` +3. `generate-skill` + +Each phase includes a stop gate before continuing. + +The prompt also includes a post-generation checklist: + +- Run `npx @tanstack/intent@latest validate` and fix issues +- Commit generated `skills/` and `skills/_artifacts/` +- Ensure `@tanstack/intent` is in `devDependencies` +- Run setup commands as needed: + - `npx @tanstack/intent@latest add-library-bin` + - `npx @tanstack/intent@latest edit-package-json` + - `npx @tanstack/intent@latest setup-github-actions` + +## Related + +- [intent validate](./intent-validate) +- [setup commands](./intent-setup) diff --git a/docs/cli/intent-setup.md b/docs/cli/intent-setup.md new file mode 100644 index 0000000..6feb558 --- /dev/null +++ b/docs/cli/intent-setup.md @@ -0,0 +1,56 @@ +--- +title: setup commands +id: intent-setup +--- + +Intent exposes setup as three separate commands. + +```bash +npx @tanstack/intent@latest add-library-bin +npx @tanstack/intent@latest edit-package-json +npx @tanstack/intent@latest setup-github-actions +``` + +## Commands + +- `add-library-bin`: create a package-local `intent` shim in `bin/` +- `edit-package-json`: add or normalize `package.json` entries needed to publish skills +- `setup-github-actions`: copy workflow templates to `.github/workflows` + +## What each command changes + +- `add-library-bin` + - Creates `bin/intent.js` when `package.json.type` is `module`, otherwise `bin/intent.mjs` + - If either shim already exists, command skips creation + - Shim imports `@tanstack/intent/intent-library` +- `edit-package-json` + - Requires a valid `package.json` in current directory + - Ensures `bin.intent` points to `./bin/intent.` + - Ensures `files` includes required publish entries + - Preserves existing indentation and existing `bin` entries + - Converts string shorthand `bin` to object when needed +- `setup-github-actions` + - Copies templates from `@tanstack/intent/meta/templates/workflows` to `.github/workflows` + - Applies variable substitution for `PACKAGE_NAME`, `REPO`, `DOCS_PATH`, `SRC_PATH` + - Skips files that already exist at destination + +## Required `files` entries + +`edit-package-json` enforces different `files` sets based on package location: + +- Monorepo package: `skills`, `bin` +- Non-monorepo package: `skills`, `bin`, `!skills/_artifacts` + +## Common errors + +- Missing or invalid `package.json` when running `edit-package-json` +- Missing template source when running `setup-github-actions` + +## Notes + +- `add-library-bin` and `setup-github-actions` skip existing files + +## Related + +- [intent validate](./intent-validate) +- [intent scaffold](./intent-scaffold) diff --git a/docs/cli/intent-stale.md b/docs/cli/intent-stale.md new file mode 100644 index 0000000..0946702 --- /dev/null +++ b/docs/cli/intent-stale.md @@ -0,0 +1,81 @@ +--- +title: intent stale +id: intent-stale +--- + +`intent stale` reports whether shipped skills may need review. + +```bash +npx @tanstack/intent@latest stale [--json] +``` + +## Options + +- `--json`: print JSON array of staleness reports + +## Behavior + +- Scans installed intent-enabled packages +- Computes one staleness report per package +- Prints text output by default or JSON with `--json` +- If no packages are found, prints `No intent-enabled packages found.` + +## JSON report schema + +`--json` outputs an array of reports: + +```json +[ + { + "library": "string", + "currentVersion": "string | null", + "skillVersion": "string | null", + "versionDrift": "major | minor | patch | null", + "skills": [ + { + "name": "string", + "reasons": ["string"], + "needsReview": true + } + ] + } +] +``` + +Report fields: + +- `library`: package name +- `currentVersion`: latest version from npm registry (or `null` if unavailable) +- `skillVersion`: `library_version` from skills (or `null`) +- `versionDrift`: `major | minor | patch | null` +- `skills`: array of per-skill checks + +Skill fields: + +- `name` +- `reasons`: one or more staleness reasons +- `needsReview`: boolean (`true` when reasons exist) + +Reason generation: + +- `version drift ( → )` +- `new source ()` when a declared source has no stored sync SHA + +## Text output + +- Report header format: ` ( → ) [ drift]` +- When no skill reasons exist: `All skills up-to-date` +- Otherwise: one warning line per stale skill (`⚠ : , , ...`) + +## Common errors + +- Package scan failure: prints a scanner error +- Registry fetch failures do not crash command; `currentVersion` may be `null` + +## Notes + +- Source staleness checking is conservative: it flags missing source SHAs in sync-state, not remote content differences. + +## Related + +- [intent list](./intent-list) diff --git a/docs/cli/intent-validate.md b/docs/cli/intent-validate.md new file mode 100644 index 0000000..5b27c5c --- /dev/null +++ b/docs/cli/intent-validate.md @@ -0,0 +1,58 @@ +--- +title: intent validate +id: intent-validate +--- + +`intent validate` checks `SKILL.md` files and artifacts for structural problems. + +```bash +npx @tanstack/intent@latest validate [] +``` + +## Arguments + +- ``: directory containing skills; default is `skills` +- Relative paths are resolved from the current working directory + +## Validation checks + +For each discovered `SKILL.md`: + +- Frontmatter delimiter and structure are valid +- YAML frontmatter parses successfully +- Required fields exist: `name`, `description` +- `name` matches skill directory path under the target root +- `description` length is at most 1024 characters +- `type: framework` requires `requires` to be an array +- Total file length is at most 500 lines + +If `/_artifacts` exists, it also validates artifacts: + +- Required files: `domain_map.yaml`, `skill_spec.md`, `skill_tree.yaml` +- Required files must be non-empty +- `.yaml` artifacts must parse successfully + +## Packaging warnings + +Packaging warnings are always computed from `package.json` in the current working directory: + +- `@tanstack/intent` missing from `devDependencies` +- Missing `bin.intent` entry +- Missing shim (`bin/intent.js` or `bin/intent.mjs`) +- Missing `files` entries when `files` array exists: + - `skills` + - `bin` + - `!skills/_artifacts` + +Warnings are informational; they are printed on both pass and fail paths. + +## Common errors + +- Missing target directory: `Skills directory not found: ` +- No skill files discovered: `No SKILL.md files found` +- Validation failures: aggregated file-specific errors and count + +## Related + +- [intent scaffold](./intent-scaffold) +- [setup commands](./intent-setup) From 27488a07e01966d6669936cb093a909bf7a5b719 Mon Sep 17 00:00:00 2001 From: LadyBluenotes Date: Mon, 9 Mar 2026 14:43:58 -0700 Subject: [PATCH 3/7] feat: add quick start guides for consumers and maintainers --- docs/config.json | 129 +++++++++++ docs/getting-started/quick-start-consumers.md | 89 ++++++++ .../quick-start-maintainers.md | 213 ++++++++++++++++++ docs/overview.md | 72 +++--- 4 files changed, 475 insertions(+), 28 deletions(-) create mode 100644 docs/getting-started/quick-start-consumers.md create mode 100644 docs/getting-started/quick-start-maintainers.md diff --git a/docs/config.json b/docs/config.json index 552d60c..29575b3 100644 --- a/docs/config.json +++ b/docs/config.json @@ -12,6 +12,135 @@ { "label": "Overview", "to": "overview" + }, + { + "label": "Quick Start (Consumers)", + "to": "getting-started/quick-start-consumers" + }, + { + "label": "Quick Start (Maintainers)", + "to": "getting-started/quick-start-maintainers" + } + ] + }, + { + "label": "Concepts", + "children": [ + { + "label": "What Are Skills", + "to": "concepts/what-are-skills" + }, + { + "label": "Discovery", + "to": "concepts/discovery" + }, + { + "label": "Staleness & Versioning", + "to": "concepts/staleness" + }, + { + "label": "Feedback Loop", + "to": "concepts/feedback-loop" + }, + { + "label": "Security & Trust", + "to": "concepts/security" + } + ] + }, + { + "label": "Guides (Consumers)", + "children": [ + { + "label": "Setting Up Agent Config", + "to": "guides/consumers/agent-config-setup" + }, + { + "label": "Listing & Inspecting Skills", + "to": "guides/consumers/listing-skills" + }, + { + "label": "Submitting Feedback", + "to": "guides/consumers/submitting-feedback" + } + ] + }, + { + "label": "Guides (Maintainers)", + "children": [ + { + "label": "Scaffolding Skills", + "to": "guides/maintainers/scaffolding-skills" + }, + { + "label": "Writing Skills", + "to": "guides/maintainers/writing-skills" + }, + { + "label": "Meta-Skills", + "to": "guides/maintainers/meta-skills" + }, + { + "label": "Validation", + "to": "guides/maintainers/validation" + }, + { + "label": "CI Integration", + "to": "guides/maintainers/ci-integration" + }, + { + "label": "Responding to Feedback", + "to": "guides/maintainers/responding-to-feedback" + } + ] + }, + { + "label": "CLI Reference", + "children": [ + { + "label": "intent install", + "to": "cli/intent-install" + }, + { + "label": "intent list", + "to": "cli/intent-list" + }, + { + "label": "intent meta", + "to": "cli/intent-meta" + }, + { + "label": "intent scaffold", + "to": "cli/intent-scaffold" + }, + { + "label": "intent validate", + "to": "cli/intent-validate" + }, + { + "label": "intent setup-github-actions", + "to": "cli/intent-setup" + }, + { + "label": "intent stale", + "to": "cli/intent-stale" + } + ] + }, + { + "label": "Specification", + "children": [ + { + "label": "package.json Configuration", + "to": "specification/package-json" + }, + { + "label": "SKILL.md Format", + "to": "specification/skill-format" + }, + { + "label": "Agent Skills Compatibility", + "to": "specification/agent-skills-compatibility" } ] } diff --git a/docs/getting-started/quick-start-consumers.md b/docs/getting-started/quick-start-consumers.md new file mode 100644 index 0000000..d97de41 --- /dev/null +++ b/docs/getting-started/quick-start-consumers.md @@ -0,0 +1,89 @@ +--- +title: Quick Start for Consumers +id: quick-start-consumers +--- + +Get started using Intent to set up skill-to-task mappings for your agent. + +## 1. Run install + +The install command guides your agent through the setup process: + +```bash +npx @tanstack/intent@latest install +``` + +This prints a skill that instructs your AI agent to: +1. Check for existing `intent-skills` mappings in your config files (CLAUDE.md, .cursorrules, etc.) +2. Run `intent list` to discover available skills from installed packages +3. Scan your repository structure to understand your project +4. Propose relevant skill-to-task mappings based on your codebase patterns +5. Write or update an `intent-skills` block in your agent config + +Your agent will create mappings like: + +```markdown + +# Skill mappings — when working in these areas, load the linked skill file into context. +skills: + - task: "implementing data fetching with TanStack Query" + load: "node_modules/@tanstack/react-query/skills/core/SKILL.md" + - task: "setting up routing with TanStack Router" + load: "node_modules/@tanstack/react-router/skills/core/SKILL.md" + +``` + +## 2. Use skills in your workflow + +When your agent works on a task that matches a mapping, it automatically loads the corresponding SKILL.md into context to guide implementation. + +## 3. Keep skills up-to-date + +Skills version with library releases. When you update a library: + +```bash +npm update @tanstack/react-query +``` + +The new version brings updated skills automatically — you don't need to do anything. The skills are shipped with the library, so you always get the version that matches your installed code. + +If you need to see what skills have changed, run: + +```bash +npx @tanstack/intent@latest list +``` + +Or use `--json` for machine-readable output: + +```bash +npx @tanstack/intent@latest list --json +``` + +You can also check if any skills reference outdated source documentation: + +```bash +npx @tanstack/intent@latest stale +``` + +## 4. Submit feedback (optional) + +After using a skill, you can submit feedback to help maintainers improve it: + +```bash +npx @tanstack/intent@latest meta feedback-collection +``` + +This prints a skill that guides your agent to collect structured feedback about gaps, errors, and improvements. + +--- + +## Next steps + +- [Listing Skills](../guides/consumers/listing-skills.md) — interpret `intent list` output in detail +- [Submitting Feedback](../guides/consumers/submitting-feedback.md) — help maintainers improve skills +- [What Are Skills](../concepts/what-are-skills.md) — understand skill anatomy and consumption + + + + + diff --git a/docs/getting-started/quick-start-maintainers.md b/docs/getting-started/quick-start-maintainers.md new file mode 100644 index 0000000..4e4daa3 --- /dev/null +++ b/docs/getting-started/quick-start-maintainers.md @@ -0,0 +1,213 @@ +--- +title: Quick Start for Maintainers +id: quick-start-maintainers +--- + +Get started scaffolding, validating, and shipping skills for your library. + +## Install + + +react: @tanstack/intent +solid: @tanstack/intent +vue: @tanstack/intent +svelte: @tanstack/intent +angular: @tanstack/intent +lit: @tanstack/intent + + +Or run commands without installing: + +```bash +npx @tanstack/intent@latest scaffold +``` + +> [!WARNING] +> When using `npx` or `bunx`, always include `@latest`. Intent-enabled libraries ship a local `intent` binary shim, and without `@latest`, your package manager may resolve to that shim instead of the real CLI. + +--- + +## Initial Setup (With Agent) + +### 1. Scaffold skills + +Start the scaffolding process **with your AI agent**: + +```bash +npx @tanstack/intent@latest scaffold +``` + +This prints a comprehensive prompt that walks you and your agent through three phases: + +**Phase 1: Domain Discovery** +- Scans your documentation, source code, and GitHub issues +- Conducts an interactive interview to surface implicit knowledge +- Produces `domain_map.yaml` and `skill_spec.md` artifacts + +**Phase 2: Tree Generation** +- Designs a skill taxonomy based on the domain map +- Creates a hierarchical skill structure +- Produces `skill_tree.yaml` artifact + +**Phase 3: Skill Generation** +- Writes complete SKILL.md files for each skill +- Includes patterns, failure modes, and API references +- Validates against the Intent specification + +> [!NOTE] +> This is a context-heavy process that involves domain discovery, GitHub issues analysis, and interactive maintainer interviews. The agent will scan your documentation, recent issues and discussions, and ask targeted questions to surface implicit knowledge and common failure modes. The more information you provide about your library's patterns, pitfalls, and real-world usage problems, the better the generated skills will be. Expect multiple rounds of refinement and regular context compaction before completion. + +### 2. Validate skills + +After scaffolding, validate that all SKILL.md files are well-formed: + +```bash +npx @tanstack/intent@latest validate +``` + +This checks: +- Valid YAML frontmatter in every SKILL.md +- Required fields (`name`, `description`) are present +- Skill names match their directory paths +- Description length <= 1024 characters +- Line count limits (500 lines max per skill) +- Framework skills have a `requires` array +- Artifact files exist and are non-empty + +If any artifacts are present (domain_map.yaml, skill_spec.md, skill_tree.yaml), they must parse as valid YAML. + +### 3. Commit skills and artifacts + +Commit both generated skills and the artifacts used to create them: + +``` +skills/ + core/SKILL.md + react/SKILL.md + _artifacts/ + domain_map.yaml + skill_spec.md + skill_tree.yaml +``` + +Artifacts enforce a consistent skill structure across versions, making it easier to audit, refresh, or extend the skill set without starting from scratch. + +--- + +## Publish Configuration + +### 4. Configure your package for publishing + +Run these commands to prepare your package for skill publishing: + +```bash +# Generate the bin shim that consumers use for discovery +npx @tanstack/intent@latest add-library-bin + +# Update package.json with required fields +npx @tanstack/intent@latest edit-package-json + +# Copy CI workflow templates (validate + stale checks) +npx @tanstack/intent@latest setup-github-actions +``` + +**What these do:** + +- `add-library-bin` creates `bin/intent.js` or `bin/intent.mjs` — a shim that lets consumers run `npx your-package intent` to access Intent CLI features +- `edit-package-json` adds: + - `intent` field in package.json with version, repo, and docs metadata + - `bin.intent` entry pointing to the shim + - `files` array entries for `skills/` and `bin/` + - For single packages: also adds `!skills/_artifacts` to exclude artifacts from npm + - For monorepos: skips the artifacts exclusion (artifacts live at repo root) +- `setup-github-actions` copies workflow templates to `.github/workflows/` for automated validation and staleness checking + +### 5. Ship skills with your package + +Skills ship inside your npm package. When you publish: + +```bash +npm publish +``` + +Consumers who install your library automatically get the skills. They discover them with `intent list` and map them with `intent install`. + +**Version alignment:** +- Skills version with your library releases +- Agents always load the skill matching the installed library version +- No drift between code and guidance + +--- + +## Ongoing Maintenance (Manual or Agent-Assisted) + +### 6. Set up CI workflows + +After running `setup-github-actions`, you'll have three workflows in `.github/workflows/`: + +**validate-skills.yml** (runs on PRs touching `skills/`) +- Validates SKILL.md frontmatter and structure +- Ensures files stay under 500 lines +- Runs automatically on every pull request that modifies skills + +**check-skills.yml** (runs on release or manual trigger) +- Automatically detects stale skills after you publish a new release +- Opens a review PR with an agent-friendly prompt +- Requires you to copy the prompt into Claude Code, Cursor, or your agent to update skills + +**notify-intent.yml** (runs on docs/source changes to main) +- Sends a webhook to TanStack/intent when your docs or source change +- Enables cross-library skill staleness tracking +- Requires a fine-grained GitHub token (`INTENT_NOTIFY_TOKEN`) secret + +### 7. Update stale skills + +When you publish a new release, `check-skills.yml` automatically opens a PR flagging skills that need review. + +Manually check which skills need updates with: + +```bash +npx @tanstack/intent@latest stale +``` + +This detects: +- **Version drift** — skill targets an older library version than currently installed +- **New sources** — sources declared in frontmatter that weren't tracked before + +**To update stale skills:** +1. Review the PR opened by `check-skills.yml` +2. Copy the agent prompt from the PR description +3. Paste it into Claude Code, Cursor, or your coding agent +4. The agent reads the stale skills and updates them based on library changes +5. Run `npx @tanstack/intent@latest validate` locally to verify +6. Commit and merge the PR + +> [!NOTE] +> Skills are updated through agent assistance, not full automation. The workflow detects what's stale and provides the prompt — your agent handles the actual updates. + +Use `--json` output for CI integration or scripting. + +### 8. Maintain and iterate + +As your library evolves: + +1. **When APIs change:** Update relevant SKILL.md files with new patterns +2. **When docs change:** Run `intent stale` to identify affected skills +3. **When issues are filed:** Check if the failure mode should be added to "Common Mistakes" +4. **After major releases:** Consider re-running domain discovery to catch new patterns + +> [!TIP] +> Create GitHub issue labels matching your skill names (`skill:core`, `skill:react`). When users file issues, tag them with the relevant skill label to track which areas need the most improvement. + +--- + +## Next steps + +- [Scaffolding Skills](../guides/maintainers/scaffolding-skills.md) — detailed workflow and phases +- [Validation](../guides/maintainers/validation.md) — complete validation rules +- [CI Integration](../guides/maintainers/ci-integration.md) — automated checks and workflows +- [Writing Skills](../guides/maintainers/writing-skills.md) — SKILL.md format and conventions + + + + diff --git a/docs/overview.md b/docs/overview.md index 711ec44..9a2a08f 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -5,46 +5,62 @@ id: overview `@tanstack/intent` is a CLI for shipping and consuming Agent Skills as package artifacts. -Skills are published with npm packages, discovered from installed dependencies, and mapped into agent configuration in a reviewable way. +Skills are markdown documents that teach AI coding agents how to use your library correctly. Intent versions them with your releases, ships them inside npm packages, discovers them from `node_modules`, and helps agents load them automatically when working on matching tasks. -## What Intent is for +## What Intent does -Intent supports two workflows: +Intent provides tooling for two workflows: -- **Consumers (app teams):** discover skills in `node_modules` and map them into your agent config. -- **Maintainers (library teams):** scaffold skill content, validate it, and ship it in the same release + CI pipeline as code. +**For consumers:** +- Discover skills from installed dependencies +- Generate task-to-skill mappings for your agent config +- Keep skills synchronized with library versions -Across both workflows, the core capabilities are: +**For maintainers (library teams):** +- Scaffold skills through AI-assisted domain discovery +- Validate SKILL.md format and packaging +- Ship skills in the same release pipeline as code +- Track staleness when source docs change -- **Discovery:** find intent-enabled packages and their skills. -- **Configuration:** generate instructions for an `intent-skills` mapping block. -- **Authoring + validation:** scaffold skills and enforce `SKILL.md` + packaging rules. -- **Staleness checks:** detect drift between skill metadata, source, and published versions. +## How it works -## Choose your path +### Discovery and installation -If you are consuming libraries: +```bash +npx @tanstack/intent@latest list +``` -- Start with [Installation](./getting-started/installation.md) -- Then run [Quick Start (Consumers)](./getting-started/quick-start-consumers.md) -- Use [Setting Up Agent Config](./guides/consumers/agent-config-setup.md) and [Listing & Inspecting Skills](./guides/consumers/listing-skills.md) for ongoing usage +Scans `node_modules` for intent-enabled packages and shows available skills with paths and descriptions. -If you are publishing libraries: +```bash +npx @tanstack/intent@latest install +``` -- Start with [Installation](./getting-started/installation.md) -- Then run [Quick Start (Maintainers)](./getting-started/quick-start-maintainers.md) -- Use [Scaffolding Skills](./guides/maintainers/scaffolding-skills.md), [Validation](./guides/maintainers/validation.md), and [CI Integration](./guides/maintainers/ci-integration.md) +Prints instructions for your agent to create `intent-skills` mappings in your config files (CLAUDE.md, .cursorrules, etc.). -## Core commands +### Scaffolding and validation -- `npx @tanstack/intent@latest list` discovers installed skills (`--json` for script output) -- `npx @tanstack/intent@latest install` prints instructions for updating `intent-skills` mappings -- `npx @tanstack/intent@latest scaffold` and `npx @tanstack/intent@latest validate` drive skill authoring + checks -- `npx @tanstack/intent@latest stale` reports version/source drift +```bash +npx @tanstack/intent@latest scaffold +``` -For complete command details, use the [CLI Reference](./cli/intent-list.md). +Guides your agent through domain discovery, tree generation, and skill authoring with interactive maintainer interviews. -## Where to go deeper +```bash +npx @tanstack/intent@latest validate +``` -- **Concepts:** [What Are Skills](./concepts/what-are-skills.md), [Discovery](./concepts/discovery.md), [Staleness & Versioning](./concepts/staleness.md) -- **Specification:** [package.json Configuration](./specification/package-json.md), [SKILL.md Format](./specification/skill-format.md) +Enforces SKILL.md format rules and packaging requirements before publish. + +### Staleness tracking + +```bash +npx @tanstack/intent@latest stale +``` + +Detects when skills reference outdated source documentation or library versions. + +## Next steps + +- **[What Are Skills](./concepts/what-are-skills.md)** — understand skill anatomy and why they matter +- **[CLI Reference](./cli/intent-list.md)** — explore all commands From 4efc45ef0c8c7bf1ac19a93bf45162730c17ad3d Mon Sep 17 00:00:00 2001 From: LadyBluenotes Date: Mon, 9 Mar 2026 15:24:00 -0700 Subject: [PATCH 4/7] refactor: remove files not added --- docs/config.json | 88 ------------------------------------------------ 1 file changed, 88 deletions(-) diff --git a/docs/config.json b/docs/config.json index 29575b3..92a717d 100644 --- a/docs/config.json +++ b/docs/config.json @@ -23,77 +23,6 @@ } ] }, - { - "label": "Concepts", - "children": [ - { - "label": "What Are Skills", - "to": "concepts/what-are-skills" - }, - { - "label": "Discovery", - "to": "concepts/discovery" - }, - { - "label": "Staleness & Versioning", - "to": "concepts/staleness" - }, - { - "label": "Feedback Loop", - "to": "concepts/feedback-loop" - }, - { - "label": "Security & Trust", - "to": "concepts/security" - } - ] - }, - { - "label": "Guides (Consumers)", - "children": [ - { - "label": "Setting Up Agent Config", - "to": "guides/consumers/agent-config-setup" - }, - { - "label": "Listing & Inspecting Skills", - "to": "guides/consumers/listing-skills" - }, - { - "label": "Submitting Feedback", - "to": "guides/consumers/submitting-feedback" - } - ] - }, - { - "label": "Guides (Maintainers)", - "children": [ - { - "label": "Scaffolding Skills", - "to": "guides/maintainers/scaffolding-skills" - }, - { - "label": "Writing Skills", - "to": "guides/maintainers/writing-skills" - }, - { - "label": "Meta-Skills", - "to": "guides/maintainers/meta-skills" - }, - { - "label": "Validation", - "to": "guides/maintainers/validation" - }, - { - "label": "CI Integration", - "to": "guides/maintainers/ci-integration" - }, - { - "label": "Responding to Feedback", - "to": "guides/maintainers/responding-to-feedback" - } - ] - }, { "label": "CLI Reference", "children": [ @@ -126,23 +55,6 @@ "to": "cli/intent-stale" } ] - }, - { - "label": "Specification", - "children": [ - { - "label": "package.json Configuration", - "to": "specification/package-json" - }, - { - "label": "SKILL.md Format", - "to": "specification/skill-format" - }, - { - "label": "Agent Skills Compatibility", - "to": "specification/agent-skills-compatibility" - } - ] } ] } From 1c9c21f5f618f8d6b7d40f1588b90777270040d0 Mon Sep 17 00:00:00 2001 From: LadyBluenotes Date: Tue, 10 Mar 2026 10:20:02 -0700 Subject: [PATCH 5/7] refactor: remove next steps sections from quick start guides for consumers and maintainers --- docs/getting-started/quick-start-consumers.md | 9 --------- docs/getting-started/quick-start-maintainers.md | 13 ------------- docs/overview.md | 5 ----- 3 files changed, 27 deletions(-) diff --git a/docs/getting-started/quick-start-consumers.md b/docs/getting-started/quick-start-consumers.md index d97de41..8cafd67 100644 --- a/docs/getting-started/quick-start-consumers.md +++ b/docs/getting-started/quick-start-consumers.md @@ -75,15 +75,6 @@ npx @tanstack/intent@latest meta feedback-collection This prints a skill that guides your agent to collect structured feedback about gaps, errors, and improvements. ---- - -## Next steps - -- [Listing Skills](../guides/consumers/listing-skills.md) — interpret `intent list` output in detail -- [Submitting Feedback](../guides/consumers/submitting-feedback.md) — help maintainers improve skills -- [What Are Skills](../concepts/what-are-skills.md) — understand skill anatomy and consumption - - diff --git a/docs/getting-started/quick-start-maintainers.md b/docs/getting-started/quick-start-maintainers.md index 4e4daa3..b59e6fd 100644 --- a/docs/getting-started/quick-start-maintainers.md +++ b/docs/getting-started/quick-start-maintainers.md @@ -198,16 +198,3 @@ As your library evolves: > [!TIP] > Create GitHub issue labels matching your skill names (`skill:core`, `skill:react`). When users file issues, tag them with the relevant skill label to track which areas need the most improvement. - ---- - -## Next steps - -- [Scaffolding Skills](../guides/maintainers/scaffolding-skills.md) — detailed workflow and phases -- [Validation](../guides/maintainers/validation.md) — complete validation rules -- [CI Integration](../guides/maintainers/ci-integration.md) — automated checks and workflows -- [Writing Skills](../guides/maintainers/writing-skills.md) — SKILL.md format and conventions - - - - diff --git a/docs/overview.md b/docs/overview.md index 9a2a08f..33cce56 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -59,8 +59,3 @@ npx @tanstack/intent@latest stale ``` Detects when skills reference outdated source documentation or library versions. - -## Next steps - -- **[What Are Skills](./concepts/what-are-skills.md)** — understand skill anatomy and why they matter -- **[CLI Reference](./cli/intent-list.md)** — explore all commands From 3d7fdc777887c06c31f58851cbe0ba7b282fbfa3 Mon Sep 17 00:00:00 2001 From: Sarah Gerrard <98355961+LadyBluenotes@users.noreply.github.com> Date: Wed, 11 Mar 2026 11:34:38 -0700 Subject: [PATCH 6/7] fix my branch --- .changeset/add-keywords-to-package-json.md | 10 +- docs/cli/intent-install.md | 74 +- docs/cli/intent-list.md | 134 +- docs/cli/intent-meta.md | 64 +- docs/cli/intent-scaffold.md | 80 +- docs/cli/intent-setup.md | 112 +- docs/cli/intent-stale.md | 162 +- docs/cli/intent-validate.md | 116 +- docs/config.json | 120 +- docs/getting-started/quick-start-consumers.md | 160 +- .../quick-start-maintainers.md | 400 ++-- docs/overview.md | 122 +- packages/intent/CHANGELOG.md | 128 +- .../intent/meta/domain-discovery/SKILL.md | 1836 ++++++++--------- .../intent/meta/feedback-collection/SKILL.md | 468 ++--- packages/intent/meta/generate-skill/SKILL.md | 906 ++++---- .../templates/workflows/notify-intent.yml | 104 +- packages/intent/package.json | 80 +- packages/intent/src/setup.ts | 742 +++---- 19 files changed, 2909 insertions(+), 2909 deletions(-) diff --git a/.changeset/add-keywords-to-package-json.md b/.changeset/add-keywords-to-package-json.md index 9f39097..039b7ef 100644 --- a/.changeset/add-keywords-to-package-json.md +++ b/.changeset/add-keywords-to-package-json.md @@ -1,5 +1,5 @@ ---- -'@tanstack/intent': patch ---- - -Add `tanstack-intent` keyword to package.json during setup +--- +'@tanstack/intent': patch +--- + +Add `tanstack-intent` keyword to package.json during setup diff --git a/docs/cli/intent-install.md b/docs/cli/intent-install.md index e4503e8..ff6d002 100644 --- a/docs/cli/intent-install.md +++ b/docs/cli/intent-install.md @@ -1,37 +1,37 @@ ---- -title: intent install -id: intent-install ---- - -`intent install` prints instructions for setting up an `intent-skills` mapping block in your project guidance file. - -```bash -npx @tanstack/intent@latest install -``` - -The command prints text only. It does not edit files. - -## Output - -The printed instructions include this tagged block template: - -```yaml - -# Skill mappings — when working in these areas, load the linked skill file into context. -skills: - - task: "describe the task or code area here" - load: "node_modules/package-name/skills/skill-name/SKILL.md" - -``` - -They also ask you to: - -1. Check for an existing block first -2. Run `intent list` to discover installed skills -3. Add task-to-skill mappings -4. Preserve all content outside the tagged block - -## Related - -- [intent list](./intent-list) -- [Setting Up Agent Config](../guides/consumers/agent-config-setup) +--- +title: intent install +id: intent-install +--- + +`intent install` prints instructions for setting up an `intent-skills` mapping block in your project guidance file. + +```bash +npx @tanstack/intent@latest install +``` + +The command prints text only. It does not edit files. + +## Output + +The printed instructions include this tagged block template: + +```yaml + +# Skill mappings — when working in these areas, load the linked skill file into context. +skills: + - task: "describe the task or code area here" + load: "node_modules/package-name/skills/skill-name/SKILL.md" + +``` + +They also ask you to: + +1. Check for an existing block first +2. Run `intent list` to discover installed skills +3. Add task-to-skill mappings +4. Preserve all content outside the tagged block + +## Related + +- [intent list](./intent-list) +- [Setting Up Agent Config](../guides/consumers/agent-config-setup) diff --git a/docs/cli/intent-list.md b/docs/cli/intent-list.md index 16da99e..3aa6606 100644 --- a/docs/cli/intent-list.md +++ b/docs/cli/intent-list.md @@ -1,67 +1,67 @@ ---- -title: intent list -id: intent-list ---- - -`intent list` discovers skill-enabled packages and prints available skills. - -```bash -npx @tanstack/intent@latest list [--json] -``` - -## Options - -- `--json`: print JSON instead of text output - -## What you get - -- Scans installed dependencies for intent-enabled packages and skills -- Includes warnings from discovery -- If no packages are discovered, prints `No intent-enabled packages found.` -- Summary line with package count, skill count, and detected package manager -- Package table columns: `PACKAGE`, `VERSION`, `SKILLS`, `REQUIRES` -- Skill tree grouped by package -- Optional warnings section (`⚠ ...` per warning) - -`REQUIRES` uses `intent.requires` values joined by `, `; empty values render as `–`. - -## JSON output - -`--json` prints the `ScanResult` object: - -```json -{ - "packageManager": "npm | pnpm | yarn | bun | unknown", - "packages": [ - { - "name": "string", - "version": "string", - "intent": { - "version": 1, - "repo": "string", - "docs": "string", - "requires": ["string"] - }, - "skills": [ - { - "name": "string", - "path": "string", - "description": "string", - "type": "string (optional)", - "framework": "string (optional)" - } - ] - } - ], - "warnings": ["string"] -} -``` - -`packages` are ordered using `intent.requires` when possible. - -## Common errors - -- Scanner failures are printed as errors -- Unsupported environments: - - Yarn PnP without `node_modules` - - Deno projects without `node_modules` +--- +title: intent list +id: intent-list +--- + +`intent list` discovers skill-enabled packages and prints available skills. + +```bash +npx @tanstack/intent@latest list [--json] +``` + +## Options + +- `--json`: print JSON instead of text output + +## What you get + +- Scans installed dependencies for intent-enabled packages and skills +- Includes warnings from discovery +- If no packages are discovered, prints `No intent-enabled packages found.` +- Summary line with package count, skill count, and detected package manager +- Package table columns: `PACKAGE`, `VERSION`, `SKILLS`, `REQUIRES` +- Skill tree grouped by package +- Optional warnings section (`⚠ ...` per warning) + +`REQUIRES` uses `intent.requires` values joined by `, `; empty values render as `–`. + +## JSON output + +`--json` prints the `ScanResult` object: + +```json +{ + "packageManager": "npm | pnpm | yarn | bun | unknown", + "packages": [ + { + "name": "string", + "version": "string", + "intent": { + "version": 1, + "repo": "string", + "docs": "string", + "requires": ["string"] + }, + "skills": [ + { + "name": "string", + "path": "string", + "description": "string", + "type": "string (optional)", + "framework": "string (optional)" + } + ] + } + ], + "warnings": ["string"] +} +``` + +`packages` are ordered using `intent.requires` when possible. + +## Common errors + +- Scanner failures are printed as errors +- Unsupported environments: + - Yarn PnP without `node_modules` + - Deno projects without `node_modules` diff --git a/docs/cli/intent-meta.md b/docs/cli/intent-meta.md index b21891b..e700f23 100644 --- a/docs/cli/intent-meta.md +++ b/docs/cli/intent-meta.md @@ -1,32 +1,32 @@ ---- -title: intent meta -id: intent-meta ---- - -`intent meta` lists bundled meta-skills or prints one meta-skill file. - -```bash -npx @tanstack/intent@latest meta -npx @tanstack/intent@latest meta -``` - -## Arguments - -- `` is a meta-skill directory under `node_modules/@tanstack/intent/meta/` -- Rejected values: any name containing `..`, `/`, or `\\` - -## Output - -- Without ``: - - one line per meta-skill - - `name` + description from frontmatter - - description is normalized and truncated to 60 characters -- With ``: - - raw markdown from `meta//SKILL.md` - -## Common errors - -- Meta directory not found -- Invalid `` format -- Unknown `` (message suggests running `npx @tanstack/intent meta`) -- Read failure for target `SKILL.md` +--- +title: intent meta +id: intent-meta +--- + +`intent meta` lists bundled meta-skills or prints one meta-skill file. + +```bash +npx @tanstack/intent@latest meta +npx @tanstack/intent@latest meta +``` + +## Arguments + +- `` is a meta-skill directory under `node_modules/@tanstack/intent/meta/` +- Rejected values: any name containing `..`, `/`, or `\\` + +## Output + +- Without ``: + - one line per meta-skill + - `name` + description from frontmatter + - description is normalized and truncated to 60 characters +- With ``: + - raw markdown from `meta//SKILL.md` + +## Common errors + +- Meta directory not found +- Invalid `` format +- Unknown `` (message suggests running `npx @tanstack/intent meta`) +- Read failure for target `SKILL.md` diff --git a/docs/cli/intent-scaffold.md b/docs/cli/intent-scaffold.md index a7abe41..eceb0e7 100644 --- a/docs/cli/intent-scaffold.md +++ b/docs/cli/intent-scaffold.md @@ -1,40 +1,40 @@ ---- -title: intent scaffold -id: intent-scaffold ---- - -`intent scaffold` prints a phased scaffold prompt for generating skills. - -```bash -npx @tanstack/intent@latest scaffold -``` - -## Behavior - -- Prints prompt text to stdout -- Does not create files - -## Output - -The printed prompt defines three ordered phases: - -1. `domain-discovery` -2. `tree-generator` -3. `generate-skill` - -Each phase includes a stop gate before continuing. - -The prompt also includes a post-generation checklist: - -- Run `npx @tanstack/intent@latest validate` and fix issues -- Commit generated `skills/` and `skills/_artifacts/` -- Ensure `@tanstack/intent` is in `devDependencies` -- Run setup commands as needed: - - `npx @tanstack/intent@latest add-library-bin` - - `npx @tanstack/intent@latest edit-package-json` - - `npx @tanstack/intent@latest setup-github-actions` - -## Related - -- [intent validate](./intent-validate) -- [setup commands](./intent-setup) +--- +title: intent scaffold +id: intent-scaffold +--- + +`intent scaffold` prints a phased scaffold prompt for generating skills. + +```bash +npx @tanstack/intent@latest scaffold +``` + +## Behavior + +- Prints prompt text to stdout +- Does not create files + +## Output + +The printed prompt defines three ordered phases: + +1. `domain-discovery` +2. `tree-generator` +3. `generate-skill` + +Each phase includes a stop gate before continuing. + +The prompt also includes a post-generation checklist: + +- Run `npx @tanstack/intent@latest validate` and fix issues +- Commit generated `skills/` and `skills/_artifacts/` +- Ensure `@tanstack/intent` is in `devDependencies` +- Run setup commands as needed: + - `npx @tanstack/intent@latest add-library-bin` + - `npx @tanstack/intent@latest edit-package-json` + - `npx @tanstack/intent@latest setup-github-actions` + +## Related + +- [intent validate](./intent-validate) +- [setup commands](./intent-setup) diff --git a/docs/cli/intent-setup.md b/docs/cli/intent-setup.md index 6feb558..953ecfc 100644 --- a/docs/cli/intent-setup.md +++ b/docs/cli/intent-setup.md @@ -1,56 +1,56 @@ ---- -title: setup commands -id: intent-setup ---- - -Intent exposes setup as three separate commands. - -```bash -npx @tanstack/intent@latest add-library-bin -npx @tanstack/intent@latest edit-package-json -npx @tanstack/intent@latest setup-github-actions -``` - -## Commands - -- `add-library-bin`: create a package-local `intent` shim in `bin/` -- `edit-package-json`: add or normalize `package.json` entries needed to publish skills -- `setup-github-actions`: copy workflow templates to `.github/workflows` - -## What each command changes - -- `add-library-bin` - - Creates `bin/intent.js` when `package.json.type` is `module`, otherwise `bin/intent.mjs` - - If either shim already exists, command skips creation - - Shim imports `@tanstack/intent/intent-library` -- `edit-package-json` - - Requires a valid `package.json` in current directory - - Ensures `bin.intent` points to `./bin/intent.` - - Ensures `files` includes required publish entries - - Preserves existing indentation and existing `bin` entries - - Converts string shorthand `bin` to object when needed -- `setup-github-actions` - - Copies templates from `@tanstack/intent/meta/templates/workflows` to `.github/workflows` - - Applies variable substitution for `PACKAGE_NAME`, `REPO`, `DOCS_PATH`, `SRC_PATH` - - Skips files that already exist at destination - -## Required `files` entries - -`edit-package-json` enforces different `files` sets based on package location: - -- Monorepo package: `skills`, `bin` -- Non-monorepo package: `skills`, `bin`, `!skills/_artifacts` - -## Common errors - -- Missing or invalid `package.json` when running `edit-package-json` -- Missing template source when running `setup-github-actions` - -## Notes - -- `add-library-bin` and `setup-github-actions` skip existing files - -## Related - -- [intent validate](./intent-validate) -- [intent scaffold](./intent-scaffold) +--- +title: setup commands +id: intent-setup +--- + +Intent exposes setup as three separate commands. + +```bash +npx @tanstack/intent@latest add-library-bin +npx @tanstack/intent@latest edit-package-json +npx @tanstack/intent@latest setup-github-actions +``` + +## Commands + +- `add-library-bin`: create a package-local `intent` shim in `bin/` +- `edit-package-json`: add or normalize `package.json` entries needed to publish skills +- `setup-github-actions`: copy workflow templates to `.github/workflows` + +## What each command changes + +- `add-library-bin` + - Creates `bin/intent.js` when `package.json.type` is `module`, otherwise `bin/intent.mjs` + - If either shim already exists, command skips creation + - Shim imports `@tanstack/intent/intent-library` +- `edit-package-json` + - Requires a valid `package.json` in current directory + - Ensures `bin.intent` points to `./bin/intent.` + - Ensures `files` includes required publish entries + - Preserves existing indentation and existing `bin` entries + - Converts string shorthand `bin` to object when needed +- `setup-github-actions` + - Copies templates from `@tanstack/intent/meta/templates/workflows` to `.github/workflows` + - Applies variable substitution for `PACKAGE_NAME`, `REPO`, `DOCS_PATH`, `SRC_PATH` + - Skips files that already exist at destination + +## Required `files` entries + +`edit-package-json` enforces different `files` sets based on package location: + +- Monorepo package: `skills`, `bin` +- Non-monorepo package: `skills`, `bin`, `!skills/_artifacts` + +## Common errors + +- Missing or invalid `package.json` when running `edit-package-json` +- Missing template source when running `setup-github-actions` + +## Notes + +- `add-library-bin` and `setup-github-actions` skip existing files + +## Related + +- [intent validate](./intent-validate) +- [intent scaffold](./intent-scaffold) diff --git a/docs/cli/intent-stale.md b/docs/cli/intent-stale.md index 0946702..b532c4d 100644 --- a/docs/cli/intent-stale.md +++ b/docs/cli/intent-stale.md @@ -1,81 +1,81 @@ ---- -title: intent stale -id: intent-stale ---- - -`intent stale` reports whether shipped skills may need review. - -```bash -npx @tanstack/intent@latest stale [--json] -``` - -## Options - -- `--json`: print JSON array of staleness reports - -## Behavior - -- Scans installed intent-enabled packages -- Computes one staleness report per package -- Prints text output by default or JSON with `--json` -- If no packages are found, prints `No intent-enabled packages found.` - -## JSON report schema - -`--json` outputs an array of reports: - -```json -[ - { - "library": "string", - "currentVersion": "string | null", - "skillVersion": "string | null", - "versionDrift": "major | minor | patch | null", - "skills": [ - { - "name": "string", - "reasons": ["string"], - "needsReview": true - } - ] - } -] -``` - -Report fields: - -- `library`: package name -- `currentVersion`: latest version from npm registry (or `null` if unavailable) -- `skillVersion`: `library_version` from skills (or `null`) -- `versionDrift`: `major | minor | patch | null` -- `skills`: array of per-skill checks - -Skill fields: - -- `name` -- `reasons`: one or more staleness reasons -- `needsReview`: boolean (`true` when reasons exist) - -Reason generation: - -- `version drift ( → )` -- `new source ()` when a declared source has no stored sync SHA - -## Text output - -- Report header format: ` ( → ) [ drift]` -- When no skill reasons exist: `All skills up-to-date` -- Otherwise: one warning line per stale skill (`⚠ : , , ...`) - -## Common errors - -- Package scan failure: prints a scanner error -- Registry fetch failures do not crash command; `currentVersion` may be `null` - -## Notes - -- Source staleness checking is conservative: it flags missing source SHAs in sync-state, not remote content differences. - -## Related - -- [intent list](./intent-list) +--- +title: intent stale +id: intent-stale +--- + +`intent stale` reports whether shipped skills may need review. + +```bash +npx @tanstack/intent@latest stale [--json] +``` + +## Options + +- `--json`: print JSON array of staleness reports + +## Behavior + +- Scans installed intent-enabled packages +- Computes one staleness report per package +- Prints text output by default or JSON with `--json` +- If no packages are found, prints `No intent-enabled packages found.` + +## JSON report schema + +`--json` outputs an array of reports: + +```json +[ + { + "library": "string", + "currentVersion": "string | null", + "skillVersion": "string | null", + "versionDrift": "major | minor | patch | null", + "skills": [ + { + "name": "string", + "reasons": ["string"], + "needsReview": true + } + ] + } +] +``` + +Report fields: + +- `library`: package name +- `currentVersion`: latest version from npm registry (or `null` if unavailable) +- `skillVersion`: `library_version` from skills (or `null`) +- `versionDrift`: `major | minor | patch | null` +- `skills`: array of per-skill checks + +Skill fields: + +- `name` +- `reasons`: one or more staleness reasons +- `needsReview`: boolean (`true` when reasons exist) + +Reason generation: + +- `version drift ( → )` +- `new source ()` when a declared source has no stored sync SHA + +## Text output + +- Report header format: ` ( → ) [ drift]` +- When no skill reasons exist: `All skills up-to-date` +- Otherwise: one warning line per stale skill (`⚠ : , , ...`) + +## Common errors + +- Package scan failure: prints a scanner error +- Registry fetch failures do not crash command; `currentVersion` may be `null` + +## Notes + +- Source staleness checking is conservative: it flags missing source SHAs in sync-state, not remote content differences. + +## Related + +- [intent list](./intent-list) diff --git a/docs/cli/intent-validate.md b/docs/cli/intent-validate.md index 5b27c5c..8e4b292 100644 --- a/docs/cli/intent-validate.md +++ b/docs/cli/intent-validate.md @@ -1,58 +1,58 @@ ---- -title: intent validate -id: intent-validate ---- - -`intent validate` checks `SKILL.md` files and artifacts for structural problems. - -```bash -npx @tanstack/intent@latest validate [] -``` - -## Arguments - -- ``: directory containing skills; default is `skills` -- Relative paths are resolved from the current working directory - -## Validation checks - -For each discovered `SKILL.md`: - -- Frontmatter delimiter and structure are valid -- YAML frontmatter parses successfully -- Required fields exist: `name`, `description` -- `name` matches skill directory path under the target root -- `description` length is at most 1024 characters -- `type: framework` requires `requires` to be an array -- Total file length is at most 500 lines - -If `/_artifacts` exists, it also validates artifacts: - -- Required files: `domain_map.yaml`, `skill_spec.md`, `skill_tree.yaml` -- Required files must be non-empty -- `.yaml` artifacts must parse successfully - -## Packaging warnings - -Packaging warnings are always computed from `package.json` in the current working directory: - -- `@tanstack/intent` missing from `devDependencies` -- Missing `bin.intent` entry -- Missing shim (`bin/intent.js` or `bin/intent.mjs`) -- Missing `files` entries when `files` array exists: - - `skills` - - `bin` - - `!skills/_artifacts` - -Warnings are informational; they are printed on both pass and fail paths. - -## Common errors - -- Missing target directory: `Skills directory not found: ` -- No skill files discovered: `No SKILL.md files found` -- Validation failures: aggregated file-specific errors and count - -## Related - -- [intent scaffold](./intent-scaffold) -- [setup commands](./intent-setup) +--- +title: intent validate +id: intent-validate +--- + +`intent validate` checks `SKILL.md` files and artifacts for structural problems. + +```bash +npx @tanstack/intent@latest validate [] +``` + +## Arguments + +- ``: directory containing skills; default is `skills` +- Relative paths are resolved from the current working directory + +## Validation checks + +For each discovered `SKILL.md`: + +- Frontmatter delimiter and structure are valid +- YAML frontmatter parses successfully +- Required fields exist: `name`, `description` +- `name` matches skill directory path under the target root +- `description` length is at most 1024 characters +- `type: framework` requires `requires` to be an array +- Total file length is at most 500 lines + +If `/_artifacts` exists, it also validates artifacts: + +- Required files: `domain_map.yaml`, `skill_spec.md`, `skill_tree.yaml` +- Required files must be non-empty +- `.yaml` artifacts must parse successfully + +## Packaging warnings + +Packaging warnings are always computed from `package.json` in the current working directory: + +- `@tanstack/intent` missing from `devDependencies` +- Missing `bin.intent` entry +- Missing shim (`bin/intent.js` or `bin/intent.mjs`) +- Missing `files` entries when `files` array exists: + - `skills` + - `bin` + - `!skills/_artifacts` + +Warnings are informational; they are printed on both pass and fail paths. + +## Common errors + +- Missing target directory: `Skills directory not found: ` +- No skill files discovered: `No SKILL.md files found` +- Validation failures: aggregated file-specific errors and count + +## Related + +- [intent scaffold](./intent-scaffold) +- [setup commands](./intent-setup) diff --git a/docs/config.json b/docs/config.json index 92a717d..9134108 100644 --- a/docs/config.json +++ b/docs/config.json @@ -1,60 +1,60 @@ -{ - "$schema": "https://raw.githubusercontent.com/TanStack/tanstack.com/main/tanstack-docs-config.schema.json", - "docSearch": { - "appId": "", - "apiKey": "", - "indexName": "tanstack-agents" - }, - "sections": [ - { - "label": "Getting Started", - "children": [ - { - "label": "Overview", - "to": "overview" - }, - { - "label": "Quick Start (Consumers)", - "to": "getting-started/quick-start-consumers" - }, - { - "label": "Quick Start (Maintainers)", - "to": "getting-started/quick-start-maintainers" - } - ] - }, - { - "label": "CLI Reference", - "children": [ - { - "label": "intent install", - "to": "cli/intent-install" - }, - { - "label": "intent list", - "to": "cli/intent-list" - }, - { - "label": "intent meta", - "to": "cli/intent-meta" - }, - { - "label": "intent scaffold", - "to": "cli/intent-scaffold" - }, - { - "label": "intent validate", - "to": "cli/intent-validate" - }, - { - "label": "intent setup-github-actions", - "to": "cli/intent-setup" - }, - { - "label": "intent stale", - "to": "cli/intent-stale" - } - ] - } - ] -} +{ + "$schema": "https://raw.githubusercontent.com/TanStack/tanstack.com/main/tanstack-docs-config.schema.json", + "docSearch": { + "appId": "", + "apiKey": "", + "indexName": "tanstack-agents" + }, + "sections": [ + { + "label": "Getting Started", + "children": [ + { + "label": "Overview", + "to": "overview" + }, + { + "label": "Quick Start (Consumers)", + "to": "getting-started/quick-start-consumers" + }, + { + "label": "Quick Start (Maintainers)", + "to": "getting-started/quick-start-maintainers" + } + ] + }, + { + "label": "CLI Reference", + "children": [ + { + "label": "intent install", + "to": "cli/intent-install" + }, + { + "label": "intent list", + "to": "cli/intent-list" + }, + { + "label": "intent meta", + "to": "cli/intent-meta" + }, + { + "label": "intent scaffold", + "to": "cli/intent-scaffold" + }, + { + "label": "intent validate", + "to": "cli/intent-validate" + }, + { + "label": "intent setup-github-actions", + "to": "cli/intent-setup" + }, + { + "label": "intent stale", + "to": "cli/intent-stale" + } + ] + } + ] +} diff --git a/docs/getting-started/quick-start-consumers.md b/docs/getting-started/quick-start-consumers.md index 8cafd67..4b39ae9 100644 --- a/docs/getting-started/quick-start-consumers.md +++ b/docs/getting-started/quick-start-consumers.md @@ -1,80 +1,80 @@ ---- -title: Quick Start for Consumers -id: quick-start-consumers ---- - -Get started using Intent to set up skill-to-task mappings for your agent. - -## 1. Run install - -The install command guides your agent through the setup process: - -```bash -npx @tanstack/intent@latest install -``` - -This prints a skill that instructs your AI agent to: -1. Check for existing `intent-skills` mappings in your config files (CLAUDE.md, .cursorrules, etc.) -2. Run `intent list` to discover available skills from installed packages -3. Scan your repository structure to understand your project -4. Propose relevant skill-to-task mappings based on your codebase patterns -5. Write or update an `intent-skills` block in your agent config - -Your agent will create mappings like: - -```markdown - -# Skill mappings — when working in these areas, load the linked skill file into context. -skills: - - task: "implementing data fetching with TanStack Query" - load: "node_modules/@tanstack/react-query/skills/core/SKILL.md" - - task: "setting up routing with TanStack Router" - load: "node_modules/@tanstack/react-router/skills/core/SKILL.md" - -``` - -## 2. Use skills in your workflow - -When your agent works on a task that matches a mapping, it automatically loads the corresponding SKILL.md into context to guide implementation. - -## 3. Keep skills up-to-date - -Skills version with library releases. When you update a library: - -```bash -npm update @tanstack/react-query -``` - -The new version brings updated skills automatically — you don't need to do anything. The skills are shipped with the library, so you always get the version that matches your installed code. - -If you need to see what skills have changed, run: - -```bash -npx @tanstack/intent@latest list -``` - -Or use `--json` for machine-readable output: - -```bash -npx @tanstack/intent@latest list --json -``` - -You can also check if any skills reference outdated source documentation: - -```bash -npx @tanstack/intent@latest stale -``` - -## 4. Submit feedback (optional) - -After using a skill, you can submit feedback to help maintainers improve it: - -```bash -npx @tanstack/intent@latest meta feedback-collection -``` - -This prints a skill that guides your agent to collect structured feedback about gaps, errors, and improvements. - - - - +--- +title: Quick Start for Consumers +id: quick-start-consumers +--- + +Get started using Intent to set up skill-to-task mappings for your agent. + +## 1. Run install + +The install command guides your agent through the setup process: + +```bash +npx @tanstack/intent@latest install +``` + +This prints a skill that instructs your AI agent to: +1. Check for existing `intent-skills` mappings in your config files (CLAUDE.md, .cursorrules, etc.) +2. Run `intent list` to discover available skills from installed packages +3. Scan your repository structure to understand your project +4. Propose relevant skill-to-task mappings based on your codebase patterns +5. Write or update an `intent-skills` block in your agent config + +Your agent will create mappings like: + +```markdown + +# Skill mappings — when working in these areas, load the linked skill file into context. +skills: + - task: "implementing data fetching with TanStack Query" + load: "node_modules/@tanstack/react-query/skills/core/SKILL.md" + - task: "setting up routing with TanStack Router" + load: "node_modules/@tanstack/react-router/skills/core/SKILL.md" + +``` + +## 2. Use skills in your workflow + +When your agent works on a task that matches a mapping, it automatically loads the corresponding SKILL.md into context to guide implementation. + +## 3. Keep skills up-to-date + +Skills version with library releases. When you update a library: + +```bash +npm update @tanstack/react-query +``` + +The new version brings updated skills automatically — you don't need to do anything. The skills are shipped with the library, so you always get the version that matches your installed code. + +If you need to see what skills have changed, run: + +```bash +npx @tanstack/intent@latest list +``` + +Or use `--json` for machine-readable output: + +```bash +npx @tanstack/intent@latest list --json +``` + +You can also check if any skills reference outdated source documentation: + +```bash +npx @tanstack/intent@latest stale +``` + +## 4. Submit feedback (optional) + +After using a skill, you can submit feedback to help maintainers improve it: + +```bash +npx @tanstack/intent@latest meta feedback-collection +``` + +This prints a skill that guides your agent to collect structured feedback about gaps, errors, and improvements. + + + + diff --git a/docs/getting-started/quick-start-maintainers.md b/docs/getting-started/quick-start-maintainers.md index b59e6fd..f310aa1 100644 --- a/docs/getting-started/quick-start-maintainers.md +++ b/docs/getting-started/quick-start-maintainers.md @@ -1,200 +1,200 @@ ---- -title: Quick Start for Maintainers -id: quick-start-maintainers ---- - -Get started scaffolding, validating, and shipping skills for your library. - -## Install - - -react: @tanstack/intent -solid: @tanstack/intent -vue: @tanstack/intent -svelte: @tanstack/intent -angular: @tanstack/intent -lit: @tanstack/intent - - -Or run commands without installing: - -```bash -npx @tanstack/intent@latest scaffold -``` - -> [!WARNING] -> When using `npx` or `bunx`, always include `@latest`. Intent-enabled libraries ship a local `intent` binary shim, and without `@latest`, your package manager may resolve to that shim instead of the real CLI. - ---- - -## Initial Setup (With Agent) - -### 1. Scaffold skills - -Start the scaffolding process **with your AI agent**: - -```bash -npx @tanstack/intent@latest scaffold -``` - -This prints a comprehensive prompt that walks you and your agent through three phases: - -**Phase 1: Domain Discovery** -- Scans your documentation, source code, and GitHub issues -- Conducts an interactive interview to surface implicit knowledge -- Produces `domain_map.yaml` and `skill_spec.md` artifacts - -**Phase 2: Tree Generation** -- Designs a skill taxonomy based on the domain map -- Creates a hierarchical skill structure -- Produces `skill_tree.yaml` artifact - -**Phase 3: Skill Generation** -- Writes complete SKILL.md files for each skill -- Includes patterns, failure modes, and API references -- Validates against the Intent specification - -> [!NOTE] -> This is a context-heavy process that involves domain discovery, GitHub issues analysis, and interactive maintainer interviews. The agent will scan your documentation, recent issues and discussions, and ask targeted questions to surface implicit knowledge and common failure modes. The more information you provide about your library's patterns, pitfalls, and real-world usage problems, the better the generated skills will be. Expect multiple rounds of refinement and regular context compaction before completion. - -### 2. Validate skills - -After scaffolding, validate that all SKILL.md files are well-formed: - -```bash -npx @tanstack/intent@latest validate -``` - -This checks: -- Valid YAML frontmatter in every SKILL.md -- Required fields (`name`, `description`) are present -- Skill names match their directory paths -- Description length <= 1024 characters -- Line count limits (500 lines max per skill) -- Framework skills have a `requires` array -- Artifact files exist and are non-empty - -If any artifacts are present (domain_map.yaml, skill_spec.md, skill_tree.yaml), they must parse as valid YAML. - -### 3. Commit skills and artifacts - -Commit both generated skills and the artifacts used to create them: - -``` -skills/ - core/SKILL.md - react/SKILL.md - _artifacts/ - domain_map.yaml - skill_spec.md - skill_tree.yaml -``` - -Artifacts enforce a consistent skill structure across versions, making it easier to audit, refresh, or extend the skill set without starting from scratch. - ---- - -## Publish Configuration - -### 4. Configure your package for publishing - -Run these commands to prepare your package for skill publishing: - -```bash -# Generate the bin shim that consumers use for discovery -npx @tanstack/intent@latest add-library-bin - -# Update package.json with required fields -npx @tanstack/intent@latest edit-package-json - -# Copy CI workflow templates (validate + stale checks) -npx @tanstack/intent@latest setup-github-actions -``` - -**What these do:** - -- `add-library-bin` creates `bin/intent.js` or `bin/intent.mjs` — a shim that lets consumers run `npx your-package intent` to access Intent CLI features -- `edit-package-json` adds: - - `intent` field in package.json with version, repo, and docs metadata - - `bin.intent` entry pointing to the shim - - `files` array entries for `skills/` and `bin/` - - For single packages: also adds `!skills/_artifacts` to exclude artifacts from npm - - For monorepos: skips the artifacts exclusion (artifacts live at repo root) -- `setup-github-actions` copies workflow templates to `.github/workflows/` for automated validation and staleness checking - -### 5. Ship skills with your package - -Skills ship inside your npm package. When you publish: - -```bash -npm publish -``` - -Consumers who install your library automatically get the skills. They discover them with `intent list` and map them with `intent install`. - -**Version alignment:** -- Skills version with your library releases -- Agents always load the skill matching the installed library version -- No drift between code and guidance - ---- - -## Ongoing Maintenance (Manual or Agent-Assisted) - -### 6. Set up CI workflows - -After running `setup-github-actions`, you'll have three workflows in `.github/workflows/`: - -**validate-skills.yml** (runs on PRs touching `skills/`) -- Validates SKILL.md frontmatter and structure -- Ensures files stay under 500 lines -- Runs automatically on every pull request that modifies skills - -**check-skills.yml** (runs on release or manual trigger) -- Automatically detects stale skills after you publish a new release -- Opens a review PR with an agent-friendly prompt -- Requires you to copy the prompt into Claude Code, Cursor, or your agent to update skills - -**notify-intent.yml** (runs on docs/source changes to main) -- Sends a webhook to TanStack/intent when your docs or source change -- Enables cross-library skill staleness tracking -- Requires a fine-grained GitHub token (`INTENT_NOTIFY_TOKEN`) secret - -### 7. Update stale skills - -When you publish a new release, `check-skills.yml` automatically opens a PR flagging skills that need review. - -Manually check which skills need updates with: - -```bash -npx @tanstack/intent@latest stale -``` - -This detects: -- **Version drift** — skill targets an older library version than currently installed -- **New sources** — sources declared in frontmatter that weren't tracked before - -**To update stale skills:** -1. Review the PR opened by `check-skills.yml` -2. Copy the agent prompt from the PR description -3. Paste it into Claude Code, Cursor, or your coding agent -4. The agent reads the stale skills and updates them based on library changes -5. Run `npx @tanstack/intent@latest validate` locally to verify -6. Commit and merge the PR - -> [!NOTE] -> Skills are updated through agent assistance, not full automation. The workflow detects what's stale and provides the prompt — your agent handles the actual updates. - -Use `--json` output for CI integration or scripting. - -### 8. Maintain and iterate - -As your library evolves: - -1. **When APIs change:** Update relevant SKILL.md files with new patterns -2. **When docs change:** Run `intent stale` to identify affected skills -3. **When issues are filed:** Check if the failure mode should be added to "Common Mistakes" -4. **After major releases:** Consider re-running domain discovery to catch new patterns - -> [!TIP] -> Create GitHub issue labels matching your skill names (`skill:core`, `skill:react`). When users file issues, tag them with the relevant skill label to track which areas need the most improvement. +--- +title: Quick Start for Maintainers +id: quick-start-maintainers +--- + +Get started scaffolding, validating, and shipping skills for your library. + +## Install + + +react: @tanstack/intent +solid: @tanstack/intent +vue: @tanstack/intent +svelte: @tanstack/intent +angular: @tanstack/intent +lit: @tanstack/intent + + +Or run commands without installing: + +```bash +npx @tanstack/intent@latest scaffold +``` + +> [!WARNING] +> When using `npx` or `bunx`, always include `@latest`. Intent-enabled libraries ship a local `intent` binary shim, and without `@latest`, your package manager may resolve to that shim instead of the real CLI. + +--- + +## Initial Setup (With Agent) + +### 1. Scaffold skills + +Start the scaffolding process **with your AI agent**: + +```bash +npx @tanstack/intent@latest scaffold +``` + +This prints a comprehensive prompt that walks you and your agent through three phases: + +**Phase 1: Domain Discovery** +- Scans your documentation, source code, and GitHub issues +- Conducts an interactive interview to surface implicit knowledge +- Produces `domain_map.yaml` and `skill_spec.md` artifacts + +**Phase 2: Tree Generation** +- Designs a skill taxonomy based on the domain map +- Creates a hierarchical skill structure +- Produces `skill_tree.yaml` artifact + +**Phase 3: Skill Generation** +- Writes complete SKILL.md files for each skill +- Includes patterns, failure modes, and API references +- Validates against the Intent specification + +> [!NOTE] +> This is a context-heavy process that involves domain discovery, GitHub issues analysis, and interactive maintainer interviews. The agent will scan your documentation, recent issues and discussions, and ask targeted questions to surface implicit knowledge and common failure modes. The more information you provide about your library's patterns, pitfalls, and real-world usage problems, the better the generated skills will be. Expect multiple rounds of refinement and regular context compaction before completion. + +### 2. Validate skills + +After scaffolding, validate that all SKILL.md files are well-formed: + +```bash +npx @tanstack/intent@latest validate +``` + +This checks: +- Valid YAML frontmatter in every SKILL.md +- Required fields (`name`, `description`) are present +- Skill names match their directory paths +- Description length <= 1024 characters +- Line count limits (500 lines max per skill) +- Framework skills have a `requires` array +- Artifact files exist and are non-empty + +If any artifacts are present (domain_map.yaml, skill_spec.md, skill_tree.yaml), they must parse as valid YAML. + +### 3. Commit skills and artifacts + +Commit both generated skills and the artifacts used to create them: + +``` +skills/ + core/SKILL.md + react/SKILL.md + _artifacts/ + domain_map.yaml + skill_spec.md + skill_tree.yaml +``` + +Artifacts enforce a consistent skill structure across versions, making it easier to audit, refresh, or extend the skill set without starting from scratch. + +--- + +## Publish Configuration + +### 4. Configure your package for publishing + +Run these commands to prepare your package for skill publishing: + +```bash +# Generate the bin shim that consumers use for discovery +npx @tanstack/intent@latest add-library-bin + +# Update package.json with required fields +npx @tanstack/intent@latest edit-package-json + +# Copy CI workflow templates (validate + stale checks) +npx @tanstack/intent@latest setup-github-actions +``` + +**What these do:** + +- `add-library-bin` creates `bin/intent.js` or `bin/intent.mjs` — a shim that lets consumers run `npx your-package intent` to access Intent CLI features +- `edit-package-json` adds: + - `intent` field in package.json with version, repo, and docs metadata + - `bin.intent` entry pointing to the shim + - `files` array entries for `skills/` and `bin/` + - For single packages: also adds `!skills/_artifacts` to exclude artifacts from npm + - For monorepos: skips the artifacts exclusion (artifacts live at repo root) +- `setup-github-actions` copies workflow templates to `.github/workflows/` for automated validation and staleness checking + +### 5. Ship skills with your package + +Skills ship inside your npm package. When you publish: + +```bash +npm publish +``` + +Consumers who install your library automatically get the skills. They discover them with `intent list` and map them with `intent install`. + +**Version alignment:** +- Skills version with your library releases +- Agents always load the skill matching the installed library version +- No drift between code and guidance + +--- + +## Ongoing Maintenance (Manual or Agent-Assisted) + +### 6. Set up CI workflows + +After running `setup-github-actions`, you'll have three workflows in `.github/workflows/`: + +**validate-skills.yml** (runs on PRs touching `skills/`) +- Validates SKILL.md frontmatter and structure +- Ensures files stay under 500 lines +- Runs automatically on every pull request that modifies skills + +**check-skills.yml** (runs on release or manual trigger) +- Automatically detects stale skills after you publish a new release +- Opens a review PR with an agent-friendly prompt +- Requires you to copy the prompt into Claude Code, Cursor, or your agent to update skills + +**notify-intent.yml** (runs on docs/source changes to main) +- Sends a webhook to TanStack/intent when your docs or source change +- Enables cross-library skill staleness tracking +- Requires a fine-grained GitHub token (`INTENT_NOTIFY_TOKEN`) secret + +### 7. Update stale skills + +When you publish a new release, `check-skills.yml` automatically opens a PR flagging skills that need review. + +Manually check which skills need updates with: + +```bash +npx @tanstack/intent@latest stale +``` + +This detects: +- **Version drift** — skill targets an older library version than currently installed +- **New sources** — sources declared in frontmatter that weren't tracked before + +**To update stale skills:** +1. Review the PR opened by `check-skills.yml` +2. Copy the agent prompt from the PR description +3. Paste it into Claude Code, Cursor, or your coding agent +4. The agent reads the stale skills and updates them based on library changes +5. Run `npx @tanstack/intent@latest validate` locally to verify +6. Commit and merge the PR + +> [!NOTE] +> Skills are updated through agent assistance, not full automation. The workflow detects what's stale and provides the prompt — your agent handles the actual updates. + +Use `--json` output for CI integration or scripting. + +### 8. Maintain and iterate + +As your library evolves: + +1. **When APIs change:** Update relevant SKILL.md files with new patterns +2. **When docs change:** Run `intent stale` to identify affected skills +3. **When issues are filed:** Check if the failure mode should be added to "Common Mistakes" +4. **After major releases:** Consider re-running domain discovery to catch new patterns + +> [!TIP] +> Create GitHub issue labels matching your skill names (`skill:core`, `skill:react`). When users file issues, tag them with the relevant skill label to track which areas need the most improvement. diff --git a/docs/overview.md b/docs/overview.md index 33cce56..3c765a7 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -1,61 +1,61 @@ ---- -title: Overview -id: overview ---- - -`@tanstack/intent` is a CLI for shipping and consuming Agent Skills as package artifacts. - -Skills are markdown documents that teach AI coding agents how to use your library correctly. Intent versions them with your releases, ships them inside npm packages, discovers them from `node_modules`, and helps agents load them automatically when working on matching tasks. - -## What Intent does - -Intent provides tooling for two workflows: - -**For consumers:** -- Discover skills from installed dependencies -- Generate task-to-skill mappings for your agent config -- Keep skills synchronized with library versions - -**For maintainers (library teams):** -- Scaffold skills through AI-assisted domain discovery -- Validate SKILL.md format and packaging -- Ship skills in the same release pipeline as code -- Track staleness when source docs change - -## How it works - -### Discovery and installation - -```bash -npx @tanstack/intent@latest list -``` - -Scans `node_modules` for intent-enabled packages and shows available skills with paths and descriptions. - -```bash -npx @tanstack/intent@latest install -``` - -Prints instructions for your agent to create `intent-skills` mappings in your config files (CLAUDE.md, .cursorrules, etc.). - -### Scaffolding and validation - -```bash -npx @tanstack/intent@latest scaffold -``` - -Guides your agent through domain discovery, tree generation, and skill authoring with interactive maintainer interviews. - -```bash -npx @tanstack/intent@latest validate -``` - -Enforces SKILL.md format rules and packaging requirements before publish. - -### Staleness tracking - -```bash -npx @tanstack/intent@latest stale -``` - -Detects when skills reference outdated source documentation or library versions. +--- +title: Overview +id: overview +--- + +`@tanstack/intent` is a CLI for shipping and consuming Agent Skills as package artifacts. + +Skills are markdown documents that teach AI coding agents how to use your library correctly. Intent versions them with your releases, ships them inside npm packages, discovers them from `node_modules`, and helps agents load them automatically when working on matching tasks. + +## What Intent does + +Intent provides tooling for two workflows: + +**For consumers:** +- Discover skills from installed dependencies +- Generate task-to-skill mappings for your agent config +- Keep skills synchronized with library versions + +**For maintainers (library teams):** +- Scaffold skills through AI-assisted domain discovery +- Validate SKILL.md format and packaging +- Ship skills in the same release pipeline as code +- Track staleness when source docs change + +## How it works + +### Discovery and installation + +```bash +npx @tanstack/intent@latest list +``` + +Scans `node_modules` for intent-enabled packages and shows available skills with paths and descriptions. + +```bash +npx @tanstack/intent@latest install +``` + +Prints instructions for your agent to create `intent-skills` mappings in your config files (CLAUDE.md, .cursorrules, etc.). + +### Scaffolding and validation + +```bash +npx @tanstack/intent@latest scaffold +``` + +Guides your agent through domain discovery, tree generation, and skill authoring with interactive maintainer interviews. + +```bash +npx @tanstack/intent@latest validate +``` + +Enforces SKILL.md format rules and packaging requirements before publish. + +### Staleness tracking + +```bash +npx @tanstack/intent@latest stale +``` + +Detects when skills reference outdated source documentation or library versions. diff --git a/packages/intent/CHANGELOG.md b/packages/intent/CHANGELOG.md index 135a384..d8cac92 100644 --- a/packages/intent/CHANGELOG.md +++ b/packages/intent/CHANGELOG.md @@ -1,64 +1,64 @@ -# @tanstack/intent - -## 0.0.17 - -### Patch Changes - -- rename notify-playbooks.yml to notify-intent.yml ([#60](https://github.com/TanStack/intent/pull/60)) - -## 0.0.16 - -### Patch Changes - -- enhance SKILL.md with detailed guidance on leveraging GitHub issues and discussions for skill improvement ([#56](https://github.com/TanStack/intent/pull/56)) - -## 0.0.15 - -### Patch Changes - -- enhance SKILL.md with detailed guidance on leveraging GitHub issues and discussions for skill improvement ([#56](https://github.com/TanStack/intent/pull/56)) - -## 0.0.14 - -### Patch Changes - -- Fix scanner to discover transitive dependencies with skills in non-hoisted layouts (pnpm). Add dependency tree walking via `resolveDepDir` that resolves packages through the pnpm virtual store. Also handle shim import errors gracefully when `@tanstack/intent` is not installed, and use `@latest` in all npx commands to avoid local binary conflicts. ([#46](https://github.com/TanStack/intent/pull/46)) - -## 0.0.11 - -### Patch Changes - -- Replace `intent setup` with three focused commands: `intent add-library-bin`, `intent edit-package-json`, and `intent setup-github-actions`. The new `edit-package-json` command automatically wires the `files` array and `bin` field, handling existing CLIs (both object and string shorthand forms) without clobbering them. Improve meta skill SKILL.md files based on real scaffolding feedback: soften lightweight path threshold, add companion library and experimental features questions, add YAML validation step, add subagent guidance for parallel generation, and replace inline feedback sections with a pointer to the feedback-collection skill. ([#37](https://github.com/TanStack/intent/pull/37)) - -- 3 files changed in packages/playbooks/meta/ ([#33](https://github.com/TanStack/intent/pull/33)) - - domain-discovery/SKILL.md (681 → ~792 lines) - - Added "Hard rules" section: 7 mandatory rules enforcing interactive interviews, prohibiting docs-as-substitute, question collapsing, and interview skipping - - Added 3 STOP gates between phases (1→2, 3→4, and after Phase 2d skill list confirmation) - - Strengthened Phase 2 & 4 headers with explicit interactivity requirements and "wait for response" instructions - - Added Phase 3 thoroughness: file checklist before reading, read-all enforcement, peer dependency analysis in Phase 1b - - Added 7 new constraint table rows for interview interactivity - - Updated cross-model compatibility notes with STOP gate and question protection rationale - - Added cross-package monorepo question in Phase 2a - - Added packages field to domain_map.yaml schema (package-relative ownership model) - - Softened feedback section to alpha-temporary - - tree-generator/SKILL.md (859 → ~898 lines) - - Strengthened compressed discovery warning (requires maintainer confirmation to skip) - - Added packages field to skill_tree.yaml schema - - Added monorepo placement section with concrete directory tree example showing skills inside each package - - Added STOP gate after Step 1 (file tree review before writing) - - Added STOP gate after Step 8 (validation results review) - - Added 2 new constraint rows (file tree reviewed, validation presented) - - Softened feedback section to alpha-temporary - - generate-skill/SKILL.md (419 → ~441 lines) - - Added packages field to frontmatter template - - Added monorepo path guidance: skills ship inside each package, not repo root - - Added STOP gate in Step 6: first skill reviewed before generating batch - - Added first-skill-reviewed constraint row - - Softened feedback section to alpha-temporary - -## 0.1.0 - -### Patch Changes - -- Add `intent-library` end-user CLI for library consumers. Libraries wire it up via a generated shim (`intent setup --shim`) to expose an `intent` bin. Running `intent list` recursively discovers skills across the library's dependency tree; `intent install` prints an agent-driven prompt to map skills to project tasks in CLAUDE.md. ([#9](https://github.com/TanStack/intent/pull/9)) +# @tanstack/intent + +## 0.0.17 + +### Patch Changes + +- rename notify-playbooks.yml to notify-intent.yml ([#60](https://github.com/TanStack/intent/pull/60)) + +## 0.0.16 + +### Patch Changes + +- enhance SKILL.md with detailed guidance on leveraging GitHub issues and discussions for skill improvement ([#56](https://github.com/TanStack/intent/pull/56)) + +## 0.0.15 + +### Patch Changes + +- enhance SKILL.md with detailed guidance on leveraging GitHub issues and discussions for skill improvement ([#56](https://github.com/TanStack/intent/pull/56)) + +## 0.0.14 + +### Patch Changes + +- Fix scanner to discover transitive dependencies with skills in non-hoisted layouts (pnpm). Add dependency tree walking via `resolveDepDir` that resolves packages through the pnpm virtual store. Also handle shim import errors gracefully when `@tanstack/intent` is not installed, and use `@latest` in all npx commands to avoid local binary conflicts. ([#46](https://github.com/TanStack/intent/pull/46)) + +## 0.0.11 + +### Patch Changes + +- Replace `intent setup` with three focused commands: `intent add-library-bin`, `intent edit-package-json`, and `intent setup-github-actions`. The new `edit-package-json` command automatically wires the `files` array and `bin` field, handling existing CLIs (both object and string shorthand forms) without clobbering them. Improve meta skill SKILL.md files based on real scaffolding feedback: soften lightweight path threshold, add companion library and experimental features questions, add YAML validation step, add subagent guidance for parallel generation, and replace inline feedback sections with a pointer to the feedback-collection skill. ([#37](https://github.com/TanStack/intent/pull/37)) + +- 3 files changed in packages/playbooks/meta/ ([#33](https://github.com/TanStack/intent/pull/33)) + + domain-discovery/SKILL.md (681 → ~792 lines) + - Added "Hard rules" section: 7 mandatory rules enforcing interactive interviews, prohibiting docs-as-substitute, question collapsing, and interview skipping + - Added 3 STOP gates between phases (1→2, 3→4, and after Phase 2d skill list confirmation) + - Strengthened Phase 2 & 4 headers with explicit interactivity requirements and "wait for response" instructions + - Added Phase 3 thoroughness: file checklist before reading, read-all enforcement, peer dependency analysis in Phase 1b + - Added 7 new constraint table rows for interview interactivity + - Updated cross-model compatibility notes with STOP gate and question protection rationale + - Added cross-package monorepo question in Phase 2a + - Added packages field to domain_map.yaml schema (package-relative ownership model) + - Softened feedback section to alpha-temporary + - tree-generator/SKILL.md (859 → ~898 lines) + - Strengthened compressed discovery warning (requires maintainer confirmation to skip) + - Added packages field to skill_tree.yaml schema + - Added monorepo placement section with concrete directory tree example showing skills inside each package + - Added STOP gate after Step 1 (file tree review before writing) + - Added STOP gate after Step 8 (validation results review) + - Added 2 new constraint rows (file tree reviewed, validation presented) + - Softened feedback section to alpha-temporary + - generate-skill/SKILL.md (419 → ~441 lines) + - Added packages field to frontmatter template + - Added monorepo path guidance: skills ship inside each package, not repo root + - Added STOP gate in Step 6: first skill reviewed before generating batch + - Added first-skill-reviewed constraint row + - Softened feedback section to alpha-temporary + +## 0.1.0 + +### Patch Changes + +- Add `intent-library` end-user CLI for library consumers. Libraries wire it up via a generated shim (`intent setup --shim`) to expose an `intent` bin. Running `intent list` recursively discovers skills across the library's dependency tree; `intent install` prints an agent-driven prompt to map skills to project tasks in CLAUDE.md. ([#9](https://github.com/TanStack/intent/pull/9)) diff --git a/packages/intent/meta/domain-discovery/SKILL.md b/packages/intent/meta/domain-discovery/SKILL.md index bf9f529..7b3e4bb 100644 --- a/packages/intent/meta/domain-discovery/SKILL.md +++ b/packages/intent/meta/domain-discovery/SKILL.md @@ -1,918 +1,918 @@ ---- -name: skill-domain-discovery -description: > - Analyze library documentation and source code, then interview maintainers - to discover capability domains and task-focused skills for AI coding - agents. Activate when creating skills for a new library, organizing - existing documentation into skill categories, or when a maintainer wants - help deciding how to structure their library's agent-facing knowledge. - Produces a domain_map.yaml and skill_spec.md that feed directly into - the skill-tree-generator skill. -metadata: - version: '3.0' - category: meta-tooling - output_artifacts: - - skills/_artifacts/domain_map.yaml - - skills/_artifacts/skill_spec.md - skills: - - tree-generator ---- - -# Domain Discovery & Maintainer Interview - -You are extracting domain knowledge for a library to produce a structured -domain map. Your job is not to summarize documentation — it is to build a -deep understanding of the library first, then use that understanding to -surface the implicit knowledge that maintainers carry but docs miss. - -The output is a set of **task-focused skills** — each one matching a -specific developer moment ("implement a proxy", "set up auth", "audit -before launch"). Domains are an intermediate conceptual grouping you use -during analysis; the final skills emerge from the intersection of domains -and developer tasks. - -There are five phases. Always run them in order — unless the lightweight -path applies (see below). - -1. **Quick scan** — orient yourself (autonomous) -2. **High-level interview** — extract the maintainer's task map -3. **Deep read** — fill in failure modes and detail (autonomous) -4. **Detail interview** — gap-targeted questions, AI-agent failures -5. **Finalize artifacts** - -### Lightweight path (small libraries) - -After Phase 1, decide whether the library warrants the full five-phase -flow or the compressed flow below. This is a judgment call — lean toward -full discovery unless the library is obviously small (single-purpose -utility, 2–3 distinct developer tasks max). Use a compressed flow when -the skill surface is small enough that two interview rounds would be -redundant: - -1. **Phase 1** — Quick scan (same as full flow) -2. **Phase 2+4 combined** — Single interview round. Combine the - high-level task map questions (Phase 2) with gap-targeted and - AI-agent-specific questions (Phase 4) into one interview session - of 4–8 questions total. Skip the draft-review step since the skill - set is small enough to confirm in one pass. -3. **Phase 3** — Deep read (same as full flow, but scope is smaller) -4. **Phase 5** — Finalize artifacts (same as full flow) - -The lightweight path produces identical output artifacts (domain_map.yaml -and skill_spec.md). It just avoids two separate interview rounds when the -library is small enough that one round covers everything. - -### Hard rules — interview phases are mandatory and interactive - -These rules override any other reasoning. No exceptions. - -1. **Phases 2 and 4 are interactive interviews conducted with the - maintainer.** You must ask the questions specified in each sub-section - and wait for the maintainer's response before continuing. Documentation, - source code, and other automated analysis are NOT substitutes for the - maintainer's answers. -2. **Every question in Phases 2 and 4 must be asked as an open-ended - question and sent as a message to the maintainer.** You must then - STOP and WAIT for their reply. Do not answer your own questions. Do - not infer answers from documentation. Do not skip questions because - you believe you already know the answer. -3. **Do not convert open-ended questions into multiple-choice, - yes/no, or confirmation prompts.** The question templates in each - sub-section are open-ended by design. Present them as open-ended - questions. The maintainer's unprompted answers surface knowledge that - pre-structured options suppress. -4. **Minimum question counts are enforced.** Each sub-section specifies - a question count range (e.g. "2–4 questions"). You must ask at least - the minimum number. Asking zero questions in any sub-section is a - protocol violation. -5. **STOP gates are mandatory.** At the boundaries marked `── STOP ──` - below, you must halt execution and wait for the maintainer's response - or acknowledgment before proceeding. Do not continue past a STOP gate - in the same message. -6. **If the maintainer asks to skip an interview phase**, explain the - value of the phase and what will be lost. Proceed with skipping only - if they confirm a second time. -7. **Rich documentation makes interviews MORE valuable, not less.** - When docs are comprehensive, the interview surfaces what docs miss: - implicit knowledge, AI-specific failure modes, undocumented tradeoffs, - and the maintainer's prioritization of what matters most. Never - rationalize skipping interviews because documentation is thorough. - ---- - -## Phase 1 — Quick scan (autonomous, ~10 minutes) - -Orient yourself in the library. You are building a structural map, not -reading exhaustively yet. - -### 1a — Read orientation material - -1. **README** — vocabulary, mental model, what the library does -2. **Getting started / quickstart** — the happy path -3. **Package structure** — if monorepo, identify which packages are - client-facing vs internal. Focus on the 2–3 packages most relevant - to skill consumers (usually client SDKs and primary framework adapters) -4. **AGENTS.md or .cursorrules** — if the library already has agent - guidance, read it. This is high-signal for what the maintainer - considers important - -### 1b — Read peer dependency constraints - -Check `package.json` for `peerDependencies` and `peerDependenciesMeta`. -For each major peer dependency (React, Vue, Svelte, Next.js, etc.): - -1. Note the version range required -2. Read the peer's docs for integration constraints that affect this - library: SSR/hydration rules, component lifecycle boundaries, - browser-only APIs, singleton patterns, connection limits -3. Log framework-specific failure modes — these are the highest-impact - failure modes and cannot be discovered from the library's own source - -Examples of peer-dependency-driven failure modes: - -- SSR: calling browser-only APIs during server render -- React: breaking hook rules in library wrapper components -- Connection limits: opening multiple WebSocket connections per tab -- Singleton patterns: creating multiple client instances in dev mode - -### 1c — Note initial impressions - -Log (but do not group yet): - -- What the library does in one sentence -- The core abstractions a developer interacts with -- Which frameworks it supports -- Any existing skill files, agent configs, or intents -- Whether the library is a monorepo and which packages matter -- Peer dependency constraints — read `peerDependencies` and - `peerDependenciesMeta` from each client-facing package.json to - understand version ranges and optional integrations early - -Present your initial impressions to the maintainer as a brief summary -(3–5 bullets). This orients them on what you found and primes them for -the interview. - -**── STOP ── Do not proceed to Phase 2 until the maintainer has -acknowledged your summary or responded.** - ---- - -## Phase 2 — High-level interview (interactive — requires maintainer) - -The maintainer's mental model of developer tasks IS the skill map. Your -job in this phase is to extract it — not to propose your own structure. - -You must ask the questions below to the maintainer and wait for their -responses. Do not infer answers from documentation or source code. - -### Rules for Phase 2 - -1. One topic per message for open-ended questions. You may batch 2–3 - yes/no or short-confirmation questions together. -2. Ask each question as written (you may adapt phrasing to context, but - keep questions open-ended — never convert to multiple-choice). -3. Wait for the maintainer's response after each question before asking - the next. -4. Take notes silently. Do not summarize back unless asked. -5. If the maintainer gives a short answer, probe deeper before moving on. - -### 2a — Developer tasks (2–4 questions) - -Start with the maintainer's view of what developers do: - -> "Walk me through what a developer actually does with your library — -> not the elevator pitch, but the tasks they come to you for help with, -> from first install through production." - -Follow up to enumerate distinct tasks: - -> "If you listed every distinct thing a developer asks an agent to help -> with using your library, what would that list look like? I'm thinking -> things like 'set up the client', 'implement auth', 'debug sync issues' -> — each one a separate moment where they'd want focused guidance." - -For monorepo libraries, also ask about cross-package tasks: - -> "Are there tasks that touch multiple packages in your monorepo? For -> example, a getting-started flow that requires imports from both the -> client and server packages? I want to make sure skills that span -> package boundaries are captured correctly." - -### 2b — Developer journeys (1–2 questions) - -Surface lifecycle/journey skills that cross-cut task areas: - -> "Are there developer journeys that cut across multiple features? -> For example: a getting-started guide, a go-to-production checklist, -> a migrate-from-v4 walkthrough. Which of these exist in your docs -> or would be valuable as standalone skills?" - -### 2c — Composition and ecosystem (1–3 questions) - -> "Which other libraries does yours compose with most often? Are there -> integration patterns important enough to warrant their own skill — -> for example, using your library with [framework/ORM/router]?" - -> "Are there tasks that developers might expect your library to handle, -> but that are actually handled by a companion library? Which tasks -> should we explicitly exclude from your library's skills?" - -### 2d — Exclude experimental features (1 question) - -> "Are there any features that are experimental, unstable, or not yet -> ready to document for agents? We'll exclude these from the skill set." - -### 2e — Confirm initial skill map - -Synthesize what you heard into a proposed skill list and present it: - -> "Based on what you've told me, here's my proposed skill list: -> [enumerate skills with one-line descriptions]. Does this match how -> you think about your library? What would you add, remove, or rename?" - -**── STOP ── Do not proceed to Phase 3 until the maintainer has -reviewed and confirmed (or corrected) the skill list.** - ---- - -## Phase 3 — Deep read (autonomous) - -You now have the maintainer's task map. Read docs and source to fill -each skill area with concrete content — failure modes, code patterns, -gotchas. - -### Reading order - -Read in this order. Each step builds context for the next. - -Before starting, list every file in the docs directory (and subdirectories). -Use this list as a checklist — every narrative file must be read. Do not -sample a subset and extrapolate. - -1. **Narrative guides** — read as many as needed to build confidence in - your understanding. Prioritize getting-started, migration, and guides - covering the skill areas from Phase 2. Skip exhaustive reading of large - online-only doc sets. -2. **Migration guides** — highest-yield source for failure modes; every - breaking change is exactly what agents trained on older versions produce -3. **API reference** — scan for exports, type signatures, option shapes -4. **Changelog for major versions** — API renames, removed exports, - behavioral changes -5. **GitHub issues and discussions** — this is one of the highest-yield - sources for failure modes and skill content. Docs describe intended - behavior; issues reveal actual behavior and real developer confusion. - - **How to search.** Use `gh search issues` and `gh search prs` (or the - GitHub web search UI) against the library's repo. Run multiple passes: - - **High-engagement issues:** sort by reactions or comments to find the - problems that affect the most developers. These are skill-worthy - even if already fixed — agents trained on older data still hit them. - - **Label-based scans:** look for labels like `bug`, `question`, - `documentation`, `breaking-change`, `good first issue`, `FAQ`, - `help wanted`. Each label category yields different signal: - - `bug` + `closed` → failure modes with known fixes (wrong/correct pairs) - - `question` → developer confusion that skills should preempt - - `breaking-change` → migration-boundary mistakes - - **Keyword searches:** search for the skill's primary APIs, hooks, - and config options by name. E.g. `useQuery stale` or `hydration SSR`. - - **Recent vs. historical:** scan the last 6–12 months of open issues - for current pain points. Then scan older closed issues for patterns - that are now fixed but still appear in agent training data. - - **GitHub Discussions** are equally important when the repo uses them. - Discussions surface "how do I..." patterns and architectural questions - that issues don't capture. Search the Discussions tab (or use - `gh api` to query discussions) for: - - Unanswered or long-thread questions (signal: docs are insufficient) - - Threads marked as "Answered" with a non-obvious solution (skill content) - - Recurring themes across multiple threads (systemic confusion) - - **What to extract from issues/discussions:** - - Frequently reported confusion patterns → candidate failure modes - - Workarounds that developers use before a fix ships → "wrong pattern" - examples that agents will reproduce - - Recurring "how do I X with Y" threads → composition skill candidates - - Misunderstandings about defaults or config → skill content gaps - - Feature requests with many upvotes that change API design → signals - of where the API surface is unintuitive - - What users are implicitly arguing for architecturally — not just - "people are confused about X" but "users keep expecting X to work - like Y, which reveals a tension between [design force] and - [design force]" - - **What NOT to extract:** one-off bugs already fixed, feature requests - unrelated to current API surface, issues about build tooling or CI - that don't affect library usage patterns. - - **Fallback.** If no web access is available, check for FAQ.md, - TROUBLESHOOTING.md, docs/faq, or KNOWN_ISSUES.md as proxies. Also - scan the repo's `.github/ISSUE_TEMPLATE/` for hints about common - issue categories. - -6. **Source code** — verify ambiguities from docs, check defaults, find - assertions and invariant checks. For monorepos, read the 2–3 core - packages deeply. For adapter packages, read one representative adapter - deeply, then scan others for deviations from the pattern. - -### What to log - -Produce a flat concept inventory. One item per line. No grouping yet. - -Log every: - -- Named concept, abstraction, or lifecycle stage -- Public export: function, hook, class, type, constant -- Configuration key, its type, and its default value -- Constraint or invariant (especially any enforced by `throw` or assertion) -- Doc callout: any "note", "warning", "caution", "important", "avoid", "do not" -- Dual API: any place the library has two ways to do the same thing (old/new, - verbose/shorthand, lower-level/higher-level) -- Environment branch: any place behavior depends on SSR/CSR, dev/prod, - framework, bundler, or config flag -- Type gap: any type documented as accepting X but source shows X | Y or - rejects a subtype of X -- Source assertion: any `if (!x) throw`, `invariant()`, or `assert()` with - the error message text -- Issue/discussion pattern: any recurring confusion, workaround, or - misunderstanding surfaced from GitHub issues or discussions — note the - issue/discussion URL, the core misunderstanding, and whether it's - resolved or still active - -### What to extract from migration guides specifically - -For each breaking change between major versions: - -``` -Old pattern: [code that agents trained on older versions will produce] -New pattern: [current correct code] -What changed: [one sentence — the specific mechanism] -Version boundary: [e.g. "v4 → v5"] -``` - -These become high-priority failure modes. - -### 3a — Group concepts into domains - -Move concept inventory items into groups. Two items belong together when: - -- A developer reasons about them together when solving a problem -- Solving one correctly requires understanding how the other works -- They share a lifecycle, configuration scope, or architectural tradeoff -- Getting one wrong tends to produce bugs in the other - -Let library complexity drive the domain count — a focused library may need -only 2–3 domains, while a large framework may need 7+. Validate by asking: -"Would a developer working on a single feature need to load skills from -multiple domains? If so, merge those domains." These are conceptual -groupings, not the final skills. - -Do not create a group for: - -- A single hook, function, or class -- A single doc or reference page -- "Miscellaneous", "Advanced", or "Other" -- Configuration knobs that only affect another group's behavior - -Name each domain as work being performed, not what the library provides. - -**Validation step:** After grouping, check each domain by asking: -"Would a developer working on a single feature need to load skills from -multiple domains?" If yes, merge those domains. Group by developer tasks -(what they're trying to accomplish), not by architecture (how the library -is organized internally). For example, prefer "writing data" over -"producer lifecycle" — the former matches a developer's intent, the latter -matches the codebase structure. - -### 3b — Map domains × tasks → skills - -Merge your conceptual domains with the maintainer's task list from -Phase 2. Each skill should match a specific developer moment while -carrying the conceptual depth of its parent domain(s). - -A skill is well-shaped when: - -- A developer would ask for it by name ("help me set up sync") -- It covers enough for the agent to complete the task end-to-end -- It doesn't require loading 3 other skills to be useful - -Some domains produce multiple skills (a broad domain like "data access" -might yield "live-queries", "mutations", "offline-sync"). Some tasks -span domains (a "go-live" checklist touches security, performance, and -configuration). Both are fine. - -Also consider: - -- **Lifecycle/journey skills** — if the library's docs include a - quickstart guide, go-to-production checklist, or migration path, - suggest these as standalone skills. Don't force them if the docs - don't have the material. -- **Composition skills** — when peer deps or examples show consistent - co-usage with another library, output a full skill for the - integration, not a footnote on a domain. - -### 3c — Flag subsystems within skills - -Check each skill area for internal diversity. A skill may be -conceptually unified but contain multiple independent subsystems with -distinct config interfaces — for example, 5 sync adapters that all -solve "connectivity" but each with unique setup, options, and failure -modes. - -For each skill, ask: "Does this cover 3+ backends, adapters, drivers, -or providers with distinct configuration surfaces?" If yes, list them -as `subsystems`. These tell the skill-tree-generator to produce -per-subsystem reference files. - -Also flag dense API surfaces — if a topic has >10 distinct operators, -option shapes, or patterns (e.g. query operators, schema validation -rules), note it as a `reference_candidates` entry. - -### 3d — Extract failure modes - -For each skill, extract failure modes that pass all three tests: - -- **Plausible** — An agent would generate this because it looks correct - based on the library's design, a similar API, or an older version -- **Silent** — No immediate crash; fails at runtime or under specific conditions -- **Grounded** — Traceable to a specific doc page, source location, or issue - -**Where to find them:** - -| Source | What to extract | -| -------------------- | -------------------------------------------------------------------- | -| Migration guides | Every breaking change → old pattern is the wrong code | -| Doc callouts | Any "note", "warning", "avoid" with surrounding context | -| Source assertions | `throw` and `invariant()` messages describe the failure | -| Default values | Undocumented or surprising defaults that cause wrong behavior | -| Type precision | Source type more restrictive than docs imply | -| Environment branches | `typeof window`, SSR flags, `NODE_ENV` — behavior differs silently | -| GitHub issues | Recurring bug reports with workarounds → wrong/correct code pairs | -| GitHub discussions | "How do I…" threads with non-obvious answers → missing skill content | - -Target 3 failure modes per skill minimum. Complex skills target 5–6. - -**Code patterns.** Every failure mode should include `wrong_pattern` and -`correct_pattern` fields with short code snippets (3–10 lines each). -The wrong pattern is what an agent would generate; the correct pattern -is the fix. These feed directly into SKILL.md Common Mistakes sections -as wrong/correct code pairs. If the failure mode is purely conceptual -(e.g. an architectural choice) rather than a code pattern, omit both -fields and explain in `mechanism` instead. - -**Cross-skill failure modes.** Some failure modes belong to multiple -skills. A developer doing SSR work and a developer doing state management -both need to know about "stale state during hydration" — they load -different skills but need the same advice. When a failure mode spans -skills, list all relevant skill slugs in its `skills` field. The -skill-tree-generator will write it into every corresponding SKILL file. - -List a cross-skill failure mode once, under its primary skill. Set -the `skills` field to all skill slugs it applies to. Do not duplicate -the entry in the YAML — the skill-tree-generator handles duplication -into multiple SKILL files at generation time. - -### 3e — Identify cross-skill tensions - -Look for places where design forces between skills conflict. A tension -is not a failure mode — it's a structural pull where optimizing for one -task makes another harder. Examples: - -- "Getting-started simplicity conflicts with production operational safety" -- "Type-safety strictness conflicts with rapid prototyping flexibility" -- "SSR correctness requires patterns that hurt client-side performance" - -Tensions are where agents fail most because they optimize for one task -without seeing the tradeoff. Each tension should name the skills in -conflict, describe the pull, and state what an agent gets wrong when it -only considers one side. - -Target 2–4 tensions. If you find none, the skills may be too isolated — -revisit whether you're missing cross-connections. - -### 3f — Map cross-references - -Beyond tensions (conflicts) and shared failure modes, identify skills -that illuminate each other without conflicting. A cross-reference means: -"an agent loading skill A would produce better code if it knew about -skill B." These become "See also" pointers in the generated SKILL.md -files. - -For each pair, note: - -- Which skill references which (can be bidirectional) -- Why awareness of the other skill improves output - -Examples: - -- A quickstart skill references the security checklist ("after setup, audit") -- A state management skill references an SSR skill ("state hydration - requires understanding SSR lifecycle") -- A data writing skill references a data reading skill ("writes affect - how queries invalidate") - -Output these in the `cross_references` section of domain_map.yaml. - -### 3g — Identify gaps - -For each skill, explicitly list what you could NOT determine from docs -and source alone. These become interview questions in Phase 4. - -Common gaps: - -- "Docs describe X but don't explain when you'd choose X over Y" -- "Migration guide mentions this changed but doesn't say what the old - behavior was" -- "Source has an assertion here but no doc explains what triggers it" -- "GitHub issues show confusion about X but docs don't address it" -- "I found two patterns for doing X — unclear which is current/preferred" - -### 3h — Discover composition targets - -Scan `package.json` for peer dependencies, optional dependencies, and -`peerDependenciesMeta`. Scan example directories and integration tests -for import patterns. For each frequently co-used library, log: - -- Library name and which features interact -- Whether it's a required or optional integration -- Any example code showing the integration pattern - -These become targeted composition questions in Phase 4e. - -### 3i — Produce the draft - -Write the full `domain_map.yaml` (format in Output Artifacts below) with -a `status: draft` field. Flag every gap in the `gaps` section. - -Present the draft to the maintainer before starting Phase 4: - -> "I've read the docs and source for [library] and produced a draft with -> [N] skills and [M] failure modes. I've flagged [K] specific gaps where -> I need your input." - -Include the full draft domain_map.yaml in your message so the maintainer -can review it. Also include a checklist of all docs files you read. - -**── STOP ── Do not proceed to Phase 4 until the maintainer has -reviewed the draft and responded. Their feedback on the draft informs -the detail interview questions.** - ---- - -## Phase 4 — Detail interview (interactive — requires maintainer) - -You have the maintainer's task map and a deep read. The interview now -fills gaps, validates your understanding, and surfaces implicit knowledge. - -You must ask the questions below to the maintainer and wait for their -responses. Do not infer answers from documentation or source code — -even for gaps you think you can answer from your reading. - -### Rules for Phase 4 - -1. One topic per message for open-ended questions. You may batch 2–3 - yes/no or short-confirmation questions together. -2. Ask each question as written (you may adapt phrasing to context, but - keep questions open-ended — never convert to multiple-choice). -3. Each question must reference something specific from your reading. -4. Wait for the maintainer's response after each question before asking - the next. -5. If the maintainer gives a short answer, probe deeper before moving on. -6. Take notes silently. Do not summarize back unless asked. - -### 4a — Draft review (2–3 questions) - -Start by confirming or correcting your skill list and failure modes: - -> "Here's the skill list I've built from our earlier conversation plus -> the deep read: [list skills with brief descriptions]. Does this still -> match your thinking? Anything to add, remove, or rename?" - -Follow up on any corrections. Then: - -> "I identified [M] failure modes from the docs and migration guides. Are -> there important ones I missed — especially patterns that look correct -> but fail silently?" - -### 4b — Gap-targeted questions (3–8 questions) - -For each gap flagged in Phase 3g, ask a specific question. These are not -generic — they reference what you found: - -**Instead of:** "What do developers get wrong?" -**Ask:** "I noticed the migration guide from v4 to v5 changed how [X] works, -but the docs don't show the old pattern. Do agents still commonly generate -the v4 pattern? What does it look like?" - -**Instead of:** "Are there surprising interactions?" -**Ask:** "The source throws an invariant error if [X] is called before [Y], -but the docs don't mention ordering. How often do developers hit this?" - -**Instead of:** "What's different in SSR vs client?" -**Ask:** "I found a `typeof window` check in [file] that changes behavior -for [feature]. What goes wrong when developers test only in the browser -and deploy with SSR?" - -Adapt from this bank of gap-targeted question templates: - -- "I found two patterns for [X] in the docs — [pattern A] and [pattern B]. - Which is current, and does the old one still work?" -- "The source defaults [config option] to [value], which seems surprising - for [reason]. Is this intentional? Do developers need to override it?" -- "GitHub issues show [N] reports of confusion about [X]. What's the - underlying misunderstanding?" -- "I couldn't find docs for how [feature A] interacts with [feature B]. - What should an agent know about using them together?" -- "The API reference shows [type signature], but the guide examples use - a different shape. Which is accurate?" -- "I found [N] GitHub issues/discussions where developers struggled with - [X]. The common workaround seems to be [Y] — is that the recommended - approach, or is there a better pattern that should be documented?" -- "GitHub discussions show developers repeatedly asking how to combine - [feature A] with [feature B]. Is there an intended integration pattern, - or is this a gap in the current API?" - -### 4c — AI-agent-specific failure modes (2–4 questions) - -These target mistakes that AI coding agents make but human developers -typically don't. Agent-specific failures are often the highest-value -findings — in testing, maintainer answers to these questions produced -the most critical failure modes. - -- "What mistakes would an AI coding agent make that a human developer - wouldn't? Think about: hallucinating APIs that don't exist, defaulting - to language primitives instead of library abstractions, choosing the - wrong adapter or integration path." -- "When an agent generates code using your library, what's the first - thing you'd check? What pattern would make you immediately say - 'an AI wrote this'?" -- "Are there parts of your API where the naming or design is misleading - enough that an agent with no prior context would pick the wrong - approach? What would it pick, and what should it pick instead?" -- "Are there features where the docs are comprehensive for human - developers but would still mislead an agent? For example, features - that require understanding unstated context, or where the 'obvious' - approach from reading the API surface is wrong." - -### 4d — Implicit knowledge extraction (3–5 questions) - -These surface knowledge that doesn't appear in any docs: - -- "What does a senior developer using your library know that a mid-level - developer doesn't — something that isn't written down anywhere?" -- "Are there patterns that work fine for prototyping but are dangerous - in production? What makes them dangerous?" -- "What question do you answer most often in Discord or GitHub issues - that the docs technically cover but people still miss?" -- "Is there anything you'd change about the API design if you could break - backwards compatibility? What's the current workaround?" - -### 4e — Composition questions (if library interacts with others) - -Use what you discovered in Phase 3h. For each integration target -identified from peer dependencies and example code, ask targeted -questions: - -- "I see [library] is a peer dependency and [N] examples import it - alongside yours. What's the most common integration mistake?" -- "When developers use [your library] with [other library], are there - patterns that only matter when both are present?" -- "I found [specific integration pattern] in the examples. Is this the - recommended approach, or is there a better way that isn't documented?" - ---- - -## Phase 5 — Finalize artifacts - -Merge interview findings into the draft. For each interview answer: - -1. If it confirms a skill or failure mode — no action needed -2. If it corrects something — update the map -3. If it adds a new failure mode — add it with source "maintainer interview" -4. If it reveals a new skill — add it -5. If it fills a gap — remove from gaps section - -Validate the domain_map.yaml by parsing it with a YAML parser. Check for -duplicate keys, invalid syntax, and structural correctness. Fix any issues -before presenting the final artifact. - -Update `status: draft` to `status: reviewed`. - ---- - -## Output artifacts - -If the maintainer uses a custom skills root, replace `skills/` in the paths -below with their chosen directory. - -**Monorepo layout:** For monorepos, domain map artifacts go at the REPO ROOT -(e.g. `_artifacts/domain_map.yaml`) since they describe the whole library. -Skills are generated per-package later by the tree-generator and generate-skill -steps. - -### 1. skills/\_artifacts/domain_map.yaml - -```yaml -# domain_map.yaml -# Generated by skill-domain-discovery -# Library: [name] -# Version: [version this map targets] -# Date: [ISO date] -# Status: [draft | reviewed] - -library: - name: '[package-name]' - version: '[version]' - repository: '[repo URL]' - description: '[one line]' - primary_framework: '[React | Vue | Svelte | framework-agnostic]' - -domains: - - name: '[work-oriented domain name]' - slug: '[kebab-case]' - description: '[conceptual grouping — what a developer is reasoning about]' - -skills: - - name: '[task-focused skill name]' - slug: '[kebab-case]' - domain: '[parent domain slug]' - description: '[what a developer is doing — matches a specific task/moment]' - type: '[core | framework | lifecycle | composition]' - packages: # required for monorepo; omit for single-package libraries - - '[primary package name]' - - '[secondary package name, if skill spans multiple packages]' - covers: - - '[API/hook/concept 1]' - - '[API/hook/concept 2]' - tasks: - - '[example task 1]' - - '[example task 2]' - - '[example task 3]' - subsystems: # omit if skill has no independent subsystems - - name: '[adapter/backend name]' - package: '[npm package if separate]' - config_surface: '[brief description of unique config]' - reference_candidates: # omit if no dense API surfaces - - topic: '[e.g. query operators, schema validation]' - reason: '[e.g. >10 distinct operators with signatures]' - failure_modes: - - mistake: '[5-10 word phrase]' - mechanism: '[one sentence]' - wrong_pattern: | # the code an agent would incorrectly generate - [short code snippet showing the mistake] - correct_pattern: | # the code that should be generated instead - [short code snippet showing the fix] - source: '[doc page, source file, issue link, or maintainer interview]' - priority: '[CRITICAL | HIGH | MEDIUM]' - status: '[active | fixed-but-legacy-risk | removed]' - version_context: "[e.g. 'Fixed in v5.2 but agents trained on older code still generate this']" - skills: ['[this-skill-slug]'] # list all skills this belongs to; omit if single-skill - compositions: - - library: '[other library name]' - skill: '[composition skill name if applicable]' - -tensions: - - name: '[short phrase describing the pull]' - skills: ['[skill-slug-a]', '[skill-slug-b]'] - description: '[what conflicts — one sentence]' - implication: '[what an agent gets wrong when it only considers one side]' - -cross_references: - - from: '[skill-slug]' - to: '[skill-slug]' - reason: '[why loading one skill benefits from awareness of the other]' - -gaps: - - skill: '[skill slug]' - question: '[what still needs input]' - context: '[why this matters]' - status: '[open | resolved]' -``` - -### 2. skills/\_artifacts/skill_spec.md - -A human-readable companion document. Follow this structure: - -```markdown -# [Library Name] — Skill Spec - -[2–3 sentences: what this library is, what problem it solves. Factual, -not promotional.] - -## Domains - -| Domain | Description | Skills | -| ------ | --------------------- | ----------------------- | -| [name] | [conceptual grouping] | [skill-1, skill-2, ...] | - -## Skill Inventory - -| Skill | Type | Domain | What it covers | Failure modes | -| ------ | -------------------------------------- | -------- | -------------- | ------------- | -| [name] | [core/framework/lifecycle/composition] | [domain] | [list] | [count] | - -## Failure Mode Inventory - -### [Skill name] ([count] failure modes) - -| # | Mistake | Priority | Source | Cross-skill? | -| --- | -------- | -------- | ---------------------- | ------------------------ | -| 1 | [phrase] | CRITICAL | [doc/source/interview] | [other skill slugs or —] | - -[Repeat table for each skill.] - -## Tensions - -| Tension | Skills | Agent implication | -| -------------- | ------------------- | ----------------------- | -| [short phrase] | [slug-a] ↔ [slug-b] | [what agents get wrong] | - -## Cross-References - -| From | To | Reason | -| ------ | ------ | ----------------------------------------- | -| [slug] | [slug] | [why awareness of one improves the other] | - -## Subsystems & Reference Candidates - -| Skill | Subsystems | Reference candidates | -| ------ | ------------------------------ | -------------------------- | -| [slug] | [adapter1, adapter2, ...] or — | [topic needing depth] or — | - -## Remaining Gaps - -| Skill | Question | Status | -| ------ | ------------------------ | ------ | -| [slug] | [what still needs input] | open | - -[Omit this section if all gaps were resolved in the interview.] - -## Recommended Skill File Structure - -- **Core skills:** [list which skills are framework-agnostic] -- **Framework skills:** [list per-framework skills needed] -- **Lifecycle skills:** [list journey/lifecycle skills if applicable] -- **Composition skills:** [list integration seams needing composition skills] -- **Reference files:** [list skills needing references/ based on subsystems - or dense API surfaces] - -## Composition Opportunities - -| Library | Integration points | Composition skill needed? | -| ------- | ------------------ | ----------------------------- | -| [name] | [what interacts] | [yes/no — if yes, skill name] | -``` - ---- - -## Constraints - -| Check | Rule | -| ------------------------------------- | -------------------------------------------------------------------------- | -| Quick scan before interview | Never interview without at least reading README and package structure | -| High-level interview before deep read | The maintainer's task map informs what you read deeply | -| **Interview phases are interactive** | Phases 2 and 4 require sending questions to the maintainer and waiting | -| **Docs are not a substitute** | Documentation cannot replace maintainer answers — even comprehensive docs | -| **Open-ended questions stay open** | Never convert interview questions to multiple-choice or yes/no | -| **Minimum question counts enforced** | Each sub-section's minimum count must be met; zero questions = violation | -| **STOP gates are mandatory** | Do not proceed past a STOP gate without maintainer response | -| Batch only confirmations | Yes/no questions may batch 2–3; open-ended questions get their own message | -| Questions reference findings | No generic questions — cite what you found | -| Skills are task-focused | Each skill matches a developer moment, not a conceptual area | -| 3+ failure modes per skill | Complex skills target 5–6 | -| Every failure mode sourced | Doc page, source file, issue link, or maintainer interview | -| Gaps are explicit | Unknown areas flagged, not guessed | -| No marketing prose | Library description is factual, not promotional | -| domain_map.yaml is valid YAML | Parseable by any YAML parser | -| Draft before detail interview | Present draft for review before Phase 4 | -| **Draft reviewed before Phase 4** | Maintainer must acknowledge or respond to draft before detail interview | -| Agent-specific failures probed | Always ask AI-agent-specific questions in Phase 4c | -| Compositions discovered from code | Scan peer deps and examples before asking composition questions | -| Cross-skill failure modes tagged | Failure modes spanning skills list all relevant slugs | -| Tensions identified | 2–4 cross-skill tensions; if none found, revisit skill boundaries | -| Subsystems flagged | Skills with 3+ adapters/backends list them as subsystems | -| Dense surfaces flagged | Topics with >10 patterns noted as reference_candidates | -| Lifecycle skills considered | Suggest journey skills when docs have the material | -| Cross-references mapped | Skills that illuminate each other get "See also" pointers | -| **All docs files read** | List docs directory contents and read every narrative file — no sampling | - ---- - -## Cross-model compatibility notes - -This skill is designed to produce consistent results across Claude, GPT-4+, -Gemini, and open-source models. To achieve this: - -- All instructions use imperative sentences, not suggestions -- Interview phases use explicit STOP gates to prevent models from - continuing autonomously past interactive checkpoints -- Hard rules at the top override any model tendency to rationalize - skipping interactive phases when documentation is available -- Open-ended questions are explicitly protected from conversion to - multiple-choice or confirmation prompts, which models default to - when they have enough context to pre-populate answers -- Output formats use YAML (universally parsed) and Markdown tables - (universally rendered) -- Examples use concrete values, not placeholders like "[your value here]" -- Section boundaries use Markdown headers (##) for navigation and --- for - phase separation -- No model-specific features (no XML tags in output, no tool_use assumptions) +--- +name: skill-domain-discovery +description: > + Analyze library documentation and source code, then interview maintainers + to discover capability domains and task-focused skills for AI coding + agents. Activate when creating skills for a new library, organizing + existing documentation into skill categories, or when a maintainer wants + help deciding how to structure their library's agent-facing knowledge. + Produces a domain_map.yaml and skill_spec.md that feed directly into + the skill-tree-generator skill. +metadata: + version: '3.0' + category: meta-tooling + output_artifacts: + - skills/_artifacts/domain_map.yaml + - skills/_artifacts/skill_spec.md + skills: + - tree-generator +--- + +# Domain Discovery & Maintainer Interview + +You are extracting domain knowledge for a library to produce a structured +domain map. Your job is not to summarize documentation — it is to build a +deep understanding of the library first, then use that understanding to +surface the implicit knowledge that maintainers carry but docs miss. + +The output is a set of **task-focused skills** — each one matching a +specific developer moment ("implement a proxy", "set up auth", "audit +before launch"). Domains are an intermediate conceptual grouping you use +during analysis; the final skills emerge from the intersection of domains +and developer tasks. + +There are five phases. Always run them in order — unless the lightweight +path applies (see below). + +1. **Quick scan** — orient yourself (autonomous) +2. **High-level interview** — extract the maintainer's task map +3. **Deep read** — fill in failure modes and detail (autonomous) +4. **Detail interview** — gap-targeted questions, AI-agent failures +5. **Finalize artifacts** + +### Lightweight path (small libraries) + +After Phase 1, decide whether the library warrants the full five-phase +flow or the compressed flow below. This is a judgment call — lean toward +full discovery unless the library is obviously small (single-purpose +utility, 2–3 distinct developer tasks max). Use a compressed flow when +the skill surface is small enough that two interview rounds would be +redundant: + +1. **Phase 1** — Quick scan (same as full flow) +2. **Phase 2+4 combined** — Single interview round. Combine the + high-level task map questions (Phase 2) with gap-targeted and + AI-agent-specific questions (Phase 4) into one interview session + of 4–8 questions total. Skip the draft-review step since the skill + set is small enough to confirm in one pass. +3. **Phase 3** — Deep read (same as full flow, but scope is smaller) +4. **Phase 5** — Finalize artifacts (same as full flow) + +The lightweight path produces identical output artifacts (domain_map.yaml +and skill_spec.md). It just avoids two separate interview rounds when the +library is small enough that one round covers everything. + +### Hard rules — interview phases are mandatory and interactive + +These rules override any other reasoning. No exceptions. + +1. **Phases 2 and 4 are interactive interviews conducted with the + maintainer.** You must ask the questions specified in each sub-section + and wait for the maintainer's response before continuing. Documentation, + source code, and other automated analysis are NOT substitutes for the + maintainer's answers. +2. **Every question in Phases 2 and 4 must be asked as an open-ended + question and sent as a message to the maintainer.** You must then + STOP and WAIT for their reply. Do not answer your own questions. Do + not infer answers from documentation. Do not skip questions because + you believe you already know the answer. +3. **Do not convert open-ended questions into multiple-choice, + yes/no, or confirmation prompts.** The question templates in each + sub-section are open-ended by design. Present them as open-ended + questions. The maintainer's unprompted answers surface knowledge that + pre-structured options suppress. +4. **Minimum question counts are enforced.** Each sub-section specifies + a question count range (e.g. "2–4 questions"). You must ask at least + the minimum number. Asking zero questions in any sub-section is a + protocol violation. +5. **STOP gates are mandatory.** At the boundaries marked `── STOP ──` + below, you must halt execution and wait for the maintainer's response + or acknowledgment before proceeding. Do not continue past a STOP gate + in the same message. +6. **If the maintainer asks to skip an interview phase**, explain the + value of the phase and what will be lost. Proceed with skipping only + if they confirm a second time. +7. **Rich documentation makes interviews MORE valuable, not less.** + When docs are comprehensive, the interview surfaces what docs miss: + implicit knowledge, AI-specific failure modes, undocumented tradeoffs, + and the maintainer's prioritization of what matters most. Never + rationalize skipping interviews because documentation is thorough. + +--- + +## Phase 1 — Quick scan (autonomous, ~10 minutes) + +Orient yourself in the library. You are building a structural map, not +reading exhaustively yet. + +### 1a — Read orientation material + +1. **README** — vocabulary, mental model, what the library does +2. **Getting started / quickstart** — the happy path +3. **Package structure** — if monorepo, identify which packages are + client-facing vs internal. Focus on the 2–3 packages most relevant + to skill consumers (usually client SDKs and primary framework adapters) +4. **AGENTS.md or .cursorrules** — if the library already has agent + guidance, read it. This is high-signal for what the maintainer + considers important + +### 1b — Read peer dependency constraints + +Check `package.json` for `peerDependencies` and `peerDependenciesMeta`. +For each major peer dependency (React, Vue, Svelte, Next.js, etc.): + +1. Note the version range required +2. Read the peer's docs for integration constraints that affect this + library: SSR/hydration rules, component lifecycle boundaries, + browser-only APIs, singleton patterns, connection limits +3. Log framework-specific failure modes — these are the highest-impact + failure modes and cannot be discovered from the library's own source + +Examples of peer-dependency-driven failure modes: + +- SSR: calling browser-only APIs during server render +- React: breaking hook rules in library wrapper components +- Connection limits: opening multiple WebSocket connections per tab +- Singleton patterns: creating multiple client instances in dev mode + +### 1c — Note initial impressions + +Log (but do not group yet): + +- What the library does in one sentence +- The core abstractions a developer interacts with +- Which frameworks it supports +- Any existing skill files, agent configs, or intents +- Whether the library is a monorepo and which packages matter +- Peer dependency constraints — read `peerDependencies` and + `peerDependenciesMeta` from each client-facing package.json to + understand version ranges and optional integrations early + +Present your initial impressions to the maintainer as a brief summary +(3–5 bullets). This orients them on what you found and primes them for +the interview. + +**── STOP ── Do not proceed to Phase 2 until the maintainer has +acknowledged your summary or responded.** + +--- + +## Phase 2 — High-level interview (interactive — requires maintainer) + +The maintainer's mental model of developer tasks IS the skill map. Your +job in this phase is to extract it — not to propose your own structure. + +You must ask the questions below to the maintainer and wait for their +responses. Do not infer answers from documentation or source code. + +### Rules for Phase 2 + +1. One topic per message for open-ended questions. You may batch 2–3 + yes/no or short-confirmation questions together. +2. Ask each question as written (you may adapt phrasing to context, but + keep questions open-ended — never convert to multiple-choice). +3. Wait for the maintainer's response after each question before asking + the next. +4. Take notes silently. Do not summarize back unless asked. +5. If the maintainer gives a short answer, probe deeper before moving on. + +### 2a — Developer tasks (2–4 questions) + +Start with the maintainer's view of what developers do: + +> "Walk me through what a developer actually does with your library — +> not the elevator pitch, but the tasks they come to you for help with, +> from first install through production." + +Follow up to enumerate distinct tasks: + +> "If you listed every distinct thing a developer asks an agent to help +> with using your library, what would that list look like? I'm thinking +> things like 'set up the client', 'implement auth', 'debug sync issues' +> — each one a separate moment where they'd want focused guidance." + +For monorepo libraries, also ask about cross-package tasks: + +> "Are there tasks that touch multiple packages in your monorepo? For +> example, a getting-started flow that requires imports from both the +> client and server packages? I want to make sure skills that span +> package boundaries are captured correctly." + +### 2b — Developer journeys (1–2 questions) + +Surface lifecycle/journey skills that cross-cut task areas: + +> "Are there developer journeys that cut across multiple features? +> For example: a getting-started guide, a go-to-production checklist, +> a migrate-from-v4 walkthrough. Which of these exist in your docs +> or would be valuable as standalone skills?" + +### 2c — Composition and ecosystem (1–3 questions) + +> "Which other libraries does yours compose with most often? Are there +> integration patterns important enough to warrant their own skill — +> for example, using your library with [framework/ORM/router]?" + +> "Are there tasks that developers might expect your library to handle, +> but that are actually handled by a companion library? Which tasks +> should we explicitly exclude from your library's skills?" + +### 2d — Exclude experimental features (1 question) + +> "Are there any features that are experimental, unstable, or not yet +> ready to document for agents? We'll exclude these from the skill set." + +### 2e — Confirm initial skill map + +Synthesize what you heard into a proposed skill list and present it: + +> "Based on what you've told me, here's my proposed skill list: +> [enumerate skills with one-line descriptions]. Does this match how +> you think about your library? What would you add, remove, or rename?" + +**── STOP ── Do not proceed to Phase 3 until the maintainer has +reviewed and confirmed (or corrected) the skill list.** + +--- + +## Phase 3 — Deep read (autonomous) + +You now have the maintainer's task map. Read docs and source to fill +each skill area with concrete content — failure modes, code patterns, +gotchas. + +### Reading order + +Read in this order. Each step builds context for the next. + +Before starting, list every file in the docs directory (and subdirectories). +Use this list as a checklist — every narrative file must be read. Do not +sample a subset and extrapolate. + +1. **Narrative guides** — read as many as needed to build confidence in + your understanding. Prioritize getting-started, migration, and guides + covering the skill areas from Phase 2. Skip exhaustive reading of large + online-only doc sets. +2. **Migration guides** — highest-yield source for failure modes; every + breaking change is exactly what agents trained on older versions produce +3. **API reference** — scan for exports, type signatures, option shapes +4. **Changelog for major versions** — API renames, removed exports, + behavioral changes +5. **GitHub issues and discussions** — this is one of the highest-yield + sources for failure modes and skill content. Docs describe intended + behavior; issues reveal actual behavior and real developer confusion. + + **How to search.** Use `gh search issues` and `gh search prs` (or the + GitHub web search UI) against the library's repo. Run multiple passes: + - **High-engagement issues:** sort by reactions or comments to find the + problems that affect the most developers. These are skill-worthy + even if already fixed — agents trained on older data still hit them. + - **Label-based scans:** look for labels like `bug`, `question`, + `documentation`, `breaking-change`, `good first issue`, `FAQ`, + `help wanted`. Each label category yields different signal: + - `bug` + `closed` → failure modes with known fixes (wrong/correct pairs) + - `question` → developer confusion that skills should preempt + - `breaking-change` → migration-boundary mistakes + - **Keyword searches:** search for the skill's primary APIs, hooks, + and config options by name. E.g. `useQuery stale` or `hydration SSR`. + - **Recent vs. historical:** scan the last 6–12 months of open issues + for current pain points. Then scan older closed issues for patterns + that are now fixed but still appear in agent training data. + + **GitHub Discussions** are equally important when the repo uses them. + Discussions surface "how do I..." patterns and architectural questions + that issues don't capture. Search the Discussions tab (or use + `gh api` to query discussions) for: + - Unanswered or long-thread questions (signal: docs are insufficient) + - Threads marked as "Answered" with a non-obvious solution (skill content) + - Recurring themes across multiple threads (systemic confusion) + + **What to extract from issues/discussions:** + - Frequently reported confusion patterns → candidate failure modes + - Workarounds that developers use before a fix ships → "wrong pattern" + examples that agents will reproduce + - Recurring "how do I X with Y" threads → composition skill candidates + - Misunderstandings about defaults or config → skill content gaps + - Feature requests with many upvotes that change API design → signals + of where the API surface is unintuitive + - What users are implicitly arguing for architecturally — not just + "people are confused about X" but "users keep expecting X to work + like Y, which reveals a tension between [design force] and + [design force]" + + **What NOT to extract:** one-off bugs already fixed, feature requests + unrelated to current API surface, issues about build tooling or CI + that don't affect library usage patterns. + + **Fallback.** If no web access is available, check for FAQ.md, + TROUBLESHOOTING.md, docs/faq, or KNOWN_ISSUES.md as proxies. Also + scan the repo's `.github/ISSUE_TEMPLATE/` for hints about common + issue categories. + +6. **Source code** — verify ambiguities from docs, check defaults, find + assertions and invariant checks. For monorepos, read the 2–3 core + packages deeply. For adapter packages, read one representative adapter + deeply, then scan others for deviations from the pattern. + +### What to log + +Produce a flat concept inventory. One item per line. No grouping yet. + +Log every: + +- Named concept, abstraction, or lifecycle stage +- Public export: function, hook, class, type, constant +- Configuration key, its type, and its default value +- Constraint or invariant (especially any enforced by `throw` or assertion) +- Doc callout: any "note", "warning", "caution", "important", "avoid", "do not" +- Dual API: any place the library has two ways to do the same thing (old/new, + verbose/shorthand, lower-level/higher-level) +- Environment branch: any place behavior depends on SSR/CSR, dev/prod, + framework, bundler, or config flag +- Type gap: any type documented as accepting X but source shows X | Y or + rejects a subtype of X +- Source assertion: any `if (!x) throw`, `invariant()`, or `assert()` with + the error message text +- Issue/discussion pattern: any recurring confusion, workaround, or + misunderstanding surfaced from GitHub issues or discussions — note the + issue/discussion URL, the core misunderstanding, and whether it's + resolved or still active + +### What to extract from migration guides specifically + +For each breaking change between major versions: + +``` +Old pattern: [code that agents trained on older versions will produce] +New pattern: [current correct code] +What changed: [one sentence — the specific mechanism] +Version boundary: [e.g. "v4 → v5"] +``` + +These become high-priority failure modes. + +### 3a — Group concepts into domains + +Move concept inventory items into groups. Two items belong together when: + +- A developer reasons about them together when solving a problem +- Solving one correctly requires understanding how the other works +- They share a lifecycle, configuration scope, or architectural tradeoff +- Getting one wrong tends to produce bugs in the other + +Let library complexity drive the domain count — a focused library may need +only 2–3 domains, while a large framework may need 7+. Validate by asking: +"Would a developer working on a single feature need to load skills from +multiple domains? If so, merge those domains." These are conceptual +groupings, not the final skills. + +Do not create a group for: + +- A single hook, function, or class +- A single doc or reference page +- "Miscellaneous", "Advanced", or "Other" +- Configuration knobs that only affect another group's behavior + +Name each domain as work being performed, not what the library provides. + +**Validation step:** After grouping, check each domain by asking: +"Would a developer working on a single feature need to load skills from +multiple domains?" If yes, merge those domains. Group by developer tasks +(what they're trying to accomplish), not by architecture (how the library +is organized internally). For example, prefer "writing data" over +"producer lifecycle" — the former matches a developer's intent, the latter +matches the codebase structure. + +### 3b — Map domains × tasks → skills + +Merge your conceptual domains with the maintainer's task list from +Phase 2. Each skill should match a specific developer moment while +carrying the conceptual depth of its parent domain(s). + +A skill is well-shaped when: + +- A developer would ask for it by name ("help me set up sync") +- It covers enough for the agent to complete the task end-to-end +- It doesn't require loading 3 other skills to be useful + +Some domains produce multiple skills (a broad domain like "data access" +might yield "live-queries", "mutations", "offline-sync"). Some tasks +span domains (a "go-live" checklist touches security, performance, and +configuration). Both are fine. + +Also consider: + +- **Lifecycle/journey skills** — if the library's docs include a + quickstart guide, go-to-production checklist, or migration path, + suggest these as standalone skills. Don't force them if the docs + don't have the material. +- **Composition skills** — when peer deps or examples show consistent + co-usage with another library, output a full skill for the + integration, not a footnote on a domain. + +### 3c — Flag subsystems within skills + +Check each skill area for internal diversity. A skill may be +conceptually unified but contain multiple independent subsystems with +distinct config interfaces — for example, 5 sync adapters that all +solve "connectivity" but each with unique setup, options, and failure +modes. + +For each skill, ask: "Does this cover 3+ backends, adapters, drivers, +or providers with distinct configuration surfaces?" If yes, list them +as `subsystems`. These tell the skill-tree-generator to produce +per-subsystem reference files. + +Also flag dense API surfaces — if a topic has >10 distinct operators, +option shapes, or patterns (e.g. query operators, schema validation +rules), note it as a `reference_candidates` entry. + +### 3d — Extract failure modes + +For each skill, extract failure modes that pass all three tests: + +- **Plausible** — An agent would generate this because it looks correct + based on the library's design, a similar API, or an older version +- **Silent** — No immediate crash; fails at runtime or under specific conditions +- **Grounded** — Traceable to a specific doc page, source location, or issue + +**Where to find them:** + +| Source | What to extract | +| -------------------- | -------------------------------------------------------------------- | +| Migration guides | Every breaking change → old pattern is the wrong code | +| Doc callouts | Any "note", "warning", "avoid" with surrounding context | +| Source assertions | `throw` and `invariant()` messages describe the failure | +| Default values | Undocumented or surprising defaults that cause wrong behavior | +| Type precision | Source type more restrictive than docs imply | +| Environment branches | `typeof window`, SSR flags, `NODE_ENV` — behavior differs silently | +| GitHub issues | Recurring bug reports with workarounds → wrong/correct code pairs | +| GitHub discussions | "How do I…" threads with non-obvious answers → missing skill content | + +Target 3 failure modes per skill minimum. Complex skills target 5–6. + +**Code patterns.** Every failure mode should include `wrong_pattern` and +`correct_pattern` fields with short code snippets (3–10 lines each). +The wrong pattern is what an agent would generate; the correct pattern +is the fix. These feed directly into SKILL.md Common Mistakes sections +as wrong/correct code pairs. If the failure mode is purely conceptual +(e.g. an architectural choice) rather than a code pattern, omit both +fields and explain in `mechanism` instead. + +**Cross-skill failure modes.** Some failure modes belong to multiple +skills. A developer doing SSR work and a developer doing state management +both need to know about "stale state during hydration" — they load +different skills but need the same advice. When a failure mode spans +skills, list all relevant skill slugs in its `skills` field. The +skill-tree-generator will write it into every corresponding SKILL file. + +List a cross-skill failure mode once, under its primary skill. Set +the `skills` field to all skill slugs it applies to. Do not duplicate +the entry in the YAML — the skill-tree-generator handles duplication +into multiple SKILL files at generation time. + +### 3e — Identify cross-skill tensions + +Look for places where design forces between skills conflict. A tension +is not a failure mode — it's a structural pull where optimizing for one +task makes another harder. Examples: + +- "Getting-started simplicity conflicts with production operational safety" +- "Type-safety strictness conflicts with rapid prototyping flexibility" +- "SSR correctness requires patterns that hurt client-side performance" + +Tensions are where agents fail most because they optimize for one task +without seeing the tradeoff. Each tension should name the skills in +conflict, describe the pull, and state what an agent gets wrong when it +only considers one side. + +Target 2–4 tensions. If you find none, the skills may be too isolated — +revisit whether you're missing cross-connections. + +### 3f — Map cross-references + +Beyond tensions (conflicts) and shared failure modes, identify skills +that illuminate each other without conflicting. A cross-reference means: +"an agent loading skill A would produce better code if it knew about +skill B." These become "See also" pointers in the generated SKILL.md +files. + +For each pair, note: + +- Which skill references which (can be bidirectional) +- Why awareness of the other skill improves output + +Examples: + +- A quickstart skill references the security checklist ("after setup, audit") +- A state management skill references an SSR skill ("state hydration + requires understanding SSR lifecycle") +- A data writing skill references a data reading skill ("writes affect + how queries invalidate") + +Output these in the `cross_references` section of domain_map.yaml. + +### 3g — Identify gaps + +For each skill, explicitly list what you could NOT determine from docs +and source alone. These become interview questions in Phase 4. + +Common gaps: + +- "Docs describe X but don't explain when you'd choose X over Y" +- "Migration guide mentions this changed but doesn't say what the old + behavior was" +- "Source has an assertion here but no doc explains what triggers it" +- "GitHub issues show confusion about X but docs don't address it" +- "I found two patterns for doing X — unclear which is current/preferred" + +### 3h — Discover composition targets + +Scan `package.json` for peer dependencies, optional dependencies, and +`peerDependenciesMeta`. Scan example directories and integration tests +for import patterns. For each frequently co-used library, log: + +- Library name and which features interact +- Whether it's a required or optional integration +- Any example code showing the integration pattern + +These become targeted composition questions in Phase 4e. + +### 3i — Produce the draft + +Write the full `domain_map.yaml` (format in Output Artifacts below) with +a `status: draft` field. Flag every gap in the `gaps` section. + +Present the draft to the maintainer before starting Phase 4: + +> "I've read the docs and source for [library] and produced a draft with +> [N] skills and [M] failure modes. I've flagged [K] specific gaps where +> I need your input." + +Include the full draft domain_map.yaml in your message so the maintainer +can review it. Also include a checklist of all docs files you read. + +**── STOP ── Do not proceed to Phase 4 until the maintainer has +reviewed the draft and responded. Their feedback on the draft informs +the detail interview questions.** + +--- + +## Phase 4 — Detail interview (interactive — requires maintainer) + +You have the maintainer's task map and a deep read. The interview now +fills gaps, validates your understanding, and surfaces implicit knowledge. + +You must ask the questions below to the maintainer and wait for their +responses. Do not infer answers from documentation or source code — +even for gaps you think you can answer from your reading. + +### Rules for Phase 4 + +1. One topic per message for open-ended questions. You may batch 2–3 + yes/no or short-confirmation questions together. +2. Ask each question as written (you may adapt phrasing to context, but + keep questions open-ended — never convert to multiple-choice). +3. Each question must reference something specific from your reading. +4. Wait for the maintainer's response after each question before asking + the next. +5. If the maintainer gives a short answer, probe deeper before moving on. +6. Take notes silently. Do not summarize back unless asked. + +### 4a — Draft review (2–3 questions) + +Start by confirming or correcting your skill list and failure modes: + +> "Here's the skill list I've built from our earlier conversation plus +> the deep read: [list skills with brief descriptions]. Does this still +> match your thinking? Anything to add, remove, or rename?" + +Follow up on any corrections. Then: + +> "I identified [M] failure modes from the docs and migration guides. Are +> there important ones I missed — especially patterns that look correct +> but fail silently?" + +### 4b — Gap-targeted questions (3–8 questions) + +For each gap flagged in Phase 3g, ask a specific question. These are not +generic — they reference what you found: + +**Instead of:** "What do developers get wrong?" +**Ask:** "I noticed the migration guide from v4 to v5 changed how [X] works, +but the docs don't show the old pattern. Do agents still commonly generate +the v4 pattern? What does it look like?" + +**Instead of:** "Are there surprising interactions?" +**Ask:** "The source throws an invariant error if [X] is called before [Y], +but the docs don't mention ordering. How often do developers hit this?" + +**Instead of:** "What's different in SSR vs client?" +**Ask:** "I found a `typeof window` check in [file] that changes behavior +for [feature]. What goes wrong when developers test only in the browser +and deploy with SSR?" + +Adapt from this bank of gap-targeted question templates: + +- "I found two patterns for [X] in the docs — [pattern A] and [pattern B]. + Which is current, and does the old one still work?" +- "The source defaults [config option] to [value], which seems surprising + for [reason]. Is this intentional? Do developers need to override it?" +- "GitHub issues show [N] reports of confusion about [X]. What's the + underlying misunderstanding?" +- "I couldn't find docs for how [feature A] interacts with [feature B]. + What should an agent know about using them together?" +- "The API reference shows [type signature], but the guide examples use + a different shape. Which is accurate?" +- "I found [N] GitHub issues/discussions where developers struggled with + [X]. The common workaround seems to be [Y] — is that the recommended + approach, or is there a better pattern that should be documented?" +- "GitHub discussions show developers repeatedly asking how to combine + [feature A] with [feature B]. Is there an intended integration pattern, + or is this a gap in the current API?" + +### 4c — AI-agent-specific failure modes (2–4 questions) + +These target mistakes that AI coding agents make but human developers +typically don't. Agent-specific failures are often the highest-value +findings — in testing, maintainer answers to these questions produced +the most critical failure modes. + +- "What mistakes would an AI coding agent make that a human developer + wouldn't? Think about: hallucinating APIs that don't exist, defaulting + to language primitives instead of library abstractions, choosing the + wrong adapter or integration path." +- "When an agent generates code using your library, what's the first + thing you'd check? What pattern would make you immediately say + 'an AI wrote this'?" +- "Are there parts of your API where the naming or design is misleading + enough that an agent with no prior context would pick the wrong + approach? What would it pick, and what should it pick instead?" +- "Are there features where the docs are comprehensive for human + developers but would still mislead an agent? For example, features + that require understanding unstated context, or where the 'obvious' + approach from reading the API surface is wrong." + +### 4d — Implicit knowledge extraction (3–5 questions) + +These surface knowledge that doesn't appear in any docs: + +- "What does a senior developer using your library know that a mid-level + developer doesn't — something that isn't written down anywhere?" +- "Are there patterns that work fine for prototyping but are dangerous + in production? What makes them dangerous?" +- "What question do you answer most often in Discord or GitHub issues + that the docs technically cover but people still miss?" +- "Is there anything you'd change about the API design if you could break + backwards compatibility? What's the current workaround?" + +### 4e — Composition questions (if library interacts with others) + +Use what you discovered in Phase 3h. For each integration target +identified from peer dependencies and example code, ask targeted +questions: + +- "I see [library] is a peer dependency and [N] examples import it + alongside yours. What's the most common integration mistake?" +- "When developers use [your library] with [other library], are there + patterns that only matter when both are present?" +- "I found [specific integration pattern] in the examples. Is this the + recommended approach, or is there a better way that isn't documented?" + +--- + +## Phase 5 — Finalize artifacts + +Merge interview findings into the draft. For each interview answer: + +1. If it confirms a skill or failure mode — no action needed +2. If it corrects something — update the map +3. If it adds a new failure mode — add it with source "maintainer interview" +4. If it reveals a new skill — add it +5. If it fills a gap — remove from gaps section + +Validate the domain_map.yaml by parsing it with a YAML parser. Check for +duplicate keys, invalid syntax, and structural correctness. Fix any issues +before presenting the final artifact. + +Update `status: draft` to `status: reviewed`. + +--- + +## Output artifacts + +If the maintainer uses a custom skills root, replace `skills/` in the paths +below with their chosen directory. + +**Monorepo layout:** For monorepos, domain map artifacts go at the REPO ROOT +(e.g. `_artifacts/domain_map.yaml`) since they describe the whole library. +Skills are generated per-package later by the tree-generator and generate-skill +steps. + +### 1. skills/\_artifacts/domain_map.yaml + +```yaml +# domain_map.yaml +# Generated by skill-domain-discovery +# Library: [name] +# Version: [version this map targets] +# Date: [ISO date] +# Status: [draft | reviewed] + +library: + name: '[package-name]' + version: '[version]' + repository: '[repo URL]' + description: '[one line]' + primary_framework: '[React | Vue | Svelte | framework-agnostic]' + +domains: + - name: '[work-oriented domain name]' + slug: '[kebab-case]' + description: '[conceptual grouping — what a developer is reasoning about]' + +skills: + - name: '[task-focused skill name]' + slug: '[kebab-case]' + domain: '[parent domain slug]' + description: '[what a developer is doing — matches a specific task/moment]' + type: '[core | framework | lifecycle | composition]' + packages: # required for monorepo; omit for single-package libraries + - '[primary package name]' + - '[secondary package name, if skill spans multiple packages]' + covers: + - '[API/hook/concept 1]' + - '[API/hook/concept 2]' + tasks: + - '[example task 1]' + - '[example task 2]' + - '[example task 3]' + subsystems: # omit if skill has no independent subsystems + - name: '[adapter/backend name]' + package: '[npm package if separate]' + config_surface: '[brief description of unique config]' + reference_candidates: # omit if no dense API surfaces + - topic: '[e.g. query operators, schema validation]' + reason: '[e.g. >10 distinct operators with signatures]' + failure_modes: + - mistake: '[5-10 word phrase]' + mechanism: '[one sentence]' + wrong_pattern: | # the code an agent would incorrectly generate + [short code snippet showing the mistake] + correct_pattern: | # the code that should be generated instead + [short code snippet showing the fix] + source: '[doc page, source file, issue link, or maintainer interview]' + priority: '[CRITICAL | HIGH | MEDIUM]' + status: '[active | fixed-but-legacy-risk | removed]' + version_context: "[e.g. 'Fixed in v5.2 but agents trained on older code still generate this']" + skills: ['[this-skill-slug]'] # list all skills this belongs to; omit if single-skill + compositions: + - library: '[other library name]' + skill: '[composition skill name if applicable]' + +tensions: + - name: '[short phrase describing the pull]' + skills: ['[skill-slug-a]', '[skill-slug-b]'] + description: '[what conflicts — one sentence]' + implication: '[what an agent gets wrong when it only considers one side]' + +cross_references: + - from: '[skill-slug]' + to: '[skill-slug]' + reason: '[why loading one skill benefits from awareness of the other]' + +gaps: + - skill: '[skill slug]' + question: '[what still needs input]' + context: '[why this matters]' + status: '[open | resolved]' +``` + +### 2. skills/\_artifacts/skill_spec.md + +A human-readable companion document. Follow this structure: + +```markdown +# [Library Name] — Skill Spec + +[2–3 sentences: what this library is, what problem it solves. Factual, +not promotional.] + +## Domains + +| Domain | Description | Skills | +| ------ | --------------------- | ----------------------- | +| [name] | [conceptual grouping] | [skill-1, skill-2, ...] | + +## Skill Inventory + +| Skill | Type | Domain | What it covers | Failure modes | +| ------ | -------------------------------------- | -------- | -------------- | ------------- | +| [name] | [core/framework/lifecycle/composition] | [domain] | [list] | [count] | + +## Failure Mode Inventory + +### [Skill name] ([count] failure modes) + +| # | Mistake | Priority | Source | Cross-skill? | +| --- | -------- | -------- | ---------------------- | ------------------------ | +| 1 | [phrase] | CRITICAL | [doc/source/interview] | [other skill slugs or —] | + +[Repeat table for each skill.] + +## Tensions + +| Tension | Skills | Agent implication | +| -------------- | ------------------- | ----------------------- | +| [short phrase] | [slug-a] ↔ [slug-b] | [what agents get wrong] | + +## Cross-References + +| From | To | Reason | +| ------ | ------ | ----------------------------------------- | +| [slug] | [slug] | [why awareness of one improves the other] | + +## Subsystems & Reference Candidates + +| Skill | Subsystems | Reference candidates | +| ------ | ------------------------------ | -------------------------- | +| [slug] | [adapter1, adapter2, ...] or — | [topic needing depth] or — | + +## Remaining Gaps + +| Skill | Question | Status | +| ------ | ------------------------ | ------ | +| [slug] | [what still needs input] | open | + +[Omit this section if all gaps were resolved in the interview.] + +## Recommended Skill File Structure + +- **Core skills:** [list which skills are framework-agnostic] +- **Framework skills:** [list per-framework skills needed] +- **Lifecycle skills:** [list journey/lifecycle skills if applicable] +- **Composition skills:** [list integration seams needing composition skills] +- **Reference files:** [list skills needing references/ based on subsystems + or dense API surfaces] + +## Composition Opportunities + +| Library | Integration points | Composition skill needed? | +| ------- | ------------------ | ----------------------------- | +| [name] | [what interacts] | [yes/no — if yes, skill name] | +``` + +--- + +## Constraints + +| Check | Rule | +| ------------------------------------- | -------------------------------------------------------------------------- | +| Quick scan before interview | Never interview without at least reading README and package structure | +| High-level interview before deep read | The maintainer's task map informs what you read deeply | +| **Interview phases are interactive** | Phases 2 and 4 require sending questions to the maintainer and waiting | +| **Docs are not a substitute** | Documentation cannot replace maintainer answers — even comprehensive docs | +| **Open-ended questions stay open** | Never convert interview questions to multiple-choice or yes/no | +| **Minimum question counts enforced** | Each sub-section's minimum count must be met; zero questions = violation | +| **STOP gates are mandatory** | Do not proceed past a STOP gate without maintainer response | +| Batch only confirmations | Yes/no questions may batch 2–3; open-ended questions get their own message | +| Questions reference findings | No generic questions — cite what you found | +| Skills are task-focused | Each skill matches a developer moment, not a conceptual area | +| 3+ failure modes per skill | Complex skills target 5–6 | +| Every failure mode sourced | Doc page, source file, issue link, or maintainer interview | +| Gaps are explicit | Unknown areas flagged, not guessed | +| No marketing prose | Library description is factual, not promotional | +| domain_map.yaml is valid YAML | Parseable by any YAML parser | +| Draft before detail interview | Present draft for review before Phase 4 | +| **Draft reviewed before Phase 4** | Maintainer must acknowledge or respond to draft before detail interview | +| Agent-specific failures probed | Always ask AI-agent-specific questions in Phase 4c | +| Compositions discovered from code | Scan peer deps and examples before asking composition questions | +| Cross-skill failure modes tagged | Failure modes spanning skills list all relevant slugs | +| Tensions identified | 2–4 cross-skill tensions; if none found, revisit skill boundaries | +| Subsystems flagged | Skills with 3+ adapters/backends list them as subsystems | +| Dense surfaces flagged | Topics with >10 patterns noted as reference_candidates | +| Lifecycle skills considered | Suggest journey skills when docs have the material | +| Cross-references mapped | Skills that illuminate each other get "See also" pointers | +| **All docs files read** | List docs directory contents and read every narrative file — no sampling | + +--- + +## Cross-model compatibility notes + +This skill is designed to produce consistent results across Claude, GPT-4+, +Gemini, and open-source models. To achieve this: + +- All instructions use imperative sentences, not suggestions +- Interview phases use explicit STOP gates to prevent models from + continuing autonomously past interactive checkpoints +- Hard rules at the top override any model tendency to rationalize + skipping interactive phases when documentation is available +- Open-ended questions are explicitly protected from conversion to + multiple-choice or confirmation prompts, which models default to + when they have enough context to pre-populate answers +- Output formats use YAML (universally parsed) and Markdown tables + (universally rendered) +- Examples use concrete values, not placeholders like "[your value here]" +- Section boundaries use Markdown headers (##) for navigation and --- for + phase separation +- No model-specific features (no XML tags in output, no tool_use assumptions) diff --git a/packages/intent/meta/feedback-collection/SKILL.md b/packages/intent/meta/feedback-collection/SKILL.md index 1684da8..be561de 100644 --- a/packages/intent/meta/feedback-collection/SKILL.md +++ b/packages/intent/meta/feedback-collection/SKILL.md @@ -1,234 +1,234 @@ ---- -name: skill-feedback-collection -description: > - Collect structured feedback about skill usage after completing a coding task. - Activate at the end of any session where one or more SKILL.md files were - loaded. Captures agent signals (gaps, errors, corrections, human interventions) - and brief human input, then submits directly via gh CLI or provides manual - submission instructions. -metadata: - version: '2.0' - category: meta-tooling ---- - -# Skill Feedback Collection - -Run this at the end of any session where you loaded one or more SKILL.md files. -The goal is to capture what worked, what didn't, and what was missing — so skill -maintainers can improve future versions. - -This skill also covers **meta-skill feedback** — feedback about the scaffolding -process itself. When invoked after running domain-discovery, tree-generator, and -generate-skill, treat those three meta skills as the "skills" being evaluated. -Capture what worked and what didn't in each scaffolding phase so the meta skills -can be improved. - ---- - -## Phase 1 — Automated Signal Collection - -Review your own session transcript. No human interaction needed yet. - -### 1a: Skills inventory - -Before analyzing gaps and errors, inventory all skills that were available -during the session: - -- **Loaded and used:** Skills you read and actively followed. -- **Available but not loaded:** Skills that were installed (discoverable via - `intent list`) but you never read. This is important — many issues stem from - the agent not loading the right skill, not from the skill itself being wrong. - -### 1b: Gap detection - -Identify moments where the skill was silent and you had to bridge the gap -yourself — via code reading, search, trial-and-error, or general knowledge. - -For each gap, note: - -- What you needed to do -- What the skill should have told you -- How you solved it (code reading, web search, guessing) - -### 1c: Error/correction tracking - -Identify moments where the skill prescribed an approach that produced an error. - -For each error, note: - -- What the skill said to do -- The error or incorrect behavior that resulted -- The fix you applied - -### 1d: Human intervention events - -Identify moments where the human clarified, corrected, or overrode your approach. - -For each intervention, note: - -- What you were doing when the human intervened -- What the human said or changed -- Whether the skill could have prevented this - -### 1e: Step duration anomalies - -Identify steps that consumed disproportionate effort compared to their apparent -complexity. These signal that the skill should provide a template, snippet, or -more detailed guidance. - ---- - -## Phase 2 — Human Interview - -Ask the human up to 4 questions. Keep it brief — skip questions if the session -already provided clear answers. Respect if they decline. - -1. "Was anything unclear about what was happening during the task?" -2. "Did anything feel frustrating or take longer than expected?" -3. "Were you uncertain about the output quality at any point?" -4. "Anything you'd want done differently next time?" - -Derive `userRating` from overall sentiment: - -- Mostly positive → `good` -- Mixed signals → `mixed` -- Mostly negative → `bad` - -If the human gives an explicit rating, use that instead. - ---- - -## Phase 3 — Build the Feedback - -Write one Markdown feedback file per skill used. Only include skills that were -actually used during the session — skip any that were loaded but never -referenced. - -### Template - -```markdown -# Skill Feedback: [skill name from SKILL.md frontmatter] - -**Package:** [npm package name that contains the skill] -**Skill version:** [metadata.version or library_version from frontmatter] -**Rating:** [good | mixed | bad] - -## Task - -[one-sentence summary of what the human asked you to do] - -## Skills Inventory - -**Loaded and used:** - -- [list each skill the agent read and actively followed during the session] - -**Available but not loaded:** - -- [list skills that were installed/available but the agent never read] - -## What Worked - -[patterns/instructions from the skill that were accurate and helpful] - -## What Failed - -[from 1c — skill instructions that produced errors] - -## Missing - -[from 1b — gaps where the skill should have covered] - -## Self-Corrections - -[from 1c fixes + 1d human interventions, combined] - -## User Comments - -[optional — direct quotes or paraphrased human input from Phase 2] -``` - -### Field derivation guide - -| Field | Source | -| ---------------- | ------------------------------------------------------------------ | -| Skill name | Frontmatter `name` field of the SKILL.md you loaded | -| Package | The npm package the skill lives in (e.g. `@tanstack/query-intent`) | -| Skill version | Frontmatter `metadata.version` or `library_version` | -| Task | Summarize the human's original request in one sentence | -| Skills Inventory | Which skills were loaded vs. available but not loaded (see below) | -| What Worked | List skill sections/patterns that were correct and useful | -| What Failed | From 1c — skill instructions that produced errors | -| Missing | From 1b — gaps where the skill was silent | -| Self-Corrections | From 1c fixes + 1d human interventions, combined | -| Rating | From Phase 2 sentiment analysis or explicit rating | -| User Comments | From Phase 2 answers, keep brief | - ---- - -## Phase 4 — Submit - -Determine the target repo from the skill's package. The repo is typically -derivable from the `repository` field in the package's `package.json`, or -from the `sources` field in the SKILL.md frontmatter. - -### Link to existing issues/discussions - -Before creating a new issue, search the target repo for existing issues or -discussions that match the feedback. Use `gh search issues` or the GitHub -web search with keywords from the "What Failed" and "Missing" sections. - -- If an **open issue** already describes the same problem, comment on it - with the feedback instead of creating a duplicate. Reference the skill - name and version in your comment. -- If a **closed issue** describes a problem the skill still gets wrong - (regression or stale skill content), reference the closed issue in the - new feedback issue body: `Related to #[number] — this was fixed in the -library but the skill still describes the old behavior.` -- If a **discussion thread** covers the same topic, link to it in the - feedback issue body so maintainers can see the community context. - -This prevents duplicate issues and gives maintainers richer context for -improving skills. - -### Privacy check - -Before submitting, determine whether the user's project is public or private. -Check with `gh repo view --json visibility` or look for a `private` field in -the project's `package.json`. If you can't determine visibility, assume private. - -**Private repos:** Feedback is submitted to a public issue tracker, so it must -not contain project-specific details. Before submission: - -1. Strip any project-specific code, file paths, internal API names, service - URLs, or business logic from all fields -2. Rewrite the "Task" field to describe the _type_ of task generically - (e.g. "set up authenticated data fetching" not "set up auth for our - internal billing API at api.acme.corp/billing") -3. Rewrite "What Failed" and "Missing" entries to reference only the - skill's own APIs and patterns, not the user's code -4. Show the sanitized feedback to the user and ask them to confirm it's - safe to submit before proceeding - -**Public repos:** No sanitization needed. Proceed directly to submission. - -### If `gh` CLI is available - -Submit directly as a GitHub issue: - -```bash -gh issue create --repo [owner/repo] --title "Skill Feedback: [skill-name] ([rating])" --label "skill:[skill-name]" --body-file intent-feedback.md -``` - -If the label doesn't exist, omit the `--label` flag — don't let a missing -label block submission. - -If submission succeeds, delete the feedback file. - -### If `gh` CLI is not available - -Tell the human: - -> "I've written skill feedback to `intent-feedback.md`. To submit it, -> open an issue at https://github.com/[owner/repo]/issues and paste the -> contents." +--- +name: skill-feedback-collection +description: > + Collect structured feedback about skill usage after completing a coding task. + Activate at the end of any session where one or more SKILL.md files were + loaded. Captures agent signals (gaps, errors, corrections, human interventions) + and brief human input, then submits directly via gh CLI or provides manual + submission instructions. +metadata: + version: '2.0' + category: meta-tooling +--- + +# Skill Feedback Collection + +Run this at the end of any session where you loaded one or more SKILL.md files. +The goal is to capture what worked, what didn't, and what was missing — so skill +maintainers can improve future versions. + +This skill also covers **meta-skill feedback** — feedback about the scaffolding +process itself. When invoked after running domain-discovery, tree-generator, and +generate-skill, treat those three meta skills as the "skills" being evaluated. +Capture what worked and what didn't in each scaffolding phase so the meta skills +can be improved. + +--- + +## Phase 1 — Automated Signal Collection + +Review your own session transcript. No human interaction needed yet. + +### 1a: Skills inventory + +Before analyzing gaps and errors, inventory all skills that were available +during the session: + +- **Loaded and used:** Skills you read and actively followed. +- **Available but not loaded:** Skills that were installed (discoverable via + `intent list`) but you never read. This is important — many issues stem from + the agent not loading the right skill, not from the skill itself being wrong. + +### 1b: Gap detection + +Identify moments where the skill was silent and you had to bridge the gap +yourself — via code reading, search, trial-and-error, or general knowledge. + +For each gap, note: + +- What you needed to do +- What the skill should have told you +- How you solved it (code reading, web search, guessing) + +### 1c: Error/correction tracking + +Identify moments where the skill prescribed an approach that produced an error. + +For each error, note: + +- What the skill said to do +- The error or incorrect behavior that resulted +- The fix you applied + +### 1d: Human intervention events + +Identify moments where the human clarified, corrected, or overrode your approach. + +For each intervention, note: + +- What you were doing when the human intervened +- What the human said or changed +- Whether the skill could have prevented this + +### 1e: Step duration anomalies + +Identify steps that consumed disproportionate effort compared to their apparent +complexity. These signal that the skill should provide a template, snippet, or +more detailed guidance. + +--- + +## Phase 2 — Human Interview + +Ask the human up to 4 questions. Keep it brief — skip questions if the session +already provided clear answers. Respect if they decline. + +1. "Was anything unclear about what was happening during the task?" +2. "Did anything feel frustrating or take longer than expected?" +3. "Were you uncertain about the output quality at any point?" +4. "Anything you'd want done differently next time?" + +Derive `userRating` from overall sentiment: + +- Mostly positive → `good` +- Mixed signals → `mixed` +- Mostly negative → `bad` + +If the human gives an explicit rating, use that instead. + +--- + +## Phase 3 — Build the Feedback + +Write one Markdown feedback file per skill used. Only include skills that were +actually used during the session — skip any that were loaded but never +referenced. + +### Template + +```markdown +# Skill Feedback: [skill name from SKILL.md frontmatter] + +**Package:** [npm package name that contains the skill] +**Skill version:** [metadata.version or library_version from frontmatter] +**Rating:** [good | mixed | bad] + +## Task + +[one-sentence summary of what the human asked you to do] + +## Skills Inventory + +**Loaded and used:** + +- [list each skill the agent read and actively followed during the session] + +**Available but not loaded:** + +- [list skills that were installed/available but the agent never read] + +## What Worked + +[patterns/instructions from the skill that were accurate and helpful] + +## What Failed + +[from 1c — skill instructions that produced errors] + +## Missing + +[from 1b — gaps where the skill should have covered] + +## Self-Corrections + +[from 1c fixes + 1d human interventions, combined] + +## User Comments + +[optional — direct quotes or paraphrased human input from Phase 2] +``` + +### Field derivation guide + +| Field | Source | +| ---------------- | ------------------------------------------------------------------ | +| Skill name | Frontmatter `name` field of the SKILL.md you loaded | +| Package | The npm package the skill lives in (e.g. `@tanstack/query-intent`) | +| Skill version | Frontmatter `metadata.version` or `library_version` | +| Task | Summarize the human's original request in one sentence | +| Skills Inventory | Which skills were loaded vs. available but not loaded (see below) | +| What Worked | List skill sections/patterns that were correct and useful | +| What Failed | From 1c — skill instructions that produced errors | +| Missing | From 1b — gaps where the skill was silent | +| Self-Corrections | From 1c fixes + 1d human interventions, combined | +| Rating | From Phase 2 sentiment analysis or explicit rating | +| User Comments | From Phase 2 answers, keep brief | + +--- + +## Phase 4 — Submit + +Determine the target repo from the skill's package. The repo is typically +derivable from the `repository` field in the package's `package.json`, or +from the `sources` field in the SKILL.md frontmatter. + +### Link to existing issues/discussions + +Before creating a new issue, search the target repo for existing issues or +discussions that match the feedback. Use `gh search issues` or the GitHub +web search with keywords from the "What Failed" and "Missing" sections. + +- If an **open issue** already describes the same problem, comment on it + with the feedback instead of creating a duplicate. Reference the skill + name and version in your comment. +- If a **closed issue** describes a problem the skill still gets wrong + (regression or stale skill content), reference the closed issue in the + new feedback issue body: `Related to #[number] — this was fixed in the +library but the skill still describes the old behavior.` +- If a **discussion thread** covers the same topic, link to it in the + feedback issue body so maintainers can see the community context. + +This prevents duplicate issues and gives maintainers richer context for +improving skills. + +### Privacy check + +Before submitting, determine whether the user's project is public or private. +Check with `gh repo view --json visibility` or look for a `private` field in +the project's `package.json`. If you can't determine visibility, assume private. + +**Private repos:** Feedback is submitted to a public issue tracker, so it must +not contain project-specific details. Before submission: + +1. Strip any project-specific code, file paths, internal API names, service + URLs, or business logic from all fields +2. Rewrite the "Task" field to describe the _type_ of task generically + (e.g. "set up authenticated data fetching" not "set up auth for our + internal billing API at api.acme.corp/billing") +3. Rewrite "What Failed" and "Missing" entries to reference only the + skill's own APIs and patterns, not the user's code +4. Show the sanitized feedback to the user and ask them to confirm it's + safe to submit before proceeding + +**Public repos:** No sanitization needed. Proceed directly to submission. + +### If `gh` CLI is available + +Submit directly as a GitHub issue: + +```bash +gh issue create --repo [owner/repo] --title "Skill Feedback: [skill-name] ([rating])" --label "skill:[skill-name]" --body-file intent-feedback.md +``` + +If the label doesn't exist, omit the `--label` flag — don't let a missing +label block submission. + +If submission succeeds, delete the feedback file. + +### If `gh` CLI is not available + +Tell the human: + +> "I've written skill feedback to `intent-feedback.md`. To submit it, +> open an issue at https://github.com/[owner/repo]/issues and paste the +> contents." diff --git a/packages/intent/meta/generate-skill/SKILL.md b/packages/intent/meta/generate-skill/SKILL.md index d0d7146..656fc8b 100644 --- a/packages/intent/meta/generate-skill/SKILL.md +++ b/packages/intent/meta/generate-skill/SKILL.md @@ -1,453 +1,453 @@ ---- -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. - -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). -``` +--- +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. + +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). +``` diff --git a/packages/intent/meta/templates/workflows/notify-intent.yml b/packages/intent/meta/templates/workflows/notify-intent.yml index cc18685..edc4b5b 100644 --- a/packages/intent/meta/templates/workflows/notify-intent.yml +++ b/packages/intent/meta/templates/workflows/notify-intent.yml @@ -1,52 +1,52 @@ -# notify-intent.yml — Drop this into your library repo's .github/workflows/ -# -# Fires a repository_dispatch event to TanStack/intent whenever docs or -# source files change on merge to main. This triggers the skill staleness -# check workflow in the intent repo. -# -# Requirements: -# - A fine-grained PAT with contents:write on TanStack/intent stored -# as the INTENT_NOTIFY_TOKEN repository secret. -# -# Template variables (replaced by `intent setup`): -# {{PACKAGE_NAME}} — e.g. @tanstack/query -# {{DOCS_PATH}} — e.g. docs/** -# {{SRC_PATH}} — e.g. packages/query-core/src/** - -name: Notify Intent - -on: - push: - branches: [main] - paths: - - '{{DOCS_PATH}}' - - '{{SRC_PATH}}' - -jobs: - notify: - name: Notify TanStack Intent - runs-on: ubuntu-latest - steps: - - name: Checkout - uses: actions/checkout@v4 - with: - fetch-depth: 2 - - - name: Collect changed files - id: changes - run: | - FILES=$(git diff --name-only HEAD~1 HEAD | jq -R -s -c 'split("\n") | map(select(length > 0))') - echo "files=$FILES" >> "$GITHUB_OUTPUT" - - - name: Dispatch to intent repo - uses: peter-evans/repository-dispatch@v3 - with: - token: ${{ secrets.INTENT_NOTIFY_TOKEN }} - repository: TanStack/intent - event-type: skill-check - client-payload: | - { - "package": "{{PACKAGE_NAME}}", - "sha": "${{ github.sha }}", - "changed_files": ${{ steps.changes.outputs.files }} - } +# notify-intent.yml — Drop this into your library repo's .github/workflows/ +# +# Fires a repository_dispatch event to TanStack/intent whenever docs or +# source files change on merge to main. This triggers the skill staleness +# check workflow in the intent repo. +# +# Requirements: +# - A fine-grained PAT with contents:write on TanStack/intent stored +# as the INTENT_NOTIFY_TOKEN repository secret. +# +# Template variables (replaced by `intent setup`): +# {{PACKAGE_NAME}} — e.g. @tanstack/query +# {{DOCS_PATH}} — e.g. docs/** +# {{SRC_PATH}} — e.g. packages/query-core/src/** + +name: Notify Intent + +on: + push: + branches: [main] + paths: + - '{{DOCS_PATH}}' + - '{{SRC_PATH}}' + +jobs: + notify: + name: Notify TanStack Intent + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 2 + + - name: Collect changed files + id: changes + run: | + FILES=$(git diff --name-only HEAD~1 HEAD | jq -R -s -c 'split("\n") | map(select(length > 0))') + echo "files=$FILES" >> "$GITHUB_OUTPUT" + + - name: Dispatch to intent repo + uses: peter-evans/repository-dispatch@v3 + with: + token: ${{ secrets.INTENT_NOTIFY_TOKEN }} + repository: TanStack/intent + event-type: skill-check + client-payload: | + { + "package": "{{PACKAGE_NAME}}", + "sha": "${{ github.sha }}", + "changed_files": ${{ steps.changes.outputs.files }} + } diff --git a/packages/intent/package.json b/packages/intent/package.json index 5fc644b..ebbd44d 100644 --- a/packages/intent/package.json +++ b/packages/intent/package.json @@ -1,40 +1,40 @@ -{ - "name": "@tanstack/intent", - "version": "0.0.17", - "description": "Ship compositional knowledge for AI coding agents alongside your npm packages", - "license": "MIT", - "type": "module", - "repository": { - "type": "git", - "url": "https://github.com/tanstack/intent" - }, - "exports": { - ".": { - "import": "./dist/index.mjs", - "types": "./dist/index.d.mts" - }, - "./intent-library": { - "import": "./dist/intent-library.mjs" - } - }, - "bin": { - "intent": "dist/cli.mjs", - "intent-library": "dist/intent-library.mjs" - }, - "files": [ - "dist", - "meta" - ], - "dependencies": { - "yaml": "^2.7.0" - }, - "devDependencies": { - "tsdown": "^0.19.0" - }, - "scripts": { - "prepack": "pnpm run build", - "build": "tsdown src/index.ts src/cli.ts src/setup.ts src/intent-library.ts src/library-scanner.ts --format esm --dts", - "test:lib": "vitest run", - "test:types": "tsc --noEmit" - } -} +{ + "name": "@tanstack/intent", + "version": "0.0.17", + "description": "Ship compositional knowledge for AI coding agents alongside your npm packages", + "license": "MIT", + "type": "module", + "repository": { + "type": "git", + "url": "https://github.com/tanstack/intent" + }, + "exports": { + ".": { + "import": "./dist/index.mjs", + "types": "./dist/index.d.mts" + }, + "./intent-library": { + "import": "./dist/intent-library.mjs" + } + }, + "bin": { + "intent": "dist/cli.mjs", + "intent-library": "dist/intent-library.mjs" + }, + "files": [ + "dist", + "meta" + ], + "dependencies": { + "yaml": "^2.7.0" + }, + "devDependencies": { + "tsdown": "^0.19.0" + }, + "scripts": { + "prepack": "pnpm run build", + "build": "tsdown src/index.ts src/cli.ts src/setup.ts src/intent-library.ts src/library-scanner.ts --format esm --dts", + "test:lib": "vitest run", + "test:types": "tsc --noEmit" + } +} diff --git a/packages/intent/src/setup.ts b/packages/intent/src/setup.ts index be31874..71e90b1 100644 --- a/packages/intent/src/setup.ts +++ b/packages/intent/src/setup.ts @@ -1,371 +1,371 @@ -import { - existsSync, - mkdirSync, - readFileSync, - readdirSync, - writeFileSync, -} from 'node:fs' -import { join } from 'node:path' - -// --------------------------------------------------------------------------- -// Types -// --------------------------------------------------------------------------- - -export interface AddLibraryBinResult { - shim: string | null - skipped: string | null -} - -export interface EditPackageJsonResult { - added: Array - alreadyPresent: Array -} - -export interface SetupGithubActionsResult { - workflows: Array - skipped: Array -} - -interface TemplateVars { - PACKAGE_NAME: string - REPO: string - DOCS_PATH: string - SRC_PATH: string -} - -// --------------------------------------------------------------------------- -// Variable detection from package.json -// --------------------------------------------------------------------------- - -function detectVars(root: string): TemplateVars { - const pkgPath = join(root, 'package.json') - let pkgJson: Record = {} - try { - pkgJson = JSON.parse(readFileSync(pkgPath, 'utf8')) - } catch (err: unknown) { - const isNotFound = - err && - typeof err === 'object' && - 'code' in err && - (err as NodeJS.ErrnoException).code === 'ENOENT' - if (!isNotFound) { - console.error( - `Warning: could not read ${pkgPath}: ${err instanceof Error ? err.message : err}`, - ) - } - } - - const name = typeof pkgJson.name === 'string' ? pkgJson.name : 'unknown' - const intent = pkgJson.intent as Record | undefined - - const repo = - typeof intent?.repo === 'string' - ? intent.repo - : name.replace(/^@/, '').replace(/\//, '/') - - const docs = typeof intent?.docs === 'string' ? intent.docs : 'docs/' - - // Best-guess src path from common monorepo patterns - const shortName = name.replace(/^@[^/]+\//, '') - let srcPath = `packages/${shortName}/src/**` - if (existsSync(join(root, 'src'))) { - srcPath = 'src/**' - } - - return { - PACKAGE_NAME: name, - REPO: repo, - DOCS_PATH: docs.endsWith('**') ? docs : docs.replace(/\/$/, '') + '/**', - SRC_PATH: srcPath, - } -} - -// --------------------------------------------------------------------------- -// Template variable substitution -// --------------------------------------------------------------------------- - -function applyVars(content: string, vars: TemplateVars): string { - return content - .replace(/\{\{PACKAGE_NAME\}\}/g, vars.PACKAGE_NAME) - .replace(/\{\{REPO\}\}/g, vars.REPO) - .replace(/\{\{DOCS_PATH\}\}/g, vars.DOCS_PATH) - .replace(/\{\{SRC_PATH\}\}/g, vars.SRC_PATH) -} - -// --------------------------------------------------------------------------- -// Copy helpers -// --------------------------------------------------------------------------- - -function copyTemplates( - srcDir: string, - destDir: string, - vars: TemplateVars, -): { copied: Array; skipped: Array } { - const copied: Array = [] - const skipped: Array = [] - - if (!existsSync(srcDir)) return { copied, skipped } - - mkdirSync(destDir, { recursive: true }) - - for (const entry of readdirSync(srcDir)) { - const srcPath = join(srcDir, entry) - const destPath = join(destDir, entry) - - if (existsSync(destPath)) { - skipped.push(destPath) - continue - } - - const content = readFileSync(srcPath, 'utf8') - const substituted = applyVars(content, vars) - writeFileSync(destPath, substituted) - copied.push(destPath) - } - - return { copied, skipped } -} - -// --------------------------------------------------------------------------- -// Shim generation helpers -// --------------------------------------------------------------------------- - -function getShimContent(ext: string): string { - return `#!/usr/bin/env node -// Auto-generated by @tanstack/intent setup -// Exposes the intent end-user CLI for consumers of this library. -// Commit this file, then add to your package.json: -// "bin": { "intent": "./bin/intent.${ext}" } -try { - await import('@tanstack/intent/intent-library') -} catch (e) { - if (e?.code === 'ERR_MODULE_NOT_FOUND' || e?.code === 'MODULE_NOT_FOUND') { - console.error('@tanstack/intent is not installed.') - console.error('') - console.error('Install it as a dev dependency:') - console.error(' npm add -D @tanstack/intent') - console.error('') - console.error('Or run directly:') - console.error(' npx @tanstack/intent@latest list') - process.exit(1) - } - throw e -} -` -} - -function detectShimExtension(root: string): string { - try { - const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) - if (pkg.type === 'module') return 'js' - } catch (err: unknown) { - const isNotFound = - err && - typeof err === 'object' && - 'code' in err && - (err as NodeJS.ErrnoException).code === 'ENOENT' - if (!isNotFound) { - console.error( - `Warning: could not read package.json: ${err instanceof Error ? err.message : err}`, - ) - } - } - return 'mjs' -} - -function findExistingShim(root: string): string | null { - const shimJs = join(root, 'bin', 'intent.js') - if (existsSync(shimJs)) return shimJs - - const shimMjs = join(root, 'bin', 'intent.mjs') - if (existsSync(shimMjs)) return shimMjs - - return null -} - -// --------------------------------------------------------------------------- -// Command: add-library-bin -// --------------------------------------------------------------------------- - -export function runAddLibraryBin(root: string): AddLibraryBinResult { - const result: AddLibraryBinResult = { shim: null, skipped: null } - - const existingShim = findExistingShim(root) - if (existingShim) { - result.skipped = existingShim - console.log(` Already exists: ${existingShim}`) - return result - } - - const ext = detectShimExtension(root) - const shimPath = join(root, 'bin', `intent.${ext}`) - mkdirSync(join(root, 'bin'), { recursive: true }) - writeFileSync(shimPath, getShimContent(ext)) - result.shim = shimPath - - console.log(`✓ Generated intent shim: ${shimPath}`) - console.log( - `\n Run \`npx @tanstack/intent edit-package-json\` to wire package.json.`, - ) - - return result -} - -// --------------------------------------------------------------------------- -// Command: edit-package-json -// --------------------------------------------------------------------------- - -export function runEditPackageJson(root: string): EditPackageJsonResult { - const result: EditPackageJsonResult = { added: [], alreadyPresent: [] } - const pkgPath = join(root, 'package.json') - - if (!existsSync(pkgPath)) { - console.error('No package.json found in ' + root) - process.exitCode = 1 - return result - } - - const raw = readFileSync(pkgPath, 'utf8') - let pkg: Record - try { - pkg = JSON.parse(raw) as Record - } catch (err) { - const detail = err instanceof SyntaxError ? err.message : String(err) - console.error(`Failed to parse ${pkgPath}: ${detail}`) - return result - } - - // Detect indent size from existing file - const indentMatch = raw.match(/^(\s+)"/m) - const indentSize = indentMatch?.[1] ? indentMatch[1].length : 2 - - // --- keywords array --- - if (!Array.isArray(pkg.keywords)) { - pkg.keywords = [] - } - const keywords = pkg.keywords as Array - const requiredKeywords = ['tanstack-intent'] - for (const kw of requiredKeywords) { - if (keywords.includes(kw)) { - result.alreadyPresent.push(`keywords: "${kw}"`) - } else { - keywords.push(kw) - result.added.push(`keywords: "${kw}"`) - } - } - - // --- files array --- - if (!Array.isArray(pkg.files)) { - pkg.files = [] - } - const files = pkg.files as Array - - // In monorepos, _artifacts lives at repo root, not under packages — - // the negation pattern is a no-op and shouldn't be added. - // Detect monorepo by walking up to find a parent package.json with workspaces. - const isMonorepo = (() => { - let dir = join(root, '..') - for (let i = 0; i < 5; i++) { - const parentPkg = join(dir, 'package.json') - if (existsSync(parentPkg)) { - try { - const parent = JSON.parse(readFileSync(parentPkg, 'utf8')) - if (Array.isArray(parent.workspaces) || parent.workspaces?.packages) { - return true - } - } catch {} - return false - } - const next = join(dir, '..') - if (next === dir) break - dir = next - } - return false - })() - const requiredFiles = isMonorepo - ? ['skills', 'bin'] - : ['skills', 'bin', '!skills/_artifacts'] - - for (const entry of requiredFiles) { - if (files.includes(entry)) { - result.alreadyPresent.push(`files: "${entry}"`) - } else { - files.push(entry) - result.added.push(`files: "${entry}"`) - } - } - - // --- bin field --- - const existingShim = findExistingShim(root) - let ext: string - if (existingShim) { - ext = existingShim.endsWith('.mjs') ? 'mjs' : 'js' - } else { - ext = pkg.type === 'module' ? 'js' : 'mjs' - } - const shimRelative = `./bin/intent.${ext}` - - if (typeof pkg.bin === 'object' && pkg.bin !== null) { - const binObj = pkg.bin as Record - if (binObj.intent) { - result.alreadyPresent.push(`bin.intent`) - } else { - binObj.intent = shimRelative - result.added.push(`bin.intent: "${shimRelative}"`) - } - } else if (!pkg.bin) { - pkg.bin = { intent: shimRelative } - result.added.push(`bin.intent: "${shimRelative}"`) - } else if (typeof pkg.bin === 'string') { - // npm string shorthand: "bin": "./cli.js" means { "": "./cli.js" } - const pkgName = - typeof pkg.name === 'string' - ? pkg.name.replace(/^@[^/]+\//, '') - : 'unknown' - pkg.bin = { [pkgName]: pkg.bin, intent: shimRelative } - result.added.push( - `bin.intent: "${shimRelative}" (converted bin from string to object)`, - ) - } - - writeFileSync(pkgPath, JSON.stringify(pkg, null, indentSize) + '\n') - - // Print results - for (const a of result.added) console.log(`✓ Added ${a}`) - for (const a of result.alreadyPresent) console.log(` Already present: ${a}`) - - return result -} - -// --------------------------------------------------------------------------- -// Command: setup-github-actions -// --------------------------------------------------------------------------- - -export function runSetupGithubActions( - root: string, - metaDir: string, -): SetupGithubActionsResult { - const vars = detectVars(root) - const result: SetupGithubActionsResult = { workflows: [], skipped: [] } - - const srcDir = join(metaDir, 'templates', 'workflows') - const destDir = join(root, '.github', 'workflows') - const { copied, skipped } = copyTemplates(srcDir, destDir, vars) - result.workflows = copied - result.skipped = skipped - - for (const f of result.workflows) console.log(`✓ Copied workflow: ${f}`) - for (const f of result.skipped) console.log(` Already exists: ${f}`) - - if (result.workflows.length === 0 && result.skipped.length === 0) { - console.log('No templates directory found. Is @tanstack/intent installed?') - } else if (result.workflows.length > 0) { - console.log(`\nTemplate variables applied:`) - console.log(` Package: ${vars.PACKAGE_NAME}`) - console.log(` Repo: ${vars.REPO}`) - console.log(` Docs: ${vars.DOCS_PATH}`) - console.log(` Src: ${vars.SRC_PATH}`) - } - - return result -} +import { + existsSync, + mkdirSync, + readFileSync, + readdirSync, + writeFileSync, +} from 'node:fs' +import { join } from 'node:path' + +// --------------------------------------------------------------------------- +// Types +// --------------------------------------------------------------------------- + +export interface AddLibraryBinResult { + shim: string | null + skipped: string | null +} + +export interface EditPackageJsonResult { + added: Array + alreadyPresent: Array +} + +export interface SetupGithubActionsResult { + workflows: Array + skipped: Array +} + +interface TemplateVars { + PACKAGE_NAME: string + REPO: string + DOCS_PATH: string + SRC_PATH: string +} + +// --------------------------------------------------------------------------- +// Variable detection from package.json +// --------------------------------------------------------------------------- + +function detectVars(root: string): TemplateVars { + const pkgPath = join(root, 'package.json') + let pkgJson: Record = {} + try { + pkgJson = JSON.parse(readFileSync(pkgPath, 'utf8')) + } catch (err: unknown) { + const isNotFound = + err && + typeof err === 'object' && + 'code' in err && + (err as NodeJS.ErrnoException).code === 'ENOENT' + if (!isNotFound) { + console.error( + `Warning: could not read ${pkgPath}: ${err instanceof Error ? err.message : err}`, + ) + } + } + + const name = typeof pkgJson.name === 'string' ? pkgJson.name : 'unknown' + const intent = pkgJson.intent as Record | undefined + + const repo = + typeof intent?.repo === 'string' + ? intent.repo + : name.replace(/^@/, '').replace(/\//, '/') + + const docs = typeof intent?.docs === 'string' ? intent.docs : 'docs/' + + // Best-guess src path from common monorepo patterns + const shortName = name.replace(/^@[^/]+\//, '') + let srcPath = `packages/${shortName}/src/**` + if (existsSync(join(root, 'src'))) { + srcPath = 'src/**' + } + + return { + PACKAGE_NAME: name, + REPO: repo, + DOCS_PATH: docs.endsWith('**') ? docs : docs.replace(/\/$/, '') + '/**', + SRC_PATH: srcPath, + } +} + +// --------------------------------------------------------------------------- +// Template variable substitution +// --------------------------------------------------------------------------- + +function applyVars(content: string, vars: TemplateVars): string { + return content + .replace(/\{\{PACKAGE_NAME\}\}/g, vars.PACKAGE_NAME) + .replace(/\{\{REPO\}\}/g, vars.REPO) + .replace(/\{\{DOCS_PATH\}\}/g, vars.DOCS_PATH) + .replace(/\{\{SRC_PATH\}\}/g, vars.SRC_PATH) +} + +// --------------------------------------------------------------------------- +// Copy helpers +// --------------------------------------------------------------------------- + +function copyTemplates( + srcDir: string, + destDir: string, + vars: TemplateVars, +): { copied: Array; skipped: Array } { + const copied: Array = [] + const skipped: Array = [] + + if (!existsSync(srcDir)) return { copied, skipped } + + mkdirSync(destDir, { recursive: true }) + + for (const entry of readdirSync(srcDir)) { + const srcPath = join(srcDir, entry) + const destPath = join(destDir, entry) + + if (existsSync(destPath)) { + skipped.push(destPath) + continue + } + + const content = readFileSync(srcPath, 'utf8') + const substituted = applyVars(content, vars) + writeFileSync(destPath, substituted) + copied.push(destPath) + } + + return { copied, skipped } +} + +// --------------------------------------------------------------------------- +// Shim generation helpers +// --------------------------------------------------------------------------- + +function getShimContent(ext: string): string { + return `#!/usr/bin/env node +// Auto-generated by @tanstack/intent setup +// Exposes the intent end-user CLI for consumers of this library. +// Commit this file, then add to your package.json: +// "bin": { "intent": "./bin/intent.${ext}" } +try { + await import('@tanstack/intent/intent-library') +} catch (e) { + if (e?.code === 'ERR_MODULE_NOT_FOUND' || e?.code === 'MODULE_NOT_FOUND') { + console.error('@tanstack/intent is not installed.') + console.error('') + console.error('Install it as a dev dependency:') + console.error(' npm add -D @tanstack/intent') + console.error('') + console.error('Or run directly:') + console.error(' npx @tanstack/intent@latest list') + process.exit(1) + } + throw e +} +` +} + +function detectShimExtension(root: string): string { + try { + const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) + if (pkg.type === 'module') return 'js' + } catch (err: unknown) { + const isNotFound = + err && + typeof err === 'object' && + 'code' in err && + (err as NodeJS.ErrnoException).code === 'ENOENT' + if (!isNotFound) { + console.error( + `Warning: could not read package.json: ${err instanceof Error ? err.message : err}`, + ) + } + } + return 'mjs' +} + +function findExistingShim(root: string): string | null { + const shimJs = join(root, 'bin', 'intent.js') + if (existsSync(shimJs)) return shimJs + + const shimMjs = join(root, 'bin', 'intent.mjs') + if (existsSync(shimMjs)) return shimMjs + + return null +} + +// --------------------------------------------------------------------------- +// Command: add-library-bin +// --------------------------------------------------------------------------- + +export function runAddLibraryBin(root: string): AddLibraryBinResult { + const result: AddLibraryBinResult = { shim: null, skipped: null } + + const existingShim = findExistingShim(root) + if (existingShim) { + result.skipped = existingShim + console.log(` Already exists: ${existingShim}`) + return result + } + + const ext = detectShimExtension(root) + const shimPath = join(root, 'bin', `intent.${ext}`) + mkdirSync(join(root, 'bin'), { recursive: true }) + writeFileSync(shimPath, getShimContent(ext)) + result.shim = shimPath + + console.log(`✓ Generated intent shim: ${shimPath}`) + console.log( + `\n Run \`npx @tanstack/intent edit-package-json\` to wire package.json.`, + ) + + return result +} + +// --------------------------------------------------------------------------- +// Command: edit-package-json +// --------------------------------------------------------------------------- + +export function runEditPackageJson(root: string): EditPackageJsonResult { + const result: EditPackageJsonResult = { added: [], alreadyPresent: [] } + const pkgPath = join(root, 'package.json') + + if (!existsSync(pkgPath)) { + console.error('No package.json found in ' + root) + process.exitCode = 1 + return result + } + + const raw = readFileSync(pkgPath, 'utf8') + let pkg: Record + try { + pkg = JSON.parse(raw) as Record + } catch (err) { + const detail = err instanceof SyntaxError ? err.message : String(err) + console.error(`Failed to parse ${pkgPath}: ${detail}`) + return result + } + + // Detect indent size from existing file + const indentMatch = raw.match(/^(\s+)"/m) + const indentSize = indentMatch?.[1] ? indentMatch[1].length : 2 + + // --- keywords array --- + if (!Array.isArray(pkg.keywords)) { + pkg.keywords = [] + } + const keywords = pkg.keywords as Array + const requiredKeywords = ['tanstack-intent'] + for (const kw of requiredKeywords) { + if (keywords.includes(kw)) { + result.alreadyPresent.push(`keywords: "${kw}"`) + } else { + keywords.push(kw) + result.added.push(`keywords: "${kw}"`) + } + } + + // --- files array --- + if (!Array.isArray(pkg.files)) { + pkg.files = [] + } + const files = pkg.files as Array + + // In monorepos, _artifacts lives at repo root, not under packages — + // the negation pattern is a no-op and shouldn't be added. + // Detect monorepo by walking up to find a parent package.json with workspaces. + const isMonorepo = (() => { + let dir = join(root, '..') + for (let i = 0; i < 5; i++) { + const parentPkg = join(dir, 'package.json') + if (existsSync(parentPkg)) { + try { + const parent = JSON.parse(readFileSync(parentPkg, 'utf8')) + if (Array.isArray(parent.workspaces) || parent.workspaces?.packages) { + return true + } + } catch {} + return false + } + const next = join(dir, '..') + if (next === dir) break + dir = next + } + return false + })() + const requiredFiles = isMonorepo + ? ['skills', 'bin'] + : ['skills', 'bin', '!skills/_artifacts'] + + for (const entry of requiredFiles) { + if (files.includes(entry)) { + result.alreadyPresent.push(`files: "${entry}"`) + } else { + files.push(entry) + result.added.push(`files: "${entry}"`) + } + } + + // --- bin field --- + const existingShim = findExistingShim(root) + let ext: string + if (existingShim) { + ext = existingShim.endsWith('.mjs') ? 'mjs' : 'js' + } else { + ext = pkg.type === 'module' ? 'js' : 'mjs' + } + const shimRelative = `./bin/intent.${ext}` + + if (typeof pkg.bin === 'object' && pkg.bin !== null) { + const binObj = pkg.bin as Record + if (binObj.intent) { + result.alreadyPresent.push(`bin.intent`) + } else { + binObj.intent = shimRelative + result.added.push(`bin.intent: "${shimRelative}"`) + } + } else if (!pkg.bin) { + pkg.bin = { intent: shimRelative } + result.added.push(`bin.intent: "${shimRelative}"`) + } else if (typeof pkg.bin === 'string') { + // npm string shorthand: "bin": "./cli.js" means { "": "./cli.js" } + const pkgName = + typeof pkg.name === 'string' + ? pkg.name.replace(/^@[^/]+\//, '') + : 'unknown' + pkg.bin = { [pkgName]: pkg.bin, intent: shimRelative } + result.added.push( + `bin.intent: "${shimRelative}" (converted bin from string to object)`, + ) + } + + writeFileSync(pkgPath, JSON.stringify(pkg, null, indentSize) + '\n') + + // Print results + for (const a of result.added) console.log(`✓ Added ${a}`) + for (const a of result.alreadyPresent) console.log(` Already present: ${a}`) + + return result +} + +// --------------------------------------------------------------------------- +// Command: setup-github-actions +// --------------------------------------------------------------------------- + +export function runSetupGithubActions( + root: string, + metaDir: string, +): SetupGithubActionsResult { + const vars = detectVars(root) + const result: SetupGithubActionsResult = { workflows: [], skipped: [] } + + const srcDir = join(metaDir, 'templates', 'workflows') + const destDir = join(root, '.github', 'workflows') + const { copied, skipped } = copyTemplates(srcDir, destDir, vars) + result.workflows = copied + result.skipped = skipped + + for (const f of result.workflows) console.log(`✓ Copied workflow: ${f}`) + for (const f of result.skipped) console.log(` Already exists: ${f}`) + + if (result.workflows.length === 0 && result.skipped.length === 0) { + console.log('No templates directory found. Is @tanstack/intent installed?') + } else if (result.workflows.length > 0) { + console.log(`\nTemplate variables applied:`) + console.log(` Package: ${vars.PACKAGE_NAME}`) + console.log(` Repo: ${vars.REPO}`) + console.log(` Docs: ${vars.DOCS_PATH}`) + console.log(` Src: ${vars.SRC_PATH}`) + } + + return result +} From b8d4b51f9dc2efdd192f6eac77e17273bc0b000f Mon Sep 17 00:00:00 2001 From: "autofix-ci[bot]" <114827586+autofix-ci[bot]@users.noreply.github.com> Date: Wed, 11 Mar 2026 18:44:57 +0000 Subject: [PATCH 7/7] ci: apply automated fixes --- .../intent/meta/feedback-collection/SKILL.md | 468 ++++----- packages/intent/meta/generate-skill/SKILL.md | 906 +++++++++--------- .../templates/workflows/notify-intent.yml | 104 +- 3 files changed, 739 insertions(+), 739 deletions(-) diff --git a/packages/intent/meta/feedback-collection/SKILL.md b/packages/intent/meta/feedback-collection/SKILL.md index be561de..1684da8 100644 --- a/packages/intent/meta/feedback-collection/SKILL.md +++ b/packages/intent/meta/feedback-collection/SKILL.md @@ -1,234 +1,234 @@ ---- -name: skill-feedback-collection -description: > - Collect structured feedback about skill usage after completing a coding task. - Activate at the end of any session where one or more SKILL.md files were - loaded. Captures agent signals (gaps, errors, corrections, human interventions) - and brief human input, then submits directly via gh CLI or provides manual - submission instructions. -metadata: - version: '2.0' - category: meta-tooling ---- - -# Skill Feedback Collection - -Run this at the end of any session where you loaded one or more SKILL.md files. -The goal is to capture what worked, what didn't, and what was missing — so skill -maintainers can improve future versions. - -This skill also covers **meta-skill feedback** — feedback about the scaffolding -process itself. When invoked after running domain-discovery, tree-generator, and -generate-skill, treat those three meta skills as the "skills" being evaluated. -Capture what worked and what didn't in each scaffolding phase so the meta skills -can be improved. - ---- - -## Phase 1 — Automated Signal Collection - -Review your own session transcript. No human interaction needed yet. - -### 1a: Skills inventory - -Before analyzing gaps and errors, inventory all skills that were available -during the session: - -- **Loaded and used:** Skills you read and actively followed. -- **Available but not loaded:** Skills that were installed (discoverable via - `intent list`) but you never read. This is important — many issues stem from - the agent not loading the right skill, not from the skill itself being wrong. - -### 1b: Gap detection - -Identify moments where the skill was silent and you had to bridge the gap -yourself — via code reading, search, trial-and-error, or general knowledge. - -For each gap, note: - -- What you needed to do -- What the skill should have told you -- How you solved it (code reading, web search, guessing) - -### 1c: Error/correction tracking - -Identify moments where the skill prescribed an approach that produced an error. - -For each error, note: - -- What the skill said to do -- The error or incorrect behavior that resulted -- The fix you applied - -### 1d: Human intervention events - -Identify moments where the human clarified, corrected, or overrode your approach. - -For each intervention, note: - -- What you were doing when the human intervened -- What the human said or changed -- Whether the skill could have prevented this - -### 1e: Step duration anomalies - -Identify steps that consumed disproportionate effort compared to their apparent -complexity. These signal that the skill should provide a template, snippet, or -more detailed guidance. - ---- - -## Phase 2 — Human Interview - -Ask the human up to 4 questions. Keep it brief — skip questions if the session -already provided clear answers. Respect if they decline. - -1. "Was anything unclear about what was happening during the task?" -2. "Did anything feel frustrating or take longer than expected?" -3. "Were you uncertain about the output quality at any point?" -4. "Anything you'd want done differently next time?" - -Derive `userRating` from overall sentiment: - -- Mostly positive → `good` -- Mixed signals → `mixed` -- Mostly negative → `bad` - -If the human gives an explicit rating, use that instead. - ---- - -## Phase 3 — Build the Feedback - -Write one Markdown feedback file per skill used. Only include skills that were -actually used during the session — skip any that were loaded but never -referenced. - -### Template - -```markdown -# Skill Feedback: [skill name from SKILL.md frontmatter] - -**Package:** [npm package name that contains the skill] -**Skill version:** [metadata.version or library_version from frontmatter] -**Rating:** [good | mixed | bad] - -## Task - -[one-sentence summary of what the human asked you to do] - -## Skills Inventory - -**Loaded and used:** - -- [list each skill the agent read and actively followed during the session] - -**Available but not loaded:** - -- [list skills that were installed/available but the agent never read] - -## What Worked - -[patterns/instructions from the skill that were accurate and helpful] - -## What Failed - -[from 1c — skill instructions that produced errors] - -## Missing - -[from 1b — gaps where the skill should have covered] - -## Self-Corrections - -[from 1c fixes + 1d human interventions, combined] - -## User Comments - -[optional — direct quotes or paraphrased human input from Phase 2] -``` - -### Field derivation guide - -| Field | Source | -| ---------------- | ------------------------------------------------------------------ | -| Skill name | Frontmatter `name` field of the SKILL.md you loaded | -| Package | The npm package the skill lives in (e.g. `@tanstack/query-intent`) | -| Skill version | Frontmatter `metadata.version` or `library_version` | -| Task | Summarize the human's original request in one sentence | -| Skills Inventory | Which skills were loaded vs. available but not loaded (see below) | -| What Worked | List skill sections/patterns that were correct and useful | -| What Failed | From 1c — skill instructions that produced errors | -| Missing | From 1b — gaps where the skill was silent | -| Self-Corrections | From 1c fixes + 1d human interventions, combined | -| Rating | From Phase 2 sentiment analysis or explicit rating | -| User Comments | From Phase 2 answers, keep brief | - ---- - -## Phase 4 — Submit - -Determine the target repo from the skill's package. The repo is typically -derivable from the `repository` field in the package's `package.json`, or -from the `sources` field in the SKILL.md frontmatter. - -### Link to existing issues/discussions - -Before creating a new issue, search the target repo for existing issues or -discussions that match the feedback. Use `gh search issues` or the GitHub -web search with keywords from the "What Failed" and "Missing" sections. - -- If an **open issue** already describes the same problem, comment on it - with the feedback instead of creating a duplicate. Reference the skill - name and version in your comment. -- If a **closed issue** describes a problem the skill still gets wrong - (regression or stale skill content), reference the closed issue in the - new feedback issue body: `Related to #[number] — this was fixed in the -library but the skill still describes the old behavior.` -- If a **discussion thread** covers the same topic, link to it in the - feedback issue body so maintainers can see the community context. - -This prevents duplicate issues and gives maintainers richer context for -improving skills. - -### Privacy check - -Before submitting, determine whether the user's project is public or private. -Check with `gh repo view --json visibility` or look for a `private` field in -the project's `package.json`. If you can't determine visibility, assume private. - -**Private repos:** Feedback is submitted to a public issue tracker, so it must -not contain project-specific details. Before submission: - -1. Strip any project-specific code, file paths, internal API names, service - URLs, or business logic from all fields -2. Rewrite the "Task" field to describe the _type_ of task generically - (e.g. "set up authenticated data fetching" not "set up auth for our - internal billing API at api.acme.corp/billing") -3. Rewrite "What Failed" and "Missing" entries to reference only the - skill's own APIs and patterns, not the user's code -4. Show the sanitized feedback to the user and ask them to confirm it's - safe to submit before proceeding - -**Public repos:** No sanitization needed. Proceed directly to submission. - -### If `gh` CLI is available - -Submit directly as a GitHub issue: - -```bash -gh issue create --repo [owner/repo] --title "Skill Feedback: [skill-name] ([rating])" --label "skill:[skill-name]" --body-file intent-feedback.md -``` - -If the label doesn't exist, omit the `--label` flag — don't let a missing -label block submission. - -If submission succeeds, delete the feedback file. - -### If `gh` CLI is not available - -Tell the human: - -> "I've written skill feedback to `intent-feedback.md`. To submit it, -> open an issue at https://github.com/[owner/repo]/issues and paste the -> contents." +--- +name: skill-feedback-collection +description: > + Collect structured feedback about skill usage after completing a coding task. + Activate at the end of any session where one or more SKILL.md files were + loaded. Captures agent signals (gaps, errors, corrections, human interventions) + and brief human input, then submits directly via gh CLI or provides manual + submission instructions. +metadata: + version: '2.0' + category: meta-tooling +--- + +# Skill Feedback Collection + +Run this at the end of any session where you loaded one or more SKILL.md files. +The goal is to capture what worked, what didn't, and what was missing — so skill +maintainers can improve future versions. + +This skill also covers **meta-skill feedback** — feedback about the scaffolding +process itself. When invoked after running domain-discovery, tree-generator, and +generate-skill, treat those three meta skills as the "skills" being evaluated. +Capture what worked and what didn't in each scaffolding phase so the meta skills +can be improved. + +--- + +## Phase 1 — Automated Signal Collection + +Review your own session transcript. No human interaction needed yet. + +### 1a: Skills inventory + +Before analyzing gaps and errors, inventory all skills that were available +during the session: + +- **Loaded and used:** Skills you read and actively followed. +- **Available but not loaded:** Skills that were installed (discoverable via + `intent list`) but you never read. This is important — many issues stem from + the agent not loading the right skill, not from the skill itself being wrong. + +### 1b: Gap detection + +Identify moments where the skill was silent and you had to bridge the gap +yourself — via code reading, search, trial-and-error, or general knowledge. + +For each gap, note: + +- What you needed to do +- What the skill should have told you +- How you solved it (code reading, web search, guessing) + +### 1c: Error/correction tracking + +Identify moments where the skill prescribed an approach that produced an error. + +For each error, note: + +- What the skill said to do +- The error or incorrect behavior that resulted +- The fix you applied + +### 1d: Human intervention events + +Identify moments where the human clarified, corrected, or overrode your approach. + +For each intervention, note: + +- What you were doing when the human intervened +- What the human said or changed +- Whether the skill could have prevented this + +### 1e: Step duration anomalies + +Identify steps that consumed disproportionate effort compared to their apparent +complexity. These signal that the skill should provide a template, snippet, or +more detailed guidance. + +--- + +## Phase 2 — Human Interview + +Ask the human up to 4 questions. Keep it brief — skip questions if the session +already provided clear answers. Respect if they decline. + +1. "Was anything unclear about what was happening during the task?" +2. "Did anything feel frustrating or take longer than expected?" +3. "Were you uncertain about the output quality at any point?" +4. "Anything you'd want done differently next time?" + +Derive `userRating` from overall sentiment: + +- Mostly positive → `good` +- Mixed signals → `mixed` +- Mostly negative → `bad` + +If the human gives an explicit rating, use that instead. + +--- + +## Phase 3 — Build the Feedback + +Write one Markdown feedback file per skill used. Only include skills that were +actually used during the session — skip any that were loaded but never +referenced. + +### Template + +```markdown +# Skill Feedback: [skill name from SKILL.md frontmatter] + +**Package:** [npm package name that contains the skill] +**Skill version:** [metadata.version or library_version from frontmatter] +**Rating:** [good | mixed | bad] + +## Task + +[one-sentence summary of what the human asked you to do] + +## Skills Inventory + +**Loaded and used:** + +- [list each skill the agent read and actively followed during the session] + +**Available but not loaded:** + +- [list skills that were installed/available but the agent never read] + +## What Worked + +[patterns/instructions from the skill that were accurate and helpful] + +## What Failed + +[from 1c — skill instructions that produced errors] + +## Missing + +[from 1b — gaps where the skill should have covered] + +## Self-Corrections + +[from 1c fixes + 1d human interventions, combined] + +## User Comments + +[optional — direct quotes or paraphrased human input from Phase 2] +``` + +### Field derivation guide + +| Field | Source | +| ---------------- | ------------------------------------------------------------------ | +| Skill name | Frontmatter `name` field of the SKILL.md you loaded | +| Package | The npm package the skill lives in (e.g. `@tanstack/query-intent`) | +| Skill version | Frontmatter `metadata.version` or `library_version` | +| Task | Summarize the human's original request in one sentence | +| Skills Inventory | Which skills were loaded vs. available but not loaded (see below) | +| What Worked | List skill sections/patterns that were correct and useful | +| What Failed | From 1c — skill instructions that produced errors | +| Missing | From 1b — gaps where the skill was silent | +| Self-Corrections | From 1c fixes + 1d human interventions, combined | +| Rating | From Phase 2 sentiment analysis or explicit rating | +| User Comments | From Phase 2 answers, keep brief | + +--- + +## Phase 4 — Submit + +Determine the target repo from the skill's package. The repo is typically +derivable from the `repository` field in the package's `package.json`, or +from the `sources` field in the SKILL.md frontmatter. + +### Link to existing issues/discussions + +Before creating a new issue, search the target repo for existing issues or +discussions that match the feedback. Use `gh search issues` or the GitHub +web search with keywords from the "What Failed" and "Missing" sections. + +- If an **open issue** already describes the same problem, comment on it + with the feedback instead of creating a duplicate. Reference the skill + name and version in your comment. +- If a **closed issue** describes a problem the skill still gets wrong + (regression or stale skill content), reference the closed issue in the + new feedback issue body: `Related to #[number] — this was fixed in the +library but the skill still describes the old behavior.` +- If a **discussion thread** covers the same topic, link to it in the + feedback issue body so maintainers can see the community context. + +This prevents duplicate issues and gives maintainers richer context for +improving skills. + +### Privacy check + +Before submitting, determine whether the user's project is public or private. +Check with `gh repo view --json visibility` or look for a `private` field in +the project's `package.json`. If you can't determine visibility, assume private. + +**Private repos:** Feedback is submitted to a public issue tracker, so it must +not contain project-specific details. Before submission: + +1. Strip any project-specific code, file paths, internal API names, service + URLs, or business logic from all fields +2. Rewrite the "Task" field to describe the _type_ of task generically + (e.g. "set up authenticated data fetching" not "set up auth for our + internal billing API at api.acme.corp/billing") +3. Rewrite "What Failed" and "Missing" entries to reference only the + skill's own APIs and patterns, not the user's code +4. Show the sanitized feedback to the user and ask them to confirm it's + safe to submit before proceeding + +**Public repos:** No sanitization needed. Proceed directly to submission. + +### If `gh` CLI is available + +Submit directly as a GitHub issue: + +```bash +gh issue create --repo [owner/repo] --title "Skill Feedback: [skill-name] ([rating])" --label "skill:[skill-name]" --body-file intent-feedback.md +``` + +If the label doesn't exist, omit the `--label` flag — don't let a missing +label block submission. + +If submission succeeds, delete the feedback file. + +### If `gh` CLI is not available + +Tell the human: + +> "I've written skill feedback to `intent-feedback.md`. To submit it, +> open an issue at https://github.com/[owner/repo]/issues and paste the +> contents." diff --git a/packages/intent/meta/generate-skill/SKILL.md b/packages/intent/meta/generate-skill/SKILL.md index 656fc8b..d0d7146 100644 --- a/packages/intent/meta/generate-skill/SKILL.md +++ b/packages/intent/meta/generate-skill/SKILL.md @@ -1,453 +1,453 @@ ---- -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. - -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). -``` +--- +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. + +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). +``` diff --git a/packages/intent/meta/templates/workflows/notify-intent.yml b/packages/intent/meta/templates/workflows/notify-intent.yml index edc4b5b..cc18685 100644 --- a/packages/intent/meta/templates/workflows/notify-intent.yml +++ b/packages/intent/meta/templates/workflows/notify-intent.yml @@ -1,52 +1,52 @@ -# notify-intent.yml — Drop this into your library repo's .github/workflows/ -# -# Fires a repository_dispatch event to TanStack/intent whenever docs or -# source files change on merge to main. This triggers the skill staleness -# check workflow in the intent repo. -# -# Requirements: -# - A fine-grained PAT with contents:write on TanStack/intent stored -# as the INTENT_NOTIFY_TOKEN repository secret. -# -# Template variables (replaced by `intent setup`): -# {{PACKAGE_NAME}} — e.g. @tanstack/query -# {{DOCS_PATH}} — e.g. docs/** -# {{SRC_PATH}} — e.g. packages/query-core/src/** - -name: Notify Intent - -on: - push: - branches: [main] - paths: - - '{{DOCS_PATH}}' - - '{{SRC_PATH}}' - -jobs: - notify: - name: Notify TanStack Intent - runs-on: ubuntu-latest - steps: - - name: Checkout - uses: actions/checkout@v4 - with: - fetch-depth: 2 - - - name: Collect changed files - id: changes - run: | - FILES=$(git diff --name-only HEAD~1 HEAD | jq -R -s -c 'split("\n") | map(select(length > 0))') - echo "files=$FILES" >> "$GITHUB_OUTPUT" - - - name: Dispatch to intent repo - uses: peter-evans/repository-dispatch@v3 - with: - token: ${{ secrets.INTENT_NOTIFY_TOKEN }} - repository: TanStack/intent - event-type: skill-check - client-payload: | - { - "package": "{{PACKAGE_NAME}}", - "sha": "${{ github.sha }}", - "changed_files": ${{ steps.changes.outputs.files }} - } +# notify-intent.yml — Drop this into your library repo's .github/workflows/ +# +# Fires a repository_dispatch event to TanStack/intent whenever docs or +# source files change on merge to main. This triggers the skill staleness +# check workflow in the intent repo. +# +# Requirements: +# - A fine-grained PAT with contents:write on TanStack/intent stored +# as the INTENT_NOTIFY_TOKEN repository secret. +# +# Template variables (replaced by `intent setup`): +# {{PACKAGE_NAME}} — e.g. @tanstack/query +# {{DOCS_PATH}} — e.g. docs/** +# {{SRC_PATH}} — e.g. packages/query-core/src/** + +name: Notify Intent + +on: + push: + branches: [main] + paths: + - '{{DOCS_PATH}}' + - '{{SRC_PATH}}' + +jobs: + notify: + name: Notify TanStack Intent + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 2 + + - name: Collect changed files + id: changes + run: | + FILES=$(git diff --name-only HEAD~1 HEAD | jq -R -s -c 'split("\n") | map(select(length > 0))') + echo "files=$FILES" >> "$GITHUB_OUTPUT" + + - name: Dispatch to intent repo + uses: peter-evans/repository-dispatch@v3 + with: + token: ${{ secrets.INTENT_NOTIFY_TOKEN }} + repository: TanStack/intent + event-type: skill-check + client-payload: | + { + "package": "{{PACKAGE_NAME}}", + "sha": "${{ github.sha }}", + "changed_files": ${{ steps.changes.outputs.files }} + }