TanStack · LadyBluenotes · Jan 26, 2026 · Jan 26, 2026 · Jan 26, 2026 · Jan 26, 2026
diff --git a/packages/skills/bin/cli.js b/packages/skills/bin/cli.js
@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, cpSync, readdirSync, statSync } from 'node:fs'
+import { resolve, join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const SKILLS_SOURCE = resolve(__dirname, '..', 'skills', 'tanstack-router')
+const DEFAULT_DEST = '.ai/tanstack-router'
+
+function printHelp() {
+  console.log(`
+Usage: npx @tanstack/router-skills init [destination]
+
+Downloads TanStack Router skills to a local directory for use with AI tools.
+
+Arguments:
+  destination    Target directory (default: ${DEFAULT_DEST})
+
+Examples:
+  npx @tanstack/router-skills init
+  npx @tanstack/router-skills init .cursor/rules/tanstack
+  npx @tanstack/router-skills init .ai/skills/tanstack-router
+`)
+}
+
+function countFiles(dir, ext = '.md') {
+  let count = 0
+  const items = readdirSync(dir)
+  for (const item of items) {
+    const fullPath = join(dir, item)
+    const stat = statSync(fullPath)
+    if (stat.isDirectory()) {
+      count += countFiles(fullPath, ext)
+    } else if (item.endsWith(ext)) {
+      count++
+    }
+  }
+  return count
+}
+
+function copySkills(dest) {
+  const destination = resolve(process.cwd(), dest)
+
+  // Create destination directory
+  if (!existsSync(destination)) {
+    mkdirSync(destination, { recursive: true })
+  }
+
+  // Copy skills, excluding GENERATION.md
+  cpSync(SKILLS_SOURCE, destination, {
+    recursive: true,
+    filter: (src) => !src.endsWith('GENERATION.md'),
+  })
+
+  const fileCount = countFiles(destination)
+  console.log(`\nTanStack Router skills installed to: ${destination}`)
+  console.log(`Copied ${fileCount} skill files.\n`)
+  console.log(
+    "Add this directory to your AI tool's context/rules configuration.",
+  )
+}
+
+// Main
+const args = process.argv.slice(2)
+
+if (args.includes('--help') || args.includes('-h')) {
+  printHelp()
+  process.exit(0)
+}
+
+const command = args[0]
+
+if (!command || command === 'init') {
+  const dest = args[1] || DEFAULT_DEST
+  copySkills(dest)
+} else if (command && !command.startsWith('-')) {
+  // Treat as destination path for convenience
+  copySkills(command)
+} else {
+  printHelp()
+  process.exit(1)
+}
diff --git a/packages/skills/package.json b/packages/skills/package.json
@@ -0,0 +1,32 @@
+{
+  "name": "@tanstack/router-skills",
+  "version": "0.0.1",
+  "description": "TanStack Router and Start skills documentation for AI agents",
+  "author": "Tanner Linsley",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/router.git",
+    "directory": "packages/router-skills"
+  },
+  "homepage": "https://tanstack.com/router",
+  "keywords": [
+    "tanstack",
+    "router",
+    "skills",
+    "ai",
+    "llm",
+    "documentation"
+  ],
+  "bin": {
+    "router-skills": "./bin/cli.js"
+  },
+  "type": "module",
+  "files": [
+    "bin",
+    "skills"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}
diff --git a/packages/skills/skills/tanstack-router/SKILL.md b/packages/skills/skills/tanstack-router/SKILL.md
@@ -0,0 +1,39 @@
+---
+name: tanstack-router
+description: |
+  TanStack Router and TanStack Start patterns for React/Solid apps.
+  Use for type-safe routing, data loading, search params, SSR, and server functions.
+---
+
+# TanStack Router Skills
+
+TanStack Router is a type-safe router with built-in caching and URL state management. TanStack Start is a full-stack framework built on top of Router.
+
+## Routing Table
+
+| Topic      | Directory | When to Use                                                                                                                                                              |
+| ---------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Router** | `router/` | Client-side routing: route definitions, navigation, data loading, search params, type safety. Use for any routing question that doesn't involve server functions or SSR. |
+| **Start**  | `start/`  | Full-stack framework: server functions, SSR, streaming, static generation, deployment, middleware. Use when the question involves server-side code execution.            |
+
+## Quick Detection
+
+**Route to `router/` when:**
+
+- Defining routes (file-based or code-based)
+- Using `<Link>` or `useNavigate`
+- Implementing loaders or preloading
+- Working with search params or path params
+- Setting up authentication guards
+- Code splitting routes
+- Using router context
+
+**Route to `start/` when:**
+
+- Using `createServerFn` or server functions
+- Implementing SSR, streaming, or static generation
+- Setting up API routes
+- Working with middleware
+- Deploying to production
+- Managing environment variables on server
+- Database access patterns
diff --git a/packages/skills/skills/tanstack-router/router/SKILL.md b/packages/skills/skills/tanstack-router/router/SKILL.md
@@ -0,0 +1,63 @@
+---
+name: tanstack-router-core
+description: |
+  Core TanStack Router patterns for client-side routing.
+  Use for route definitions, navigation, data loading, search params, and type safety.
+---
+
+# TanStack Router
+
+Type-safe routing for React and Solid applications with first-class search param support, built-in caching, and automatic code splitting.
+
+## Routing Table
+
+| Topic             | Directory        | When to Use                                                                                  |
+| ----------------- | ---------------- | -------------------------------------------------------------------------------------------- |
+| **Installation**  | `installation/`  | Setting up TanStack Router with Vite, Webpack, Rspack, ESBuild, CLI, migration               |
+| **Routing**       | `routing/`       | Route definitions, file-based vs code-based routing, route trees, matching, path params      |
+| **Navigation**    | `navigation/`    | Links, programmatic navigation, navigation blocking, route masking, URL rewrites             |
+| **Data Loading**  | `data-loading/`  | Loaders, deferred loading, preloading, mutations, external data integration (TanStack Query) |
+| **Search Params** | `search-params/` | Type-safe search params, validation, serialization, default values                           |
+| **Auth & Errors** | `auth-errors/`   | Protected routes, redirects, not-found handling, error boundaries                            |
+| **Integrations**  | `integrations/`  | UI frameworks (Chakra, MUI, Shadcn), testing, animations, React Query, state management      |
+| **Advanced**      | `advanced/`      | Code splitting, SSR basics, router context, render optimizations, scroll restoration         |
+| **Type Safety**   | `type-safety/`   | Type inference, utilities, strict typing patterns                                            |
+
+## Core Setup
+
+```tsx
+// app/router.tsx
+import { createRouter } from '@tanstack/react-router'
+import { routeTree } from './routeTree.gen'
+
+export const router = createRouter({ routeTree })
+
+declare module '@tanstack/react-router' {
+  interface Register {
+    router: typeof router
+  }
+}
+```
+
+```tsx
+// app/main.tsx
+import { RouterProvider } from '@tanstack/react-router'
+import { router } from './router'
+
+function App() {
+  return <RouterProvider router={router} />
+}
+```
+
+## File-Based Routing (Quick Reference)
+
+| File Pattern            | Route Path   | Purpose                    |
+| ----------------------- | ------------ | -------------------------- |
+| `routes/__root.tsx`     | -            | Root layout, always active |
+| `routes/index.tsx`      | `/`          | Home page                  |
+| `routes/about.tsx`      | `/about`     | Static route               |
+| `routes/posts/`         | `/posts`     | Directory = path segment   |
+| `routes/posts/$id.tsx`  | `/posts/:id` | Dynamic param              |
+| `routes/posts_.$id.tsx` | `/posts/:id` | Flat file dynamic param    |
+| `routes/_layout.tsx`    | -            | Pathless layout wrapper    |
+| `routes/(group)/`       | -            | Route group (no URL)       |