KevinVandy · Oct 4, 2026 · Oct 4, 2026
diff --git a/.changeset/short-knives-open.md b/.changeset/short-knives-open.md
@@ -0,0 +1,18 @@
+---
+'@tanstack/table-core': patch
+'@tanstack/react-table': patch
+'@tanstack/preact-table': patch
+'@tanstack/solid-table': patch
+'@tanstack/svelte-table': patch
+'@tanstack/vue-table': patch
+'@tanstack/angular-table': patch
+'@tanstack/lit-table': patch
+'@tanstack/alpine-table': patch
+'@tanstack/ember-table': patch
+'@tanstack/octane-table': patch
+'@tanstack/match-sorter-utils': patch
+---
+
+Refactor bundled Intent skills into smaller entry points with references loaded for the current task. Keep core feature architecture and shared state directly discoverable, and move individual features, adapter compositions, and detailed migration guidance into references.
+
+Consumers with individual skill permissions or explicit agent mappings must replace retired feature/composition IDs with their owning entry points and refresh Intent mappings. See the Agent Skills guide for the replacement paths.
@@ -18,7 +18,11 @@ on:
       - '**/_artifacts/**'
       - 'scripts/sync-skill-versions.mjs'
       - 'scripts/typecheck-skill-snippets.mjs'
+      - 'scripts/skill-snippets-*.tsconfig.json'
       - 'scripts/validate-skill-content.mjs'
+      - 'scripts/validate-skill-tree.mjs'
+      - 'scripts/skill-tree.mjs'
+      - 'scripts/tests/skill-tree.test.mjs'
       - 'package.json'
       - 'pnpm-lock.yaml'
       - '.github/workflows/check-skills.yml'

diff --git a/_artifacts/domain_map.yaml b/_artifacts/domain_map.yaml
diff --git a/_artifacts/skill_spec.md b/_artifacts/skill_spec.md
diff --git a/_artifacts/skill_tree.yaml b/_artifacts/skill_tree.yaml
diff --git a/docs/agent-skills.md b/docs/agent-skills.md
@@ -27,14 +27,18 @@ TanStack Table publishes skills inside its packages so the guidance travels with
 
 The skills available to your agent depend on which packages your project installs:
 
-| Package                                                    | Skills                                               | What they teach                                                                                                                                                                                                         |
-| ---------------------------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@tanstack/table-core`                                     | `core`, `table-features`, and focused feature skills | Headless table architecture, explicit feature registration, TypeScript, client/server boundaries, migration, and features such as sorting, filtering, grouping, pagination, pinning, sizing, selection, and aggregation |
-| `@tanstack/<framework>-table`                              | Framework-specific setup and state skills            | Creating, rendering, and controlling a table with your framework adapter; supported adapters also include migration and TanStack Query/Virtual composition skills                                                       |
-| `@tanstack/table-devtools` and framework devtools adapters | `devtools`                                           | Registering table instances and inspecting features, state, options, rows, and columns                                                                                                                                  |
-| `@tanstack/match-sorter-utils`                             | `fuzzy-ranking`                                      | Fuzzy filtering, ranking metadata, and rank-aware sorting                                                                                                                                                               |
+| Package                                                    | Skills                                                                         | What they teach                                                                                                                                                                  |
+| ---------------------------------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@tanstack/table-core`                                     | `core`, `table-features`, `table-state`, `custom-features`, `migrate-v8-to-v9` | Core architecture, feature registration, shared state ownership, plugin authoring, and migration. Each optional feature has an on-demand reference linked from `table-features`. |
+| `@tanstack/<framework>-table`                              | `getting-started`, `table-state`, and migration where supported                | Framework setup, rendering, and reactive state. References cover reusable app hooks, advanced reactivity, and maintained Query/Virtual integrations.                             |
+| `@tanstack/table-devtools` and framework devtools adapters | `devtools`                                                                     | Registering table instances and inspecting features, state, options, rows, and columns                                                                                           |
+| `@tanstack/match-sorter-utils`                             | `fuzzy-ranking`                                                                | Fuzzy filtering, ranking metadata, and rank-aware sorting                                                                                                                        |
 
-Each skill lives under `node_modules/<package>/skills/<skill-name>/SKILL.md` once the package is installed. Skills can declare prerequisites, so your agent can load the core guidance before a framework or feature-specific skill.
+Each skill lives under `node_modules/<package>/skills/<skill-name>/SKILL.md` once the package is installed. Its `references/` directory contains guidance for specific tasks. For example, row selection lives in `@tanstack/table-core/skills/table-features/references/row-selection.md`.
+
+The entry point tells the agent when to read each reference. A sorting change loads the sorting guidance; selection, resizing, and other unrelated feature references stay unloaded. Framework state skills load the shared state model and then explain their own reactive reads and updates.
+
+Intent lists entry points and loads one requested `SKILL.md` at a time. The agent follows its prerequisite instructions and reads relevant references. A React project with core installed has eight Table entry points. Devtools and other installed libraries add their own entries.
 
 ## Step 1: Install TanStack Table
 
@@ -89,9 +93,11 @@ You can inspect and load Table skills yourself with the same commands:
 ```bash
 npx @tanstack/intent@latest list
 npx @tanstack/intent@latest load @tanstack/react-table#getting-started
-npx @tanstack/intent@latest load @tanstack/table-core#sorting
+npx @tanstack/intent@latest load @tanstack/table-core#table-features
 ```
 
+For sorting, follow the loaded entry point's link to `references/sorting.md`. The load command resolves relative Markdown links to the installed package, including when your package manager uses nested dependency paths.
+
 If you prefer explicit task-to-skill entries, run `npx @tanstack/intent@latest install --map`. Mapping mode scans your installed intent-enabled packages and writes compact `id`, `run`, and `for` entries into the managed block.
 
 ## Step 4: Confirm It's Wired Up
@@ -112,6 +118,22 @@ If the agent still falls back to v8 patterns, reopen its config file and confirm
 
 Skills are versioned with each package. When you update your TanStack Table packages, the `SKILL.md` files under `node_modules` update with them. No CLI rerun is needed. If you use explicit mappings, rerun `npx @tanstack/intent@latest install --map` after adding another intent-enabled package, such as a Table devtools adapter, or when you want to refresh the mappings.
 
+### Update older skill mappings
+
+The progressive-disclosure layout replaces individual feature and composition skill IDs with references. If your agent configuration contains the old IDs, update them as follows:
+
+| Old skill ID                                                                            | Replacement entry point and reference                                        |
+| --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `@tanstack/table-core#sorting`, `#row-selection`, and the other optional feature skills | `@tanstack/table-core#table-features`, then the matching feature reference   |
+| `@tanstack/table-core#client-vs-server`                                                 | `@tanstack/table-core#table-features`, then `references/client-vs-server.md` |
+| `@tanstack/table-core#typescript` or `#api-not-found`                                   | `@tanstack/table-core#core`, then the matching reference                     |
+| `@tanstack/<framework>-table#create-table-hook`                                         | The adapter's `getting-started`, then `references/create-table-hook.md`      |
+| `@tanstack/<framework>-table#with-tanstack-query` or `#with-tanstack-virtual`           | The adapter's `getting-started`, then the matching integration reference     |
+
+If `package.json#intent.skills` allows individual old skill IDs, run `npx @tanstack/intent@latest install --review` to select their replacements and the prerequisites they need. Package-level permissions include new entry points automatically. Regenerate explicit mappings with `npx @tanstack/intent@latest install --map` after updating permissions. Direct file pointers to moved skills also need their new paths.
+
+Core state guidance is available as `@tanstack/table-core#table-state`. Adapter state and migration skill IDs remain available. Migration skills retain a complete audit checklist and link to detailed mappings for the APIs your project uses.
+
 ## Using Skills Without the CLI
 
 If you'd rather wire skills in yourself, reference them directly from `node_modules` in any agent config file. The minimum your agent needs is a pointer to the relevant file:

diff --git a/package.json b/package.json
@@ -39,7 +39,8 @@
     "test:intent": "intent validate && intent stale",
     "test:skill-content": "node scripts/validate-skill-content.mjs",
     "test:skill-snippets": "node scripts/typecheck-skill-snippets.mjs",
-    "test:skills": "intent validate && pnpm skills:versions:check && pnpm test:skill-content && pnpm test:skill-snippets",
+    "test:skill-tree": "node scripts/validate-skill-tree.mjs && node --test scripts/tests/skill-tree.test.mjs",
+    "test:skills": "intent validate && pnpm skills:versions:check && pnpm test:skill-tree && pnpm test:skill-content && pnpm test:skill-snippets",
     "test:knip": "NODE_OPTIONS='--max-old-space-size=4096' knip",
     "test:lib": "nx affected --targets=test:lib",
     "test:lib:dev": "pnpm test:lib && nx watch --all -- pnpm test:lib",
@@ -94,6 +95,7 @@
     "tsdown": "^0.23.0",
     "typescript": "6.0.3",
     "vite": "^8.3.2",
-    "vitest": "^4.1.11"
+    "vitest": "^4.1.11",
+    "yaml": "2.9.0"
   }
 }
diff --git a/packages/alpine-table/skills/getting-started/SKILL.md b/packages/alpine-table/skills/getting-started/SKILL.md
@@ -1,22 +1,25 @@
 ---
 name: getting-started
-description: >
-  Create an Alpine TanStack Table v9 table with createTable, explicit tableFeatures, Alpine.reactive data getters, x-for rendering, and FlexRender through x-html. Load for first-table setup, reactive options, or when nested Alpine directives rendered by x-html do not initialize.
+description:
+  Create and render Table v9 with the alpine adapter. Route reusable createTableHook
+  defaults, and framework setup; use table-state for reactive ownership.
 metadata:
   type: framework
   library: '@tanstack/alpine-table'
   framework: alpine
-  library_version: '9.2.5'
+  library_version: 9.2.5
 requires:
   - '@tanstack/table-core#core'
-  - '@tanstack/table-core#table-features'
 sources:
-  - 'TanStack/table:docs/framework/alpine/guide/table-state.md'
-  - 'TanStack/table:examples/alpine/basic-create-table'
-  - 'TanStack/table:packages/alpine-table/src/index.ts'
+  - TanStack/table:docs/framework/alpine/guide/table-state.md
+  - TanStack/table:examples/alpine/basic-create-table
+  - TanStack/table:packages/alpine-table/src/index.ts
+  - TanStack/table:docs/framework/alpine/guide/composable-tables.md
+  - TanStack/table:examples/alpine/basic-app-table
+  - TanStack/table:packages/alpine-table/src/createTableHook.ts
 ---
 
-This skill builds on @tanstack/table-core#core and @tanstack/table-core#table-features.
+Load `intent load @tanstack/table-core#core` first for the headless model, stable inputs, and column inference.
 
 ## Setup
 
@@ -57,52 +60,20 @@ Alpine.start()
 
 Render real table structure with `x-for`; use `x-html="FlexRender({ header })"` or `x-html="FlexRender({ cell })"` only for renderer output.
 
-## Core Patterns
+## Construction and rendering
 
-### Pass live options through getters
+Wrap changing data in `Alpine.reactive` and expose it with `get data()`. The adapter tracks option getters; `data: local.data` captures a snapshot and does not follow later array replacements. Keep static columns and features outside getters.
 
-Wrap changing data in an `Alpine.reactive({ data })` object and read `local.data` through `get data()`. The property read gives the adapter's effect a dependency to track before it calls `table.setOptions`.
+The returned table is a reactive proxy. Read Table APIs directly in `x-text`, `x-for`, `x-if`, or bound attributes; no Subscribe component is needed.
 
-### Read table APIs directly in bindings
+Build table structure and interactive controls as real Alpine markup. Use `x-html="FlexRender({ header })"` or `x-html="FlexRender({ cell })"` for renderer output. Alpine does not initialize directives inside `x-html` strings; use templates or `Alpine.bind` bundles for buttons and inputs.
 
-The adapter returns a reactive proxy. Expressions such as `x-text="table.getRowModel().rows.length"` update without a Subscribe component.
+## Read for the task
 
-### Render interaction controls as real markup
+- When adding or configuring optional features, load `intent load @tanstack/table-core#table-features` and read only references for the requested behavior.
+- For state ownership or reactive reads, read [table-state](../table-state/SKILL.md).
+- When tables share features, defaults, or reusable UI, read [create-table-hook](references/create-table-hook.md).
 
-Buttons, inputs, and directives belong in the template. Renderer strings are useful for cell content, but `x-html` does not initialize Alpine directives inside the injected HTML.
+## API discovery
 
-## Common Mistakes
-
-### HIGH Passing a data snapshot
-
-Wrong: `createTable({ features, columns, data: local.data })` when `local.data` will be replaced.
-
-Correct: expose `get data() { return local.data }`.
-
-The adapter tracks option getters; a captured array does not follow later replacements.
-
-Source: TanStack/table:packages/alpine-table/src/createTable.ts
-
-### HIGH Interactive directives hidden in x-html
-
-Wrong: return `'<button @click="remove()">Remove</button>'` from a cell renderer.
-
-Correct: render the button as real template markup and bind the row action there, or use an `Alpine.bind` bundle.
-
-Alpine does not initialize directives inside content inserted by `x-html`.
-
-Source: TanStack/table:docs/framework/alpine/guide/composable-tables.md
-
-### HIGH Expecting Table styling
-
-Wrong: enable sizing or pinning and assume widths/sticky positioning appear.
-
-Correct: apply widths, logical offsets, overflow, and sticky CSS in the Alpine template.
-
-Table exposes state and geometry; it does not own the renderer.
-
-Source: TanStack/table:docs/overview.md
-
-## API Discovery
-
-Inspect `node_modules/@tanstack/alpine-table/dist/index.d.ts` and `createTable.d.ts`. Exact core APIs live under `node_modules/@tanstack/table-core/dist/`.
+Inspect `node_modules/@tanstack/alpine-table/dist/index.d.ts`, `createTable.d.ts`, and `reactivity.d.ts`. Core feature APIs are in `node_modules/@tanstack/table-core/dist/features/`.
diff --git a/...e-table/skills/create-table-hook/SKILL.md → ...g-started/references/create-table-hook.md b/...e-table/skills/create-table-hook/SKILL.md → ...g-started/references/create-table-hook.md
@@ -1,23 +1,8 @@
----
-name: create-table-hook
-description: >
-  Share Alpine tableFeatures, defaults, createAppTable, and createAppColumnHelper with createTableHook. Load when multiple Alpine tables repeat infrastructure; unlike JSX adapters, Alpine has no registered table/cell/header component or context registry.
-metadata:
-  type: framework
-  library: '@tanstack/alpine-table'
-  framework: alpine
-  library_version: '9.2.5'
-requires:
-  - '@tanstack/table-core#core'
-  - getting-started
-  - table-state
-sources:
-  - 'TanStack/table:docs/framework/alpine/guide/composable-tables.md'
-  - 'TanStack/table:examples/alpine/basic-app-table'
-  - 'TanStack/table:packages/alpine-table/src/createTableHook.ts'
----
-
-This skill builds on @tanstack/table-core#core plus this package's getting-started and table-state skills.
+# Alpine reusable table hooks
+
+Read when multiple Alpine tables share features, defaults, or rendering conventions. Keep standalone construction for tables without shared conventions. For controlled state or reactive reads, read [table-state](../../table-state/SKILL.md).
+
+This reference inherits the version of its owning skill.
 
 ## Setup
 
@@ -47,7 +32,7 @@ Alpine.data('peopleTable', () => {
 })
 ```
 
-## Core Patterns
+## Core patterns
 
 ### Share infrastructure, keep data local
 
@@ -61,7 +46,7 @@ Use real templates and `Alpine.bind` bundles for interactive reuse. `createTable
 
 Columns from `createAppColumnHelper<TData>()` know the factory's registered features without userland feature generics.
 
-## Common Mistakes
+## Common mistakes
 
 ### HIGH Assuming a JSX component registry
 
@@ -73,16 +58,6 @@ The Alpine hook returns only app features, a column helper, and createAppTable.
 
 Source: TanStack/table:packages/alpine-table/src/createTableHook.ts
 
-### MEDIUM Abstracting a one-off table
-
-Wrong: introduce an app factory for one table with no shared conventions.
-
-Correct: use standalone `createTable` until infrastructure repeats.
-
-The hook is an application reuse boundary, not required setup.
-
-Source: TanStack/table:docs/framework/alpine/guide/composable-tables.md
-
 ### HIGH Reactive data captured as a snapshot
 
 Wrong: `createAppTable({ columns, data: local.data })` when the array will be replaced.
@@ -93,6 +68,12 @@ The app factory delegates to Alpine createTable, whose option effect tracks gett
 
 Source: TanStack/table:packages/alpine-table/src/createTable.ts
 
-## API Discovery
+## API discovery
 
 Inspect `node_modules/@tanstack/alpine-table/dist/createTableHook.d.ts`; do not infer component/context APIs from React, Vue, Solid, Svelte, Angular, or Lit adapters.
+
+## Sources
+
+- `TanStack/table:docs/framework/alpine/guide/composable-tables.md`
+- `TanStack/table:examples/alpine/basic-app-table`
+- `TanStack/table:packages/alpine-table/src/createTableHook.ts`