@tanstack/intent 0.0.12 → 0.0.13

package/README.md

@@ -1,23 +1,23 @@
 # @tanstack/intent
 
-Ship compositional knowledge for AI coding agents alongside your npm packages.
+A CLI for library maintainers to generate, validate, and ship [Agent Skills](https://agentskills.io) alongside their npm packages.
 
 ## The problem
 
 Your docs are good. Your types are solid. Your agent still gets it wrong.
 
-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.
+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.
 
 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.
 
-## Skills: the fourth artifact
+## Skills: versioned knowledge in npm
 
-You ship code, docs, and types. Skills are the fourth artifact — knowledge encoded for the thing writing most of your code.
-
-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.
+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.
 
 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.
 
+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.
+
 ## Quick Start
 
 ### For library consumers
@@ -28,7 +28,7 @@ Set up skill-to-task mappings in your project's agent config files (CLAUDE.md, .
 npx @tanstack/intent install
 ```
 
-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.
+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.
 
 List available skills from installed packages:
 
@@ -44,7 +44,7 @@ Generate skills for your library by telling your AI coding agent to run:
 npx @tanstack/intent scaffold
 ```
 
-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.
+This walks the agent through domain discovery, skill tree generation, and skill creation — one step at a time with your review at each stage.
 
 Validate your skill files:
 
@@ -61,27 +61,27 @@ npx @tanstack/intent stale
 Copy CI workflow templates into your repo so validation and staleness checks run on every push:
 
 ```bash
-npx @tanstack/intent setup
+npx @tanstack/intent setup-github-actions
 ```
 
 ## Keeping skills current
 
 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.
 
-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`.
+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.
 
 ## CLI Commands
 
-| Command                               | Description                                         |
-| ------------------------------------- | --------------------------------------------------- |
-| `npx @tanstack/intent install`        | Set up skill-to-task mappings in agent config files |
-| `npx @tanstack/intent list [--json]`  | Discover intent-enabled packages                    |
-| `npx @tanstack/intent meta`           | List meta-skills for library maintainers            |
-| `npx @tanstack/intent scaffold`       | Print the guided skill generation prompt            |
-| `npx @tanstack/intent validate [dir]` | Validate SKILL.md files                             |
-| `npx @tanstack/intent setup`          | Copy CI templates, generate shim, create labels     |
-| `npx @tanstack/intent stale [--json]` | Check skills for version drift                      |
-| `npx @tanstack/intent feedback`       | Submit skill feedback                               |
+| Command                                     | Description                                         |
+| ------------------------------------------- | --------------------------------------------------- |
+| `npx @tanstack/intent install`              | Set up skill-to-task mappings in agent config files |
+| `npx @tanstack/intent list [--json]`        | Discover intent-enabled packages                    |
+| `npx @tanstack/intent meta`                 | List meta-skills for library maintainers            |
+| `npx @tanstack/intent scaffold`             | Print the guided skill generation prompt            |
+| `npx @tanstack/intent validate [dir]`       | Validate SKILL.md files                             |
+| `npx @tanstack/intent setup-github-actions` | Copy CI templates into your repo                    |
+| `npx @tanstack/intent stale [--json]`       | Check skills for version drift                      |
+| `npx @tanstack/intent feedback`             | Submit skill feedback                               |
 
 ## License
 

package/dist/cli.mjs

@@ -65,12 +65,33 @@ async function cmdList(args) {
 		for (const w of result.warnings) console.log(`  ⚠ ${w}`);
 	}
 }
-function cmdMeta() {
+function cmdMeta(args) {
 	const metaDir = getMetaDir();
 	if (!existsSync(metaDir)) {
 		console.error("Meta-skills directory not found.");
 		process.exit(1);
 	}
+	if (args.length > 0) {
+		const name = args[0];
+		if (name.includes("..") || name.includes("/") || name.includes("\\")) {
+			console.error(`Invalid meta-skill name: "${name}"`);
+			process.exit(1);
+		}
+		const skillFile = join(metaDir, name, "SKILL.md");
+		if (!existsSync(skillFile)) {
+			console.error(`Meta-skill "${name}" not found.`);
+			console.error(`Run \`npx @tanstack/intent meta\` to list available meta-skills.`);
+			process.exit(1);
+		}
+		try {
+			console.log(readFileSync(skillFile, "utf8"));
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			console.error(`Failed to read meta-skill "${name}": ${msg}`);
+			process.exit(1);
+		}
+		return;
+	}
 	const entries = readdirSync(metaDir, { withFileTypes: true }).filter((e) => e.isDirectory()).filter((e) => existsSync(join(metaDir, e.name, "SKILL.md")));
 	if (entries.length === 0) {
 		console.log("No meta-skills found.");
@@ -290,7 +311,7 @@ This produces: individual SKILL.md files.
 3. For each publishable package, run: \`npx @tanstack/intent add-library-bin\`
 4. For each publishable package, run: \`npx @tanstack/intent edit-package-json\`
 5. Ensure each package has \`@tanstack/intent\` as a devDependency
-6. Create a \`feedback:<skill-name>\` label on the GitHub repo for each skill (use \`gh label create\`)
+6. Create a \`skill:<skill-name>\` label on the GitHub repo for each skill (use \`gh label create\`)
 7. Add a README note: "If you use an AI agent, run \`npx @tanstack/intent install\`"
 `;
 	console.log(prompt);
@@ -299,7 +320,7 @@ const USAGE = `TanStack Intent CLI
 
 Usage:
   intent list [--json]           Discover intent-enabled packages
-  intent meta                    List meta-skills for maintainers
+  intent meta [name]             List meta-skills, or print one by name
   intent validate [<dir>]        Validate skill files (default: skills/)
   intent install                  Print a skill that guides your coding agent to set up skill-to-task mappings
   intent scaffold                Print maintainer scaffold prompt
@@ -314,7 +335,7 @@ switch (command) {
 		await cmdList(commandArgs);
 		break;
 	case "meta":
-		cmdMeta();
+		cmdMeta(commandArgs);
 		break;
 	case "validate":
 		cmdValidate(commandArgs);

package/dist/index.mjs

@@ -212,7 +212,7 @@ function submitMetaFeedback(payload, opts) {
 			"--title",
 			`Meta-Skill Feedback: ${payload.metaSkill} (${payload.userRating})`,
 			"--label",
-			`feedback:${payload.metaSkill}`,
+			`skill:${payload.metaSkill}`,
 			"--body",
 			"-"
 		], {

package/meta/feedback-collection/SKILL.md

@@ -29,7 +29,17 @@ can be improved.
 
 Review your own session transcript. No human interaction needed yet.
 
-### 1a: Gap detection
+### 1a: Skills inventory
+
+Before analyzing gaps and errors, inventory all skills that were available
+during the session:
+
+- **Loaded and used:** Skills you read and actively followed.
+- **Available but not loaded:** Skills that were installed (discoverable via
+  `intent list`) but you never read. This is important — many issues stem from
+  the agent not loading the right skill, not from the skill itself being wrong.
+
+### 1b: Gap detection
 
 Identify moments where the skill was silent and you had to bridge the gap
 yourself — via code reading, search, trial-and-error, or general knowledge.
@@ -40,7 +50,7 @@ For each gap, note:
 - What the skill should have told you
 - How you solved it (code reading, web search, guessing)
 
-### 1b: Error/correction tracking
+### 1c: Error/correction tracking
 
 Identify moments where the skill prescribed an approach that produced an error.
 
@@ -50,7 +60,7 @@ For each error, note:
 - The error or incorrect behavior that resulted
 - The fix you applied
 
-### 1c: Human intervention events
+### 1d: Human intervention events
 
 Identify moments where the human clarified, corrected, or overrode your approach.
 
@@ -60,7 +70,7 @@ For each intervention, note:
 - What the human said or changed
 - Whether the skill could have prevented this
 
-### 1d: Step duration anomalies
+### 1e: Step duration anomalies
 
 Identify steps that consumed disproportionate effort compared to their apparent
 complexity. These signal that the skill should provide a template, snippet, or
@@ -107,21 +117,31 @@ referenced.
 
 [one-sentence summary of what the human asked you to do]
 
+## Skills Inventory
+
+**Loaded and used:**
+
+- [list each skill the agent read and actively followed during the session]
+
+**Available but not loaded:**
+
+- [list skills that were installed/available but the agent never read]
+
 ## What Worked
 
 [patterns/instructions from the skill that were accurate and helpful]
 
 ## What Failed
 
-[from 1b — skill instructions that produced errors]
+[from 1c — skill instructions that produced errors]
 
 ## Missing
 
-[from 1a — gaps where the skill should have covered]
+[from 1b — gaps where the skill should have covered]
 
 ## Self-Corrections
 
-[from 1b fixes + 1c human interventions, combined]
+[from 1c fixes + 1d human interventions, combined]
 
 ## User Comments
 
@@ -136,10 +156,11 @@ referenced.
 | Package          | The npm package the skill lives in (e.g. `@tanstack/query-intent`) |
 | Skill version    | Frontmatter `metadata.version` or `library_version`                |
 | Task             | Summarize the human's original request in one sentence             |
+| Skills Inventory | Which skills were loaded vs. available but not loaded (see below)  |
 | What Worked      | List skill sections/patterns that were correct and useful          |
-| What Failed      | From 1b — skill instructions that produced errors                  |
-| Missing          | From 1a — gaps where the skill was silent                          |
-| Self-Corrections | From 1b fixes + 1c human interventions, combined                   |
+| What Failed      | From 1c — skill instructions that produced errors                  |
+| Missing          | From 1b — gaps where the skill was silent                          |
+| Self-Corrections | From 1c fixes + 1d human interventions, combined                   |
 | Rating           | From Phase 2 sentiment analysis or explicit rating                 |
 | User Comments    | From Phase 2 answers, keep brief                                   |
 
@@ -177,7 +198,7 @@ not contain project-specific details. Before submission:
 Submit directly as a GitHub issue:
 
 ```bash
-gh issue create --repo [owner/repo] --title "Skill Feedback: [skill-name] ([rating])" --label "feedback:[skill-name]" --body-file intent-feedback.md
+gh issue create --repo [owner/repo] --title "Skill Feedback: [skill-name] ([rating])" --label "skill:[skill-name]" --body-file intent-feedback.md
 ```
 
 If the label doesn't exist, omit the `--label` flag — don't let a missing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/intent",
-  "version": "0.0.12",
+  "version": "0.0.13",
   "description": "Ship compositional knowledge for AI coding agents alongside your npm packages",
   "license": "MIT",
   "type": "module",