From 9b126a87d70d88f2bfdc096d4e5c98c2ed6d2285 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <98355961+LadyBluenotes@users.noreply.github.com>
Date: Wed, 4 Mar 2026 10:41:14 -0800
Subject: [PATCH 1/2] feat: add tanstack/intent blog post
---
.../from-docs-to-agents/diagram-discovery.svg | 90 +++++++++++
.../from-docs-to-agents/diagram-lifecycle.svg | 95 ++++++++++++
.../diagram-split-brain.svg | 63 ++++++++
.../diagram-status-quo.svg | 75 ++++++++++
src/blog/from-docs-to-agents.md | 141 ++++++++++++++++++
5 files changed, 464 insertions(+)
create mode 100644 public/blog-assets/from-docs-to-agents/diagram-discovery.svg
create mode 100644 public/blog-assets/from-docs-to-agents/diagram-lifecycle.svg
create mode 100644 public/blog-assets/from-docs-to-agents/diagram-split-brain.svg
create mode 100644 public/blog-assets/from-docs-to-agents/diagram-status-quo.svg
create mode 100644 src/blog/from-docs-to-agents.md
diff --git a/public/blog-assets/from-docs-to-agents/diagram-discovery.svg b/public/blog-assets/from-docs-to-agents/diagram-discovery.svg
new file mode 100644
index 000000000..e00a77f6d
--- /dev/null
+++ b/public/blog-assets/from-docs-to-agents/diagram-discovery.svg
@@ -0,0 +1,90 @@
+
diff --git a/public/blog-assets/from-docs-to-agents/diagram-lifecycle.svg b/public/blog-assets/from-docs-to-agents/diagram-lifecycle.svg
new file mode 100644
index 000000000..8049702e9
--- /dev/null
+++ b/public/blog-assets/from-docs-to-agents/diagram-lifecycle.svg
@@ -0,0 +1,95 @@
+
diff --git a/public/blog-assets/from-docs-to-agents/diagram-split-brain.svg b/public/blog-assets/from-docs-to-agents/diagram-split-brain.svg
new file mode 100644
index 000000000..afd854ab5
--- /dev/null
+++ b/public/blog-assets/from-docs-to-agents/diagram-split-brain.svg
@@ -0,0 +1,63 @@
+
diff --git a/public/blog-assets/from-docs-to-agents/diagram-status-quo.svg b/public/blog-assets/from-docs-to-agents/diagram-status-quo.svg
new file mode 100644
index 000000000..887e4dc2f
--- /dev/null
+++ b/public/blog-assets/from-docs-to-agents/diagram-status-quo.svg
@@ -0,0 +1,75 @@
+
diff --git a/src/blog/from-docs-to-agents.md b/src/blog/from-docs-to-agents.md
new file mode 100644
index 000000000..8013b661e
--- /dev/null
+++ b/src/blog/from-docs-to-agents.md
@@ -0,0 +1,141 @@
+---
+title: "From Docs to Agents: Shipping Knowledge That Travels With Your Package"
+published: 2026-03-04
+authors:
+ - Sarah Gerrard
+ - Kyle Matthews
+---
+
+Your docs are good. Your types are solid. Your agent still gets it wrong.
+
+Not because it's dumb — because there's no pipeline between what you know about your tool and what agents know about your tool. Docs are written for humans who browse. Types check individual API calls but can't encode intent. Training data is a snapshot of the ecosystem as it *was*, mixing versions without flagging which one applies. The knowledge gap between your tool and agents using your tool isn't a content problem. It's a lifecycle problem.
+
+## Skills as side quests
+
+The ecosystem is already moving toward agent-readable knowledge. Cursor rules, CLAUDE.md files, skills directories — the idea that agents need more than docs and types has landed. But the delivery mechanism hasn't caught up.
+
+Right now, if you want your agent to understand TanStack Router, you go find a community-maintained rules file in some GitHub repo. Maybe it's in `awesome-cursorrules`. Maybe someone linked it in Discord. You copy it into your project's `.cursorrules` or `CLAUDE.md`. Then you do the same for TanStack Query. And TanStack Table. Each one sourced from a different place, written by a different person, at a different point in time.
+
+Now multiply that across every tool in your stack. You're managing a pile of copy-pasted knowledge files with no versioning, no update mechanism, and no way to know when they've gone stale. Did TanStack Router ship a breaking change last week? Your rules file doesn't know. Is the Query skill you grabbed written for v4 or v5? Hope you checked.
+
+Finding skills is manual. Installing them is manual. Keeping them current is manual. And when they drift — and they always drift — you don't find out until your agent starts producing subtly wrong code again.
+
+Meanwhile, library maintainers already have the knowledge agents need. It lives in their docs, migration guides, "common mistakes" GitHub discussions, Discord answers. But none of it reaches agents through a channel the maintainer controls. The knowledge exists. What's missing is a delivery mechanism tied to the package itself — not scattered across the ecosystem.
+
+
+
+## Introducing `@tanstack/intent`
+
+`@tanstack/intent` is the missing lifecycle layer. It's a toolkit for generating, discovering, and maintaining skills for your library — and shipping them as npm packages so they travel with your code.
+
+```bash
+pnpm add -D @tanstack/intent
+```
+
+The core idea: **intents are npm packages of skills.** They encode how tools work together, what patterns apply for which goals, and what to avoid. Skills travel with the tool via `npm update`, not the model's training cutoff. Not community-maintained rules files in separate repos. Not prompt snippets in READMEs. Versioned knowledge the maintainer owns, shipped through npm, updated when the package updates.
+
+A skill is a focused projection of knowledge you already maintain — the critical constraint an agent must know, the anti-pattern flagged explicitly, the composition rule stated once and clearly. Each skill declares which docs it was derived from:
+
+```
+---
+name: tanstack-router-search-params
+description: Type-safe search param patterns for TanStack Router
+triggers:
+ - search params
+ - query params
+ - validateSearch
+metadata:
+ sources:
+ - docs/framework/react/guide/search-params.md
+---
+```
+
+That `metadata.sources` field is load-bearing. When those docs change, the CLI flags the skill for review. You're not maintaining two sources of truth — you're maintaining one, with a derived artifact that stays in sync.
+
+## Generating and validating skills
+
+You don't author skills from scratch. `intent scaffold` walks you through a guided workflow to generate skills for your library:
+
+```bash
+npx intent scaffold
+```
+
+The scaffold produces drafts you review, refine, and commit alongside your source code. Once you have skills, `intent validate` checks that your skill files are well-formed:
+
+```bash
+npx intent validate
+```
+
+And `intent setup` copies CI workflow templates into your repo so validation runs automatically on every push:
+
+```bash
+npx intent setup
+```
+
+This matters because the alternative is hoping model providers eventually re-train on your latest docs. That's not a strategy. Training data has a permanent version-mixing problem: once a breaking change ships, models contain *both* versions forever with no mechanism to disambiguate. Skills bypass this entirely. They're versioned with your package, and `npm update` brings the latest knowledge with the latest code.
+
+
+
+## The dependency graph does the discovery
+
+When a developer runs `intent init`, the CLI discovers every intent-enabled package in their project and wires the relevant skills into their agent configuration — CLAUDE.md, .cursorrules, whatever their tooling expects.
+
+```bash
+npx intent init
+```
+
+
+
+No manual setup per-library. No hunting for rules files. Install the package, run `intent init`, and the agent understands the tool. Update the package, and the skills update with it. Knowledge travels through the same channel as code.
+
+`intent list` shows you what's available:
+
+```bash
+npx intent list # See what's intent-enabled in your deps
+npx intent list --json # Machine-readable output
+```
+
+For library maintainers, `intent meta` surfaces meta-skills — higher-level guidance for how to author and maintain skills for your library:
+
+```bash
+npx intent meta
+```
+
+## From skills to playbooks
+
+A single skill helps an agent use one tool correctly. But real development is composition — routing *with* server state *with* a data grid *with* client-side storage. No individual skill covers how they fit together.
+
+Playbooks are the orchestration layer. A developer says "build a paginated data table with URL-synced filters" and the playbook knows which skills to load and how they compose — the search params skill, the loader/query integration skill, the table columnDefs skill, in the right order. Developer goals map to skill combinations.
+
+The more libraries in your stack that ship skills, the richer the composition story becomes.
+
+## Keeping it current
+
+The real risk with any derived artifact is staleness. You update your docs, ship a new API, and the skills silently drift. `@tanstack/intent` treats this as a first-class problem.
+
+`intent stale` checks your skills for version drift — flagging any that may have fallen behind their source material:
+
+```bash
+npx intent stale # Human-readable report
+npx intent stale --json # Machine-readable for CI
+```
+
+Run it in CI and you get a failing check when source material has changed. The skill becomes part of your release checklist — not something you remember to update, something your pipeline catches.
+
+
+
+The feedback loop runs both directions. `intent feedback` lets users submit structured reports when a skill produces incorrect output — which skill was active, which version, what went wrong. That context flows back to you as a maintainer, and the fix ships to everyone on the next `npm update`.
+
+```bash
+npx intent feedback
+```
+
+Skills that keep needing the same workaround are a signal. Sometimes the fix is a better skill. Sometimes it's a better API. A skill that dissolves because the tool absorbed its lesson is the system working as intended.
+
+## The new job
+
+Devtool makers have a new surface to maintain. You used to ship code, docs, and types. Now there's a fourth artifact: skills — knowledge encoded for the thing writing most of the code.
+
+The tools that invest here will produce developers who build confidently with them from day one. Not through tutorials. Not through toy projects. Through correct patterns absorbed in the context of their own real work.
+
+The lifecycle is: write your docs, generate skills, ship them with your package, validate and keep them current, learn from how they're used, make your tool better. Repeat.
\ No newline at end of file
From 370c2cb41d537ae31046e27cb536e4a54ebe6347 Mon Sep 17 00:00:00 2001
From: Kyle Mathews
Date: Wed, 4 Mar 2026 13:35:23 -0700
Subject: [PATCH 2/2] Copy-edit: tighten blog post prose (#740)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
* Tighten blog post prose with Strunk & White editing pass
Apply rigorous copy-editing: omit needless words, strengthen verbs,
use active voice, improve parallel construction, and cut flab
throughout the "From Docs to Agents" post.
Co-Authored-By: Claude Opus 4.6
* Second Strunk & White pass: deeper trims + fix author name
Cut remaining filler articles, weak futures, redundant context phrases,
and strengthened verb constructions. Fix "Matthews" → "Mathews".
Co-Authored-By: Claude Opus 4.6
* Rename init→install, Playbooks→Intents
Co-Authored-By: Claude Opus 4.6
* Restructure narrative: fix heading, move split-brain argument, flesh out intents, tighten closing
- Rename "Skills as side quests" → "The copy-paste era" to match section content
- Move the training-data version-mixing argument up into the intro section
where it hits harder, right after the core idea
- Add audience transition sentence between maintainer and consumer sections
- Add concrete YAML example to "From skills to intents" section
- Cut redundant lifecycle summary sentence from closing — end on the
strong "correct patterns absorbed in real work" line
- Fix all CLI commands to use `npx @tanstack/intent ` form
Co-Authored-By: Claude Opus 4.6
* ci: apply automated fixes
---------
Co-authored-by: Claude Opus 4.6
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
---
src/blog/from-docs-to-agents.md | 108 ++++++++++++++++++--------------
1 file changed, 60 insertions(+), 48 deletions(-)
diff --git a/src/blog/from-docs-to-agents.md b/src/blog/from-docs-to-agents.md
index 8013b661e..c237dfb5a 100644
--- a/src/blog/from-docs-to-agents.md
+++ b/src/blog/from-docs-to-agents.md
@@ -1,40 +1,44 @@
---
-title: "From Docs to Agents: Shipping Knowledge That Travels With Your Package"
+title: 'From Docs to Agents: Shipping Knowledge That Travels With Your Package'
published: 2026-03-04
authors:
- Sarah Gerrard
- - Kyle Matthews
+ - Kyle Mathews
---
Your docs are good. Your types are solid. Your agent still gets it wrong.
-Not because it's dumb — because there's no pipeline between what you know about your tool and what agents know about your tool. Docs are written for humans who browse. Types check individual API calls but can't encode intent. Training data is a snapshot of the ecosystem as it *was*, mixing versions without flagging which one applies. The knowledge gap between your tool and agents using your tool isn't a content problem. It's a lifecycle problem.
+Not because it's dumb — because nothing connects what you know about your tool to what agents know. 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 without flagging which applies. The gap isn't content. It's lifecycle.
-## Skills as side quests
+## The copy-paste era
-The ecosystem is already moving toward agent-readable knowledge. Cursor rules, CLAUDE.md files, skills directories — the idea that agents need more than docs and types has landed. But the delivery mechanism hasn't caught up.
+The ecosystem already moves toward agent-readable knowledge. Cursor rules, CLAUDE.md files, skills directories — everyone agrees agents need more than docs and types. But delivery hasn't caught up.
-Right now, if you want your agent to understand TanStack Router, you go find a community-maintained rules file in some GitHub repo. Maybe it's in `awesome-cursorrules`. Maybe someone linked it in Discord. You copy it into your project's `.cursorrules` or `CLAUDE.md`. Then you do the same for TanStack Query. And TanStack Table. Each one sourced from a different place, written by a different person, at a different point in time.
+Right now, if you want your agent to understand TanStack Router, you hunt for a community-maintained rules file in some GitHub repo. Maybe it's in `awesome-cursorrules`. Maybe someone linked it in Discord. You copy it into `.cursorrules` or `CLAUDE.md`. Then you repeat for TanStack Query. And TanStack Table. Each from a different place, a different author, a different point in time.
-Now multiply that across every tool in your stack. You're managing a pile of copy-pasted knowledge files with no versioning, no update mechanism, and no way to know when they've gone stale. Did TanStack Router ship a breaking change last week? Your rules file doesn't know. Is the Query skill you grabbed written for v4 or v5? Hope you checked.
+Multiply that across every tool in your stack. You're managing copy-pasted knowledge files with no versioning, no update path, and no staleness signal. Did TanStack Router ship a breaking change last week? Your rules file doesn't know. Is the Query skill you grabbed written for v4 or v5? Hope you checked.
-Finding skills is manual. Installing them is manual. Keeping them current is manual. And when they drift — and they always drift — you don't find out until your agent starts producing subtly wrong code again.
+Finding skills is manual. Installing them is manual. Keeping them current is manual. When they drift — and they always drift — you discover it only when your agent starts producing subtly wrong code.
-Meanwhile, library maintainers already have the knowledge agents need. It lives in their docs, migration guides, "common mistakes" GitHub discussions, Discord answers. But none of it reaches agents through a channel the maintainer controls. The knowledge exists. What's missing is a delivery mechanism tied to the package itself — not scattered across the ecosystem.
+Library maintainers already have the knowledge agents need — in docs, migration guides, "common mistakes" GitHub discussions, Discord answers. But none of it reaches agents through a channel the maintainer controls. The knowledge exists. The delivery mechanism doesn't.
## Introducing `@tanstack/intent`
-`@tanstack/intent` is the missing lifecycle layer. It's a toolkit for generating, discovering, and maintaining skills for your library — and shipping them as npm packages so they travel with your code.
+`@tanstack/intent` is the missing lifecycle layer — a toolkit for generating, discovering, and maintaining skills, shipped as npm packages that travel with your code.
```bash
pnpm add -D @tanstack/intent
```
-The core idea: **intents are npm packages of skills.** They encode how tools work together, what patterns apply for which goals, and what to avoid. Skills travel with the tool via `npm update`, not the model's training cutoff. Not community-maintained rules files in separate repos. Not prompt snippets in READMEs. Versioned knowledge the maintainer owns, shipped through npm, updated when the package updates.
+The core idea: **intents are npm packages of skills.** They encode how tools compose, which patterns fit which goals, and what to avoid. Skills 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.
-A skill is a focused projection of knowledge you already maintain — the critical constraint an agent must know, the anti-pattern flagged explicitly, the composition rule stated once and clearly. Each skill declares which docs it was derived from:
+This matters because the alternative — hoping model providers re-train on your latest docs — is not a strategy. Training data has a permanent version-mixing problem: once a breaking change ships, models contain _both_ versions forever with no way to disambiguate. Skills bypass this. They're versioned with your package, and `npm update` brings the latest knowledge with the latest code.
+
+
+
+A skill is a focused projection of knowledge you already maintain: the critical constraint, the flagged anti-pattern, the composition rule stated once and clearly. Each declares its source docs:
```
---
@@ -50,92 +54,100 @@ metadata:
---
```
-That `metadata.sources` field is load-bearing. When those docs change, the CLI flags the skill for review. You're not maintaining two sources of truth — you're maintaining one, with a derived artifact that stays in sync.
+That `metadata.sources` field is load-bearing. When those docs change, the CLI flags the skill for review. One source of truth, one derived artifact that stays in sync.
## Generating and validating skills
-You don't author skills from scratch. `intent scaffold` walks you through a guided workflow to generate skills for your library:
+You don't author skills from scratch. `@tanstack/intent scaffold` generates them from your library:
```bash
-npx intent scaffold
+npx @tanstack/intent scaffold
```
-The scaffold produces drafts you review, refine, and commit alongside your source code. Once you have skills, `intent validate` checks that your skill files are well-formed:
+The scaffold produces drafts you review, refine, and commit. Once committed, `@tanstack/intent validate` checks that they're well-formed:
```bash
-npx intent validate
+npx @tanstack/intent validate
```
-And `intent setup` copies CI workflow templates into your repo so validation runs automatically on every push:
+`@tanstack/intent setup` copies CI workflow templates into your repo so validation runs on every push:
```bash
-npx intent setup
+npx @tanstack/intent setup
```
-This matters because the alternative is hoping model providers eventually re-train on your latest docs. That's not a strategy. Training data has a permanent version-mixing problem: once a breaking change ships, models contain *both* versions forever with no mechanism to disambiguate. Skills bypass this entirely. They're versioned with your package, and `npm update` brings the latest knowledge with the latest code.
-
-
-
## The dependency graph does the discovery
-When a developer runs `intent init`, the CLI discovers every intent-enabled package in their project and wires the relevant skills into their agent configuration — CLAUDE.md, .cursorrules, whatever their tooling expects.
+That's the maintainer side. For developers using those libraries, the experience is simpler.
+
+When a developer runs `@tanstack/intent install`, the CLI discovers every intent-enabled package and wires skills into the agent configuration — CLAUDE.md, .cursorrules, whatever the tooling expects.
```bash
-npx intent init
+npx @tanstack/intent install
```
-
+
-No manual setup per-library. No hunting for rules files. Install the package, run `intent init`, and the agent understands the tool. Update the package, and the skills update with it. Knowledge travels through the same channel as code.
+No per-library setup. No hunting for rules files. Install the package, run `@tanstack/intent install`, and the agent understands the tool. Update the package, and skills update too. Knowledge travels the same channel as code.
-`intent list` shows you what's available:
+`@tanstack/intent list` shows you what's available:
```bash
-npx intent list # See what's intent-enabled in your deps
-npx intent list --json # Machine-readable output
+npx @tanstack/intent list # See what's intent-enabled in your deps
+npx @tanstack/intent list --json # Machine-readable output
```
-For library maintainers, `intent meta` surfaces meta-skills — higher-level guidance for how to author and maintain skills for your library:
+For library maintainers, `@tanstack/intent meta` surfaces meta-skills — higher-level guidance on authoring and maintaining skills:
```bash
-npx intent meta
+npx @tanstack/intent meta
```
-## From skills to playbooks
+## From skills to intents
-A single skill helps an agent use one tool correctly. But real development is composition — routing *with* server state *with* a data grid *with* client-side storage. No individual skill covers how they fit together.
+A single skill helps an agent use one tool correctly. Real development demands composition — routing _with_ server state _with_ a data grid _with_ client-side storage. No single skill covers how they fit together.
-Playbooks are the orchestration layer. A developer says "build a paginated data table with URL-synced filters" and the playbook knows which skills to load and how they compose — the search params skill, the loader/query integration skill, the table columnDefs skill, in the right order. Developer goals map to skill combinations.
+Intents are the orchestration layer. A developer says "build a paginated data table with URL-synced filters" and the intent loads the right skills in the right order:
-The more libraries in your stack that ship skills, the richer the composition story becomes.
+```
+---
+name: paginated-data-table
+description: URL-synced paginated data table with TanStack Router, Query, and Table
+skills:
+ - tanstack-router-search-params
+ - tanstack-query-loader-integration
+ - tanstack-table-column-defs
+ - tanstack-table-pagination
+---
+```
+
+Developer goals map to skill combinations. The more libraries in your stack that ship skills, the richer composition becomes.
## Keeping it current
-The real risk with any derived artifact is staleness. You update your docs, ship a new API, and the skills silently drift. `@tanstack/intent` treats this as a first-class problem.
+The real risk with any derived artifact is staleness. You update your docs, ship a new API, and skills silently drift. `@tanstack/intent` treats staleness as a first-class problem.
-`intent stale` checks your skills for version drift — flagging any that may have fallen behind their source material:
+`@tanstack/intent stale` checks for version drift, flagging skills that have fallen behind their sources:
```bash
-npx intent stale # Human-readable report
-npx intent stale --json # Machine-readable for CI
+npx @tanstack/intent stale # Human-readable report
+npx @tanstack/intent stale --json # Machine-readable for CI
```
-Run it in CI and you get a failing check when source material has changed. The skill becomes part of your release checklist — not something you remember to update, something your pipeline catches.
+Run it in CI and you get a failing check when sources change. Skills become part of your release checklist — not something you remember to update, but something your pipeline catches.
-The feedback loop runs both directions. `intent feedback` lets users submit structured reports when a skill produces incorrect output — which skill was active, which version, what went wrong. That context flows back to you as a maintainer, and the fix ships to everyone on the next `npm update`.
+The feedback loop runs both directions. `@tanstack/intent feedback` lets users submit structured reports when a skill produces wrong output — which skill, which version, what broke. That context flows back to you, and the fix ships to everyone on the next `npm update`.
```bash
-npx intent feedback
+npx @tanstack/intent feedback
```
-Skills that keep needing the same workaround are a signal. Sometimes the fix is a better skill. Sometimes it's a better API. A skill that dissolves because the tool absorbed its lesson is the system working as intended.
+Skills that keep needing the same workaround signal a deeper problem. Sometimes the fix is a better skill. Sometimes it's a better API. A skill that dissolves because the tool absorbed its lesson is the system working.
## The new job
-Devtool makers have a new surface to maintain. You used to ship code, docs, and types. Now there's a fourth artifact: skills — knowledge encoded for the thing writing most of the code.
-
-The tools that invest here will produce developers who build confidently with them from day one. Not through tutorials. Not through toy projects. Through correct patterns absorbed in the context of their own real work.
+Devtool makers have a new surface to maintain. You shipped code, docs, and types. Now there's a fourth artifact: skills — knowledge encoded for the thing writing most of your code.
-The lifecycle is: write your docs, generate skills, ship them with your package, validate and keep them current, learn from how they're used, make your tool better. Repeat.
\ No newline at end of file
+Tools that invest here produce developers who build confidently from day one — not through tutorials or toy projects, but through correct patterns absorbed in real work.