You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
update Intent copy to reference Agent Skills (#745)
* update Intent copy to reference Agent Skills directly
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* rewrite blog post: copy-edited prose, Agent Skills framing, correct CLI commands
- Apply copy edits from PR 740 (which landed on ts-intent, not main)
- Update title to reference Agent Skills
- Link to agentskills.io, remove "intents" as grouping noun
- Fix all CLI commands (setup-github-actions, remove pnpm add)
- Cut premature "From skills to intents" section
- Add maintainer-focused "Try it out" closing with DB PR link
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* tighten blog post prose (Strunk & White pass)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* enrich blog post: ecosystem adoption, center/frontier, concrete skill content, feedback loops
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* ci: apply automated fixes
* fix: simplify open standard line, remove React Router callout
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* update blog post header image
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* remove editorial sentence
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: restore paragraph break, move triggers into description per Agent Skills spec
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* replace load-bearing with clearer phrasing
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* update blog post header image
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
title: 'From Docs to Agents: Shipping Knowledge That Travels With Your Package'
2
+
title: 'Introducing TanStack Intent: Ship Agent Skills with Your npm Packages'
3
3
published: 2026-03-04
4
4
authors:
5
5
- Sarah Gerrard
@@ -10,128 +10,141 @@ authors:
10
10
11
11
Your docs are good. Your types are solid. Your agent still gets it wrong.
12
12
13
-
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.
13
+
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 with no way to tell which applies. The gap isn't content. It's lifecycle.
14
14
15
-
## Skills as side quests
15
+
## The copy-paste era
16
16
17
-
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.
17
+
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.
18
18
19
-
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.
19
+
Today, if you want your agent to understand TanStack Router, you hunt for a community-maintained rules file on GitHub. 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, author, and point in time.
20
20
21
-
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.
21
+
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 that Query skill written for v4 or v5? Hope you checked.
22
22
23
-
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.
23
+
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 produces subtly wrong code.
24
24
25
-
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.
25
+
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.
26
26
27
27
28
28
29
29
## Introducing `@tanstack/intent`
30
30
31
-
`@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.
31
+
`@tanstack/intent` is a CLI for library maintainers to generate, validate, and ship [Agent Skills](https://agentskills.io) alongside their npm packages. Agent Skills is an open standard already adopted by VS Code, GitHub Copilot, OpenAI Codex, Cursor, Claude Code, Goose, Amp, and others.
32
32
33
-
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.
33
+
**Skills ship inside your npm package.** They encode how your tool works, 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.
34
34
35
-
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:
35
+
Agents handle popular, stable libraries well — React, Express, Tailwind. Training data is saturated with correct usage. But at the frontier — new tools, major version transitions, novel compositions across packages — agents hallucinate, confuse versions, and miss critical implications. The frontier is bigger than it sounds: every new library, every breaking change, every composition across tools that nobody has written about. And once a breaking change ships, models don't "catch up." They develop a permanent split-brain — training data contains _both_ versions forever with no way to disambiguate. Skills bypass this. They're pinned to the installed version.
36
+
37
+
38
+
39
+
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:
36
40
37
41
```
38
42
---
39
43
name: tanstack-router-search-params
40
-
description: Type-safe search param patterns for TanStack Router
41
-
triggers:
42
-
- search params
43
-
- query params
44
-
- validateSearch
44
+
description: Type-safe search param patterns for TanStack Router. Use when working with search params, query params, or validateSearch.
45
45
metadata:
46
46
sources:
47
47
- docs/framework/react/guide/search-params.md
48
48
---
49
49
```
50
50
51
-
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.
51
+
Inside the skill, you write what the agent needs to get right — including what NOT to do:
52
+
53
+
```markdown
54
+
## Search Params
55
+
56
+
Use `validateSearch` to define type-safe search params on a route:
57
+
58
+
const Route = createFileRoute('/products')({
59
+
validateSearch: z.object({
60
+
page: z.number().default(1),
61
+
filter: z.string().optional(),
62
+
}),
63
+
})
64
+
65
+
## Common Mistakes
66
+
67
+
❌ Don't access search params via `window.location` — use
That `metadata.sources` field is what keeps skills current. When those docs change, the CLI flags the skill for review. One source of truth, one derived artifact that stays in sync.
52
75
53
76
## Generating and validating skills
54
77
55
-
You don't author skills from scratch. `@tanstack/intent scaffold`walks you through a guided workflow to generate skills for your library:
78
+
You don't author skills from scratch. `@tanstack/intent scaffold`generates them from your library:
56
79
57
80
```bash
58
81
npx @tanstack/intent scaffold
59
82
```
60
83
61
-
The scaffold produces drafts you review, refine, and commit alongside your source code. Once you have skills, `@tanstack/intent validate` checks that your skill files are well-formed:
84
+
The scaffold produces drafts you review, refine, and commit. Once committed, `@tanstack/intent validate` checks that they're well-formed:
62
85
63
86
```bash
64
87
npx @tanstack/intent validate
65
88
```
66
89
67
-
And `@tanstack/intent setup-github-actions` copies CI workflow templates into your repo so validation runs automatically on every push:
90
+
`@tanstack/intent setup-github-actions` copies CI workflow templates into your repo so validation runs on every push:
68
91
69
92
```bash
70
93
npx @tanstack/intent setup-github-actions
71
94
```
72
95
73
-
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.
74
-
75
-
76
-
77
96
## The dependency graph does the discovery
78
97
79
-
When a developer runs `@tanstack/intent install`, 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.
98
+
That's the maintainer side. For developers, the experience is simpler.
99
+
100
+
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.
80
101
81
102
```bash
82
103
npx @tanstack/intent install
83
104
```
84
105
85
-
106
+
86
107
87
-
No manual setup per-library. No hunting for rules files. Install the package, run `@tanstack/intent install`, and the agent understands the tool. Update the package, and the skills update with it. Knowledge travels through the same channel as code.
108
+
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.
88
109
89
-
`@tanstack/intent list` shows you what's available:
110
+
`@tanstack/intent list` shows what's available:
90
111
91
112
```bash
92
113
npx @tanstack/intent list # See what's intent-enabled in your deps
93
114
npx @tanstack/intent list --json # Machine-readable output
94
115
```
95
116
96
-
For library maintainers, `@tanstack/intent meta` surfaces meta-skills — higher-level guidance for how to author and maintain skills for your library:
117
+
For library maintainers, `@tanstack/intent meta` surfaces meta-skills — higher-level guidance on authoring and maintaining skills:
97
118
98
119
```bash
99
120
npx @tanstack/intent meta
100
121
```
101
122
102
-
## From skills to playbooks
103
-
104
-
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.
105
-
106
-
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.
107
-
108
-
The more libraries in your stack that ship skills, the richer the composition story becomes.
109
-
110
123
## Keeping it current
111
124
112
-
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.
125
+
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.
113
126
114
-
`@tanstack/intent stale` checks your skills for version drift — flagging any that may have fallen behind their source material:
127
+
`@tanstack/intent stale` checks for version drift, flagging skills that have fallen behind their sources:
115
128
116
129
```bash
117
130
npx @tanstack/intent stale # Human-readable report
118
131
npx @tanstack/intent stale --json # Machine-readable for CI
119
132
```
120
133
121
-
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.
134
+
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.
122
135
123
136
124
137
125
-
The feedback loop runs both directions. `@tanstack/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`.
138
+
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 as a maintainer, and the fix ships to everyone on the next `npm update`. Every support interaction produces an artifact that prevents the same problem for all future users — not just the one who reported it.
126
139
127
140
```bash
128
141
npx @tanstack/intent feedback
129
142
```
130
143
131
-
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.
144
+
A skill that persists forever means the tool has a design gap it should close. A skill that disappears because the tool absorbed its lesson is the system working exactly as intended.
132
145
133
146
## Try it out
134
147
135
-
We've started rolling out skills in [TanStack DB](https://github.com/TanStack/db/pull/1330) with other TanStack libraries following. If you maintain a library, tell your coding agent to run `npx @tanstack/intent scaffold` and let us know how it goes. We're looking for feedback on the authoring workflow, the skill format, and what's missing. File issues on [GitHub](https://github.com/TanStack/intent) or find us on [Discord](https://tlinz.com/discord).
148
+
We've started rolling out skills in [TanStack DB](https://github.com/TanStack/db/pull/1330) with other TanStack libraries following. If you maintain a library, tell your coding agent to run `npx @tanstack/intent scaffold` and let us know how it goes. We want feedback on the authoring workflow, the skill format, and what's missing. File issues on [GitHub](https://github.com/TanStack/intent) or find us on [Discord](https://tlinz.com/discord).
136
149
137
-
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.
150
+
The lifecycle: write your docs, generate skills, ship them with your package, validate and keep them current, learn from usage, improve your tool. Repeat.
tagline: 'Developer Infrastructure for AI-Ready Libraries',
592
+
tagline: 'Ship Agent Skills with Your npm Packages',
593
593
description:
594
-
"A toolkit for shipping composable, agent-readable knowledge alongside your npm packages. Automatic discovery from node_modules, distributed architecture where skills live in each library's repo, and seamless compatibility across package managers.",
594
+
"Generate, validate, and ship Agent Skills alongside your library — versioned knowledge that agents discover automatically from node_modules. Skills live in each library's repo and update when the package updates.",
![autofix-ci[bot]](https://avatars.githubusercontent.com/in/243519?v=4&size=40){kind=avatar}
0 commit comments