Ship a marketplace plugin for skill discovery, resolving package-level skills first

[tombeckenham]

Problem

TanStack AI already ships Agent Skills inside its packages (@tanstack/ai → ai-core, @tanstack/ai-persistence → tanstack-ai-persistence + 8 sub-skills, @tanstack/ai-code-mode → ai-code-mode), and TanStack Intent wires them into an agent's config. Two gaps remain:

1. Discovery is pull-only. You have to already know the skills exist to run npx @tanstack/intent@latest install. Nothing surfaces them in the places people browse for agent tooling (Claude Code's /plugin marketplace, Cursor/Copilot equivalents).
2. Nothing tells you when your installed packages are behind. Skills travel with the package version. If an app installs @tanstack/ai-persistence@0.3 and the recipe for its stack only landed in 0.5, the agent silently follows stale guidance — or finds no skill at all and improvises Vercel-AI-SDK patterns, which is the exact failure the skills exist to prevent.

Proposal

1. A marketplace plugin for the repo

Add a .claude-plugin/marketplace.json (plus per-plugin manifests) at the root of TanStack/ai so the repo is installable as a plugin marketplace:

/plugin marketplace add TanStack/ai
/plugin install tanstack-ai

The plugin is a thin shell — it should not vendor copies of the skills. Duplicated skill text is the thing that goes stale; the whole point of shipping skills inside npm packages is that npm update updates the guidance. The plugin's job is discovery plus the resolution logic below.

Scope to settle in review:

• One plugin (tanstack-ai) vs one per package. One, most likely — the entry-point skills already route.
• Whether the marketplace also lists the maintainer-facing tooling already in this repo (.claude/skills/gap-analysis, triage-github), or keeps those out of the public listing.

2. Resolve package-level skills first

The plugin's entry point should look at the consuming project before contributing anything of its own:

1. Scan node_modules for packages carrying the tanstack-intent keyword and read their skills/*/SKILL.md. These win — they match the installed version.
2. If a package is present but ships no skill for the surface being asked about, say so and name the version that adds it: "@tanstack/ai-persistence@0.3 has no Drizzle recipe; it landed in 0.5 — upgrade, or read the skill at <url>."
3. If the relevant package isn't installed at all, suggest the install rather than guessing (pnpm add @tanstack/ai-persistence).
4. Only fall back to bundled/remote copies when nothing local resolves, and label it clearly as possibly-newer-than-your-install.

That ordering keeps a single source of truth (the package) and turns the plugin into a router plus a staleness detector.

3. Delegate the config write to Intent

Where the plugin needs to persist task→skill mappings, shell out to npx @tanstack/intent@latest install rather than reimplementing the AGENTS.md / CLAUDE.md / .cursorrules writers. Intent already handles multi-agent targets; the plugin should not fork that behaviour.

Why now

The persistence skills just moved from "here's how to build a publishable adapter package" to "here's how to write a chat-persistence.ts against the Drizzle/Prisma/D1/whatever setup this app already runs" — they read the consuming project and fit into it. That only pays off if agents actually load them, which today depends on the user having heard of intent install.

Open questions

• Does the plugin belong in TanStack/ai, or in a TanStack-wide marketplace repo alongside Router/Query/Start skills? A shared marketplace is better for discovery; a per-repo one keeps versioning aligned with the packages.
• Non-Claude agents: Cursor and Copilot have no equivalent marketplace. Is the plugin a Claude Code-specific discovery layer over an agent-neutral skill set, and is that acceptable?
• Should staleness detection be a one-shot check at install, a doctor-style command, or a check the entry-point skill runs each time it loads?