feat(cli): add published skill tree for agent workflows

Author: tannerlinsley

.changeset/cli-skills-minor.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/cli': minor
+---
+
+Add a published skill tree for TanStack CLI workflows and include `skills` in package files so agent guidance ships in npm installs.

packages/cli/package.json

@@ -5,6 +5,10 @@
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/types/index.d.ts",
+  "files": [
+    "dist",
+    "skills"
+  ],
   "bin": {
     "tanstack": "./dist/bin.js"
   },

packages/cli/skills/CHANGELOG.md

@@ -0,0 +1,18 @@
+## 2026-03-02
+
+### Updated for @tanstack/cli v0.61.0
+
+**Breaking changes:**
+- create-app-scaffold: documents router-only compatibility behavior where template/deployment/add-on intent is ignored.
+- add-addons-existing-app: enforces `.cta.json` metadata precondition for add flows.
+
+**Deprecation updates:**
+- create-app-scaffold: `--no-tailwind` treated as deprecated/ignored; recommends post-scaffold removal flow.
+- query-docs-library-metadata: deprecated alias discovery patterns replaced with `tanstack` command namespace.
+
+**New skills:**
+- create-app-scaffold: deterministic app generation and flag compatibility.
+- add-addons-existing-app: add-on layering into existing repos.
+- query-docs-library-metadata: JSON discovery/doc retrieval for agents.
+- choose-ecosystem-integrations: partner-to-add-on mapping and exclusivity handling.
+- maintain-custom-addons-dev-watch: custom add-on authoring and dev-watch lifecycle.

packages/cli/skills/add-addons-existing-app/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: add-addons-existing-app
+description: >
+  Apply integrations to existing projects with tanstack add, including
+  add-on id resolution, dependency chains, option prompts, and .cta.json
+  project metadata preconditions.
+type: core
+library: tanstack-cli
+library_version: "0.61.0"
+---
+
+# Add Add-ons To Existing App
+
+Use this skill when the project already exists and you need to layer add-ons safely without breaking dependency or metadata assumptions.
+
+## Setup
+
+```bash
+npx @tanstack/cli add clerk drizzle
+```
+
+## Core Patterns
+
+### Add multiple integrations in one pass
+
+```bash
+npx @tanstack/cli add tanstack-query drizzle
+```
+
+### Resolve candidate ids before applying
+
+```bash
+npx @tanstack/cli create --list-add-ons --json
+```
+
+### Validate optionized add-ons before install
+
+```bash
+npx @tanstack/cli create --addon-details prisma --json
+```
+
+## Common Mistakes
+
+### CRITICAL Run tanstack add without .cta.json
+
+Wrong:
+```bash
+npx @tanstack/cli add clerk
+```
+
+Correct:
+```bash
+# Run in a project scaffolded by TanStack CLI (contains .cta.json), then:
+npx @tanstack/cli add clerk
+```
+
+Add flows depend on persisted scaffold metadata, so commands can fail or apply incomplete config when `.cta.json` is missing.
+
+Source: packages/create/src/custom-add-ons/shared.ts:158
+
+### HIGH Use invalid add-on id
+
+Wrong:
+```bash
+npx @tanstack/cli add drizle
+```
+
+Correct:
+```bash
+npx @tanstack/cli add drizzle
+```
+
+Unknown ids stop resolution and force manual correction before any add-on work proceeds.
+
+Source: packages/create/src/add-ons.ts:44
+
+### HIGH Ignore add-on dependency requirements
+
+Wrong:
+```bash
+npx @tanstack/cli add custom-addon-with-missing-deps
+```
+
+Correct:
+```bash
+npx @tanstack/cli add required-dependency custom-addon-with-missing-deps
+```
+
+Add-ons with `dependsOn` can fail during finalization if required dependencies are not present.
+
+Source: packages/create/src/add-ons.ts:48
+
+### MEDIUM Assume old Windows path bug still present
+
+Wrong:
+```bash
+# Avoid tanstack add on Windows and patch manually
+```
+
+Correct:
+```bash
+npx @tanstack/cli add clerk
+```
+
+Avoiding supported workflows based on historical bug reports causes unnecessary manual drift. Fixed in newer versions, but agents trained on older threads may still avoid this path.
+
+Source: https://github.com/TanStack/cli/issues/329
+
+### HIGH Tension: Backwards support vs deterministic automation
+
+This domain's patterns conflict with maintain-custom-addons-dev-watch. Automation that assumes universal add flows tends to fail because legacy compatibility still relies on hidden scaffold metadata.
+
+See also: maintain-custom-addons-dev-watch/SKILL.md § Common Mistakes

packages/cli/skills/choose-ecosystem-integrations/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: choose-ecosystem-integrations
+description: >
+  Map tanstack ecosystem partner metadata to installable add-on ids using
+  tanstack ecosystem --json, tanstack create --list-add-ons --json, and
+  tanstack create --addon-details --json. Covers exclusive categories,
+  provider options, and router-only compatibility constraints.
+type: composition
+library: tanstack-cli
+library_version: "0.61.0"
+requires:
+  - create-app-scaffold
+  - query-docs-library-metadata
+---
+
+This skill requires familiarity with scaffold and discovery workflows. Read `create-app-scaffold` and `query-docs-library-metadata` first.
+
+# Choose Ecosystem Integrations
+
+Use this skill at the seam between user requirements and valid CLI integration choices.
+
+## Setup
+
+```bash
+npx @tanstack/cli ecosystem --json
+npx @tanstack/cli create --list-add-ons --json
+```
+
+## Core Patterns
+
+### Map partner intent to add-on ids explicitly
+
+```bash
+npx @tanstack/cli ecosystem --category database --json
+npx @tanstack/cli create --list-add-ons --json
+```
+
+### Inspect option surfaces before final provider choice
+
+```bash
+npx @tanstack/cli create --addon-details drizzle --json
+npx @tanstack/cli create --addon-details prisma --json
+```
+
+### Enforce one choice per exclusive category
+
+```bash
+npx @tanstack/cli create my-app \
+  --framework react \
+  --add-ons clerk,drizzle \
+  --deployment cloudflare \
+  -y
+```
+
+## Common Mistakes
+
+### HIGH Treat ecosystem partner id as add-on id
+
+Wrong:
+```bash
+npx @tanstack/cli add <partner-id-from-ecosystem>
+```
+
+Correct:
+```bash
+npx @tanstack/cli ecosystem --json
+npx @tanstack/cli create --list-add-ons --json
+npx @tanstack/cli add <mapped-addon-id>
+```
+
+`ecosystem` includes partners that are not directly installable add-ons, so direct reuse of partner ids can fail late in add/apply flows.
+
+Source: tanstack ecosystem --json output + tanstack create --list-add-ons --json output
+
+### HIGH Skip addon-details before choosing provider
+
+Wrong:
+```bash
+npx @tanstack/cli create my-app --add-ons prisma -y
+```
+
+Correct:
+```bash
+npx @tanstack/cli create --addon-details prisma --json
+npx @tanstack/cli create my-app --add-ons prisma -y
+```
+
+Optionized providers can default silently, producing the wrong data-layer stack for the requested integration.
+
+Source: tanstack create --addon-details prisma --json
+
+### HIGH Select multiple exclusive integrations together
+
+Wrong:
+```bash
+npx @tanstack/cli create my-app --add-ons clerk,workos -y
+```
+
+Correct:
+```bash
+npx @tanstack/cli create my-app --add-ons clerk -y
+```
+
+Exclusive categories permit only one active choice, so multi-select commands can drop or replace intended providers.
+
+Source: packages/create/src/frameworks/*/*/info.json
+
+### CRITICAL Assume router-only supports deployment integration
+
+Wrong:
+```bash
+npx @tanstack/cli create my-app --router-only --deployment cloudflare -y
+```
+
+Correct:
+```bash
+npx @tanstack/cli create my-app --router-only -y
+```
+
+Router-only mode ignores deployment integration, so the command succeeds without applying the intended ecosystem target.
+
+Source: packages/cli/src/command-line.ts:349
+
+### HIGH Tension: Compatibility mode vs explicit intent
+
+This domain's patterns conflict with create-app-scaffold. Integration planning tends to over-assume command intent is preserved, but compatibility mode silently strips integration flags.
+
+See also: create-app-scaffold/SKILL.md § Common Mistakes
+
+### HIGH Tension: Single-command convenience vs integration precision
+
+This domain's patterns conflict with query-docs-library-metadata. Integration choices tend to drift when discovery metadata is skipped in favor of one-shot scaffold commands.
+
+See also: query-docs-library-metadata/SKILL.md § Common Mistakes
+
+## References
+
+- [Authentication providers](references/authentication-providers.md)
+- [Data layer providers](references/data-layer-providers.md)
+- [Deployment targets](references/deployment-targets.md)

packages/cli/skills/choose-ecosystem-integrations/references/authentication-providers.md

@@ -0,0 +1,19 @@
+# Authentication Providers
+
+Use `tanstack ecosystem --category authentication --json` for partner discovery, then map to installable add-on ids via `tanstack create --list-add-ons --json`.
+
+## Common add-ons
+
+- `clerk`
+- `workos`
+- `better-auth`
+
+## Selection pattern
+
+```bash
+npx @tanstack/cli ecosystem --category authentication --json
+npx @tanstack/cli create --list-add-ons --json
+npx @tanstack/cli create my-app --add-ons clerk -y
+```
+
+Authentication providers are typically exclusive; select one unless metadata explicitly allows combination.

packages/cli/skills/choose-ecosystem-integrations/references/data-layer-providers.md

@@ -0,0 +1,20 @@
+# Data Layer Providers
+
+Inspect each provider's options before generation to avoid defaulting to an unintended backend.
+
+## Common add-ons
+
+- `prisma`
+- `drizzle`
+- `convex`
+- `neon`
+
+## Selection pattern
+
+```bash
+npx @tanstack/cli create --addon-details prisma --json
+npx @tanstack/cli create --addon-details drizzle --json
+npx @tanstack/cli create my-app --add-ons drizzle -y
+```
+
+Database/ORM categories can be exclusive depending on framework template metadata.

packages/cli/skills/choose-ecosystem-integrations/references/deployment-targets.md

@@ -0,0 +1,19 @@
+# Deployment Targets
+
+Map deployment intent to one supported target and include it in scaffold commands only outside router-only mode.
+
+## Common targets
+
+- `cloudflare`
+- `netlify`
+- `railway`
+- `nitro`
+
+## Selection pattern
+
+```bash
+npx @tanstack/cli ecosystem --category deployment --json
+npx @tanstack/cli create my-app --deployment cloudflare -y
+```
+
+Deployment target selection is exclusive and ignored when `--router-only` is active.