Skip to content

Commit b80f2d2

Browse files
KyleAMathewsKyleAMathews
committed
Merge remote-tracking branch 'origin/main' into feat/feedback-skills-inventory
2 parents 1e8d2cd + b1b56de commit b80f2d2

6 files changed

Lines changed: 233 additions & 116 deletions

File tree

‎README.md‎

Lines changed: 103 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -1,88 +1,103 @@
1-
# @tanstack/intent
2-
3-
Ship compositional knowledge for AI coding agents alongside your npm packages.
4-
5-
## The problem
6-
7-
Your docs are good. Your types are solid. Your agent still gets it wrong.
8-
9-
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. Once a breaking change ships, models contain _both_ versions forever with no way to disambiguate.
10-
11-
The ecosystem already moves toward agent-readable knowledge — Cursor rules, CLAUDE.md files, skills directories. But delivery is stuck in copy-paste: hunt for a community-maintained rules file, paste it into your config, repeat for every tool. No versioning, no update path, no staleness signal.
12-
13-
## Skills: the fourth artifact
14-
15-
You ship code, docs, and types. Skills are the fourth artifact — knowledge encoded for the thing writing most of your code.
16-
17-
Skills are npm packages of knowledge — encoding how tools compose, which patterns fit which goals, and what to avoid. When a library ships skills using `@tanstack/intent`, that knowledge travels with the tool via `npm update` — not the model's training cutoff. Versioned knowledge the maintainer owns, updated when the package updates.
18-
19-
Each skill declares its source docs. When those docs change, the CLI flags the skill for review. One source of truth, one derived artifact that stays in sync.
20-
21-
## Quick Start
22-
23-
### For library consumers
24-
25-
Set up skill-to-task mappings in your project's agent config files (CLAUDE.md, .cursorrules, etc.):
26-
27-
```bash
28-
npx @tanstack/intent install
29-
```
30-
31-
No per-library setup. No hunting for rules files. Install the package, run `intent install`, and the agent understands the tool. Update the package, and skills update too.
32-
33-
List available skills from installed packages:
34-
35-
```bash
36-
npx @tanstack/intent list
37-
```
38-
39-
### For library maintainers
40-
41-
Generate skills for your library by telling your AI coding agent to run:
42-
43-
```bash
44-
npx @tanstack/intent scaffold
45-
```
46-
47-
This prints a prompt that walks the agent through domain discovery, skill tree generation, and skill creation — one step at a time with your review at each stage.
48-
49-
Validate your skill files:
50-
51-
```bash
52-
npx @tanstack/intent validate
53-
```
54-
55-
Check for skills that have fallen behind their sources:
56-
57-
```bash
58-
npx @tanstack/intent stale
59-
```
60-
61-
Copy CI workflow templates into your repo so validation and staleness checks run on every push:
62-
63-
```bash
64-
npx @tanstack/intent setup
65-
```
66-
67-
## Keeping skills current
68-
69-
The real risk with any derived artifact is staleness. `intent stale` flags skills whose source docs have changed, and CI templates catch drift before it ships.
70-
71-
The feedback loop runs both directions. `intent feedback` lets users submit structured reports when a skill produces wrong output — which skill, which version, what broke. That context flows back to the maintainer, and the fix ships to everyone on the next `npm update`.
72-
73-
## CLI Commands
74-
75-
| Command | Description |
76-
| ----------------------- | --------------------------------------------------- |
77-
| `intent install` | Set up skill-to-task mappings in agent config files |
78-
| `intent list [--json]` | Discover intent-enabled packages |
79-
| `intent meta` | List meta-skills for library maintainers |
80-
| `intent scaffold` | Print the guided skill generation prompt |
81-
| `intent validate [dir]` | Validate SKILL.md files |
82-
| `intent setup` | Copy CI templates, generate shim, create labels |
83-
| `intent stale [--json]` | Check skills for version drift |
84-
| `intent feedback` | Submit skill feedback |
85-
86-
## License
87-
88-
[MIT](./LICENSE)
1+
<div align="center">
2+
<img src="./media/header_intent.png" >
3+
</div>
4+
5+
<br />
6+
7+
<div align="center">
8+
<a href="https://www.npmjs.com/package/@tanstack/intent" target="\_parent">
9+
<img alt="" src="https://img.shields.io/npm/dm/@tanstack/intent.svg" alt="npm downloads" />
10+
</a>
11+
- <a href="https://github.com/TanStack/intent" target="\_parent">
12+
<img alt="" src="https://img.shields.io/github/stars/TanStack/intent.svg?style=social&label=Star" alt="GitHub stars" />
13+
</a>
14+
<a href="https://bundlephobia.com/result?p=@tanstack/react-intent@latest" target="\_parent">
15+
<img alt="" src="https://badgen.net/bundlephobia/minzip/@tanstack/react-intent@latest" alt="Bundle size" />
16+
</a>
17+
</div>
18+
19+
<div align="center">
20+
<a href="#badge">
21+
<img alt="semantic-release" src="https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg">
22+
</a>
23+
<a href="#badge">
24+
<img src="https://img.shields.io/github/v/release/tanstack/intent" alt="Release"/>
25+
</a>
26+
<a href="https://twitter.com/tan_stack">
27+
<img src="https://img.shields.io/twitter/follow/tan_stack.svg?style=social" alt="Follow @TanStack"/>
28+
</a>
29+
</div>
30+
31+
<div align="center">
32+
33+
### [Become a Sponsor!](https://github.com/sponsors/tannerlinsley/)
34+
35+
</div>
36+
37+
# TanStack Intent
38+
39+
A CLI for library maintainers to generate, validate, and ship [Agent Skills](https://agentskills.io) alongside their npm packages. Auto-discovered, versioned with your code, and compatible with the open Agent Skills standard.
40+
41+
### <a href="https://tanstack.com/intent">Read the docs →</b></a>
42+
43+
## Get Involved
44+
45+
- We welcome issues and pull requests!
46+
- Participate in [GitHub discussions](https://github.com/TanStack/intent/discussions)
47+
- Chat with the community on [Discord](https://discord.com/invite/WrRKjPJ)
48+
- See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup instructions
49+
50+
## Partners
51+
52+
<div align="center">
53+
54+
<table align="center">
55+
<tr>
56+
<td>
57+
<a href="https://www.coderabbit.ai/?via=tanstack&dub_id=aCcEEdAOqqutX6OS" >
58+
<picture>
59+
<source media="(prefers-color-scheme: dark)" srcset="https://tanstack.com/assets/coderabbit-dark-D643Zkrv.svg" height="40" />
60+
<source media="(prefers-color-scheme: light)" srcset="https://tanstack.com/assets/coderabbit-light-CIzGLYU_.svg" height="40" />
61+
<img src=https://tanstack.com/assets/coderabbit-light-CIzGLYU_.svg" height="40" alt="CodeRabbit" />
62+
</picture>
63+
</a>
64+
</td>
65+
<td>
66+
<a href="https://www.cloudflare.com?utm_source=tanstack">
67+
<picture>
68+
<source media="(prefers-color-scheme: dark)" srcset=https://tanstack.com/assets/cloudflare-white-Co-Tyjbl.svg" height="60" />
69+
<source media="(prefers-color-scheme: light)" srcset="https://tanstack.com/assets/cloudflare-black-6Ojsn8yh.svg" height="60" />
70+
<img src="https://tanstack.com/assets/cloudflare-black-6Ojsn8yh.svg" height="60" alt="Cloudflare" />
71+
</picture>
72+
</a>
73+
</td>
74+
</tr>
75+
</table>
76+
77+
<div align="center">
78+
<img src="./media/partner_logo.svg" alt="Intent & you?" height="65">
79+
<p>
80+
We're looking for TanStack Intent Partners to join our mission! Partner with us to push the boundaries of TanStack intent and build amazing things together.
81+
</p>
82+
<a href="mailto:partners@tanstack.com?subject=TanStack Intent Partnership"><b>LET'S CHAT</b></a>
83+
</div>
84+
85+
</div>
86+
87+
## Explore the TanStack Ecosystem
88+
89+
- <a href="https://github.com/tanstack/config"><b>TanStack Config</b></a> – Tooling for JS/TS packages
90+
- <a href="https://github.com/tanstack/db"><b>TanStack DB</b></a> – Reactive sync client store
91+
- <a href="https://github.com/tanstack/devtools"><b>TanStack DevTools</b></a> – Unified devtools panel
92+
- <a href="https://github.com/tanstack/form"><b>TanStack Form</b></a> – Type‑safe form state
93+
- <a href="https://github.com/tanstack/query"><b>TanStack Query</b></a> – Async state & caching
94+
- <a href="https://github.com/tanstack/ranger"><b>TanStack Ranger</b></a> – Range & slider primitives
95+
- <a href="https://github.com/tanstack/router"><b>TanStack Router</b></a> – Type‑safe routing, caching & URL state
96+
- <a href="https://github.com/tanstack/router"><b>TanStack Start</b></a> – Full‑stack SSR & streaming
97+
- <a href="https://github.com/tanstack/store"><b>TanStack Store</b></a> – Reactive data store
98+
- <a href="https://github.com/tanstack/table"><b>TanStack Table</b></a> – Headless datagrids
99+
- <a href="https://github.com/tanstack/virtual"><b>TanStack Virtual</b></a> – Virtualized rendering
100+
101+
… and more at <a href="https://tanstack.com"><b>TanStack.com »</b></a>
102+
103+
<!-- USE THE FORCE LUKE -->

‎docs/config.json‎

Lines changed: 0 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -12,14 +12,6 @@
1212
{
1313
"label": "Overview",
1414
"to": "overview"
15-
},
16-
{
17-
"label": "Installation",
18-
"to": "installation"
19-
},
20-
{
21-
"label": "Quick Start",
22-
"to": "quick-start"
2315
}
2416
]
2517
}

‎docs/overview.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
---
2+
title: Overview
3+
---
4+
5+
`@tanstack/intent` is a CLI for library maintainers to generate, validate, and ship [Agent Skills](https://agentskills.io) alongside their npm packages.
6+
7+
## The problem
8+
9+
Your docs are good. Your types are solid. Your agent still gets it wrong.
10+
11+
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. Once a breaking change ships, models develop a permanent split-brain — training data contains _both_ versions forever with no way to disambiguate.
12+
13+
The ecosystem already moves toward agent-readable knowledge — Cursor rules, CLAUDE.md files, skills directories. But delivery is stuck in copy-paste: hunt for a community-maintained rules file, paste it into your config, repeat for every tool. No versioning, no update path, no staleness signal.
14+
15+
## Skills: versioned knowledge in npm
16+
17+
A skill is a short, versioned document that tells agents how to use a specific capability of your library — correct patterns, common mistakes, and when to apply them. Skills ship inside your npm package and 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.
18+
19+
Each skill declares its source docs. When those docs change, the CLI flags the skill for review. One source of truth, one derived artifact that stays in sync.
20+
21+
The [Agent Skills spec](https://agentskills.io) is an open standard already adopted by VS Code, GitHub Copilot, OpenAI Codex, Cursor, Claude Code, Goose, Amp, and others.
22+
23+
## For library consumers
24+
25+
Set up skill-to-task mappings in your project's agent config files (CLAUDE.md, .cursorrules, etc.):
26+
27+
```bash
28+
npx @tanstack/intent install
29+
```
30+
31+
No per-library setup. No hunting for rules files. Install the package, run `npx @tanstack/intent install`, and the agent understands the tool. Update the package, and skills update too.
32+
33+
List available skills from installed packages:
34+
35+
```bash
36+
npx @tanstack/intent list
37+
```
38+
39+
## For library maintainers
40+
41+
Generate skills for your library by telling your AI coding agent to run:
42+
43+
```bash
44+
npx @tanstack/intent scaffold
45+
```
46+
47+
This walks the agent through domain discovery, skill tree generation, and skill creation — one step at a time with your review at each stage.
48+
49+
Validate your skill files:
50+
51+
```bash
52+
npx @tanstack/intent validate
53+
```
54+
55+
Check for skills that have fallen behind their sources:
56+
57+
```bash
58+
npx @tanstack/intent stale
59+
```
60+
61+
Copy CI workflow templates into your repo so validation and staleness checks run on every push:
62+
63+
```bash
64+
npx @tanstack/intent setup-github-actions
65+
```
66+
67+
## Keeping skills current
68+
69+
The real risk with any derived artifact is staleness. `npx @tanstack/intent stale` flags skills whose source docs have changed, and CI templates catch drift before it ships.
70+
71+
The feedback loop runs both directions. `npx @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 the maintainer, and the fix ships to everyone on the next `npm update`. Every support interaction produces an artifact that prevents the same class of problem for all future users — not just the one who reported it.
72+
73+
## CLI Commands
74+
75+
| Command | Description |
76+
| --- | --- |
77+
| `npx @tanstack/intent install` | Set up skill-to-task mappings in agent config files |
78+
| `npx @tanstack/intent list [--json]` | Discover intent-enabled packages |
79+
| `npx @tanstack/intent meta` | List meta-skills for library maintainers |
80+
| `npx @tanstack/intent scaffold` | Print the guided skill generation prompt |
81+
| `npx @tanstack/intent validate [dir]` | Validate SKILL.md files |
82+
| `npx @tanstack/intent setup-github-actions` | Copy CI templates into your repo |
83+
| `npx @tanstack/intent stale [--json]` | Check skills for version drift |
84+
| `npx @tanstack/intent feedback` | Submit skill feedback |

‎media/header_intent.png‎

111 KB
Loading

‎media/partner_logo.svg‎

Lines changed: 26 additions & 0 deletions
Loading

0 commit comments

Comments
 (0)