Ship Skills With Your Package: TanStack Intent + the Vercel Skills CLI

For two years we have all been fighting the same quiet bug. You ask an agent to wire up a router, set up a query cache, or configure a build tool, and it confidently writes code against an API that was deprecated three minor versions ago. The agent is not wrong on purpose. It learned the framework from a snapshot of the internet that froze at training time, and the framework kept moving. The gap between "what the model knows" and "what your package.json actually installed" is where most of the frustrating, hard-to-debug agent failures live.

There is a newer idea that fixes this at the source, and it is one of the most important shifts in how we distribute framework knowledge: ship the skill inside the package itself. Instead of an agent guessing how your library works from stale training data, the library ships a SKILL.md next to its compiled output, versioned with every release. When the library updates, the skill updates. When you pin a version, you pin the instructions too.

In this piece I want to walk you through the whole loop. We will start with the consumer-side fix — skilld, which generates version-aware skills from the dependencies you already have installed. Then we will flip to the maintainer side with TanStack Intent, which lets library authors scaffold and ship SKILL.md files inside their npm package. We will tie it together with the Vercel skills CLI (npx skills), the install layer that pushes any of this across 70+ agents. And we will look at how the Vue ecosystem — vuejs-ai/skills and Anthony Fu's antfu/skills — is already living in this model. By the end you should be able to both consume versioned skills and ship your own.

The staleness problem, stated precisely

Let me be specific about what breaks, because "the model is out of date" is too vague to act on.

A frontier model is trained on data up to some cutoff. After that date, three kinds of change accumulate that the model cannot see:

1. API surface changes. A function gets renamed, an option moves from positional to an options object, a hook splits into two, a default flips. The model writes the old shape and your linter or runtime complains.
2. Idiom changes. The API technically still works, but the community moved on. The maintainers now recommend a different pattern — server components instead of effects, suspense instead of loading flags, signals instead of refs. The model produces working-but-discouraged code.
3. New surface entirely. The library shipped a whole subsystem the model never saw. The agent cannot use what it does not know exists, so it reinvents a worse version by hand.

Notice that none of these are fixed by a bigger model or a longer context window alone. They are fixed by giving the agent the current truth at the moment it writes code. The question is only: where does that truth come from, and who is responsible for keeping it fresh?

There are two answers, and they are complementary rather than competing.

• Consumer-generated skills pull the truth from the packages you have installed, on your machine, right now. This is skilld.
• Maintainer-shipped skills put the truth in the package before it is published, so every consumer gets it for free. This is the TanStack Intent model.

Let me take them in that order.

skilld: version-aware skills from your installed dependencies

The cleanest way to understand skilld is this: it reads your node_modules and your lockfile, figures out exactly which versions of which libraries you depend on, and generates SKILL.md files grounded in those versions — pulling from the package's own docs, its release notes, and its GitHub issues.

The shift is subtle but enormous. A generic "how to use React Query" skill is written for a version that exists in someone's head. A skilld-generated skill is written for @tanstack/react-query@5.59.2 because that is the literal string in your lockfile. If a colleague on the same repo runs it, they get the same answer. If you bump the version next month, you regenerate and the skill moves with you.

Why release notes and issues matter as sources:

• Release notes capture the deltas the docs sometimes lag on — the "we changed this default in 5.50" note that never made it into the prose guide.
• GitHub issues capture the failure modes. The most-commented issues are usually the sharp edges: the gotcha that bites everyone, the migration footgun, the config that silently does nothing. An agent armed with that context avoids the trap instead of falling into it and then debugging its way out.

A skilld workflow looks like this:

# Generate skills from what you actually have installed
npx skilld generate

# It inspects package.json + lockfile, resolves versions,
# and writes version-pinned SKILL.md files into your skills dir

The output is not magic — it is a focused, version-stamped briefing the agent can load before it touches your code. I covered skilld on its own in depth, and if the consumer side is your main concern, start there. For the rest of this article I want to live on the other side of the npm registry: what happens when the maintainer takes responsibility for the skill.

The "skills ship with your package" model

Here is the mental model I want you to carry. Think about what already ships inside a modern npm package:

• Compiled JavaScript
• TypeScript declaration files (.d.ts)
• Source maps
• A README.md
• Sometimes a CHANGELOG.md

Every one of those is a form of machine- or human-readable documentation that travels with the code and is versioned with the code. The .d.ts files are the obvious precedent: they are instructions for the type checker, generated from the source, shipped in the tarball, and pinned to the exact version you installed. Nobody maintains a separate "types for version 5.x" repository that drifts out of sync, because that would be absurd. The types live with the code.

A SKILL.md is the same idea for the agent. It is instructions for the model — generated from the source and the docs, shipped in the tarball, pinned to the exact version. When you run npm install left-pad@3.0.0, you should be able to find, somewhere in that package, a file that tells an agent how to use left-pad 3.0.0 correctly.

The type checker gets .d.ts. The bundler gets exports maps. The human gets README.md. The agent gets SKILL.md. Same package, same version, four audiences. Once you see it this way, shipping a skill stops feeling exotic and starts feeling like a missing file.

This reframes the maintainer's job. You are no longer hoping a frontier lab scrapes your docs and learns your API correctly by next training run. You are publishing the correct usage as an artifact, on your release cadence, under your control.

Why versioned-with-release beats static

A static skill — one that lives in a community repo, or in a model's weights, or in a one-off gist — has a single fatal property: it has no idea which version of the library the user has. So it must either pick a version (and be wrong for everyone else) or stay vague (and be useless precisely when precision matters).

A skill versioned with the release inverts every one of those problems:

Property	Static / scraped skill	Shipped-with-package skill
Knows the installed version	No — must guess	Yes — it is the version
Updates when the library changes	Only on the next manual rewrite	Automatically, every release
Source of truth	A copy that drifts	The package itself
Migration coverage	Usually absent	Maintainer can encode "moving from 4 → 5"
Trust	Community goodwill	The same people who wrote the code
Distribution	Separate repo to discover	Already in your node_modules

The last row matters more than it looks. If the skill is in the package, then the install already happened. You do not have to discover, vet, and separately install a knowledge artifact. The moment npm install completes, the agent's guidance is on disk, at the right version, with zero additional steps. Distribution is solved by the registry you were already using.

TanStack Intent: scaffolding skills for maintainers

This is where TanStack Intent (@tanstack/intent) comes in. If skilld is the consumer pulling truth out of installed packages, Intent is the maintainer pushing truth into the package before it ships.

The core command is a scaffolder:

npx @tanstack/intent scaffold

Run it inside your library repo and it sets up the structure for authoring SKILL.md files that get bundled into your published package. The whole premise is that the people best positioned to write the agent's instructions are the maintainers — they know the API, they know which patterns they regret, they know exactly what changed in the last release because they are the ones who changed it.

What Intent gives a maintainer:

• A standard place for skills to live in the repo, so contributors know where to put them and reviewers know where to look.
• A scaffold so you are not inventing the SKILL.md frontmatter and layout from scratch — name, description, triggers, body.
• A versioning story tied to your existing release pipeline, so the skill is part of the package contents rather than an afterthought.
• A consumer-facing convention so that tools like the Vercel CLI and version-aware generators know where to find what you shipped.

What "scaffold" actually produces

When you scaffold, you are establishing three things in your repo:

1. The skill source files — one or more SKILL.md documents describing how to use your library correctly, written for the current version.
2. The packaging glue — making sure those files end up inside the published tarball (the files field in package.json, or the directory your build copies into dist).
3. The metadata — a manifest or frontmatter that names each skill and describes when an agent should reach for it.

The discipline Intent encourages is that you treat the skill as part of your public API. When you change the API, you change the skill in the same pull request, the same way a responsible maintainer updates the README and the migration guide in the same change. That co-location is the entire trick. A skill that lives in the PR that changed the behavior cannot drift, because the reviewer sees both at once.

Authoring well: what maintainers should put in the skill

The scaffold gives you a skeleton; the value is in what you fill it with. From watching good and bad examples, here is what separates a skill that actually changes agent behavior from one that just restates the README:

• Lead with the current idiom, not the history. The agent does not need a tour of how the API evolved. It needs the one correct way to do the common thing, today, in this version. Put that first.
• Encode the gotchas you answer in your issue tracker. Every maintainer has the five questions they answer over and over. Those are gold. Write them into the skill as "do this, not that" with a one-line reason.
• Be explicit about defaults and breaking changes. "As of 5.0 the default staleTime is X" is exactly the kind of fact a model cannot know and will get wrong. Pin it.
• Show runnable snippets in the version's real syntax. A code block the agent can copy and adapt is worth ten paragraphs of prose.
• Keep it tight. This loads into a context window. Ruthless relevance beats completeness. Link to the full docs for the long tail; the skill is the high-frequency core.

The Vercel skills CLI: the install layer

Generating and shipping skills is only half the system. The other half is getting them into whatever agent the developer is actually using — and there are a lot of agents now. This is the job of the Vercel skills CLI, the npx skills tool from vercel-labs/skills.

The CLI is the great equalizer. A skill is just a SKILL.md, but every coding agent has its own idea of where instructions should live and what format they take. The Vercel CLI knows the conventions for 70+ agents and installs your skill into the right place for each one, so you author once and run anywhere.

The basic verbs:

# Install a skill (or a whole repo's worth) from GitHub
npx skills add vercel-labs/skills

# Pull a community framework collection
npx skills add vuejs-ai/skills

# Grab everything in a repo with a glob
npx skills add antfu/skills --skill='*'

What makes this the connective tissue for the whole "ship with your package" idea:

• It is agent-agnostic. You do not write a Cursor version and a Claude Code version and a Windsurf version. You write a SKILL.md, and the CLI adapts it to each target's layout.
• It reads from GitHub and from packages. It can pull a skill straight from a repo, which is how community collections work, and it slots naturally into the package-shipped model because the skill is a plain file wherever it lives.
• It standardizes the install step so that "add this skill" is one predictable command no matter where the skill came from — a maintainer's package, a community repo, or your own generated set.

Kiro and automatic skill loading

A nice concrete example of how deep this integration goes: with Kiro, the CLI loads skills from .kiro/skills/ automatically. You drop the files in that directory and the agent picks them up without a manual registration step. That is the direction the whole ecosystem is heading — skills as a first-class, convention-based part of the workspace, discovered the way an editor discovers a .editorconfig or a tsconfig.json. No glue code, just a known location.

When every agent agrees on "look here for skills," and every package agrees on "ship the skill here," the two halves meet in the middle and the developer does nothing. That is the goal.

The full loop, end to end

Let me put the pieces in order so the architecture is clear.

1. A maintainer uses npx @tanstack/intent scaffold to author SKILL.md files inside their library repo, writes them against the current version, and ships them in the published package. The skill is now versioned with every release.
2. A consumer runs npm install and the skill arrives on disk, pinned to the exact version, with no extra step.
3. For libraries that have not shipped skills yet, the consumer runs skilld to generate version-aware skills from the installed packages — docs, release notes, issues — closing the gap until maintainers catch up.
4. The Vercel skills CLI (npx skills add ...) installs any of these — package-shipped, generated, or community — across 70+ agents, putting the right file in the right place for whichever tool the developer uses.
5. The agent loads the skill before writing code, and produces output that matches the version on disk instead of the version in its weights.

The beautiful property of this loop is that each piece degrades gracefully. If a library ships skills, great — you get them free. If it does not, skilld fills the gap. If your agent has a weird config, the Vercel CLI handles it. No single component has to be universal for the system to be useful today.

The Vue ecosystem is already living here

The clearest proof that this is not theoretical is the Vue ecosystem, which has leaned into community framework skill collections harder than most.

vuejs-ai/skills

The vuejs-ai/skills collection is a community-maintained set you install with:

npx skills add vuejs-ai/skills

Its headline skill, vue-best-practices, is exactly the kind of "idiom" guidance I described earlier — not just "here is the syntax" but "here is the way the Vue community actually wants you to write components today." It is the antidote to an agent producing technically-valid-but-dated Vue: Options API where Composition is preferred, reactivity footguns, the patterns that look fine and quietly cause re-render storms.

antfu/skills

Anthony Fu — who maintains a huge slice of the modern Vue and build-tooling world — ships antfu/skills, which you can pull wholesale:

npx skills add antfu/skills --skill='*'

The --skill='*' glob grabs the entire collection, which spans the tools he works on: Vue, Vite, Nuxt, Pinia, VueUse, and Vitest. That is essentially a full-stack Vue agent briefing from the person who builds those tools. The value of a maintainer-authored skill is at its peak here: when the author of VueUse tells the agent how to use VueUse, you are getting truth from the source, not a guess from a scrape.

These two collections show both flavors of the model in the wild:

• vuejs-ai/skills is a community collection — broad, idiom-focused, maintained by people close to the framework.
• antfu/skills is closer to maintainer-authored — narrow per tool, deep, authored by the person who owns the code.

Both install through the same npx skills CLI, which is the point: the install layer does not care where the skill came from, only that it is a SKILL.md.

Practical guidance: which path is yours?

Let me close the conceptual part with direct advice depending on who you are.

If you are a consumer and your dependencies do not ship skills yet:

• Run skilld to generate version-aware skills from your lockfile.
• Install community collections for your framework — vuejs-ai/skills, antfu/skills, or your stack's equivalent — via npx skills add.
• Regenerate after major version bumps. Treat it like updating your types: a routine step in the upgrade.

If you are a maintainer:

• Scaffold with npx @tanstack/intent scaffold and commit the skill into your repo.
• Add the skill file to your package's files array so it ships in the tarball.
• Make "update the skill" a checklist item in your release process, the same line as "update the changelog."
• Encode your top five most-answered support questions directly into the skill. You will deflect them at the source.

If you maintain a team's tooling:

• Standardize on the Vercel CLI so every developer installs skills the same way regardless of their editor.
• For Kiro users, rely on .kiro/skills/ auto-loading and check skill files into the repo so the whole team shares the same agent grounding.

A note on trust and responsibility

There is a governance dimension worth naming. When skills ship inside packages, the supply-chain question expands. A SKILL.md is not executable, but it is instructions you are feeding an agent that will then write and sometimes run code. A malicious or careless skill could nudge an agent toward insecure patterns just as a malicious dependency could ship bad code.

The reassuring part is that the same defenses apply. You already vet your dependencies; the skill travels with the dependency, under the same maintainer, with the same review surface. A skill shipped by the package author is exactly as trustworthy as the package itself — which is the whole reason the model works. The risk to watch is unofficial skill repos claiming to cover a framework. Prefer skills that come from the maintainer or a clearly community-endorsed collection, read them before you install them, and treat a glob install (--skill='*') from an unknown source with the same caution you would treat npm install of an unknown package.

This is the maturity curve every distribution mechanism walks. We learned it with npm packages, with VS Code extensions, with browser add-ons. Skills are early on that curve, and shipping them with the package — under the maintainer's name, in the maintainer's tarball — is the version of skill distribution with the strongest trust story, because it inherits the trust you already extended to the code.

Where this is heading

I think the endgame is that a SKILL.md becomes as ordinary a package artifact as a .d.ts. You will not think about it any more than you think about types today. You will npm install, and your agent will quietly become correct about that library at that version, and the friction we have all been absorbing — the deprecated calls, the dated idioms, the reinvented subsystems — will fade into the same category as "writing your own type definitions for an untyped package." A thing we used to do, now mostly handled.

The pieces to get there exist now. TanStack Intent gives maintainers the authoring path. The package registry gives the distribution path. The Vercel CLI gives the install path across every agent. And skilld covers the gap for everything that has not caught up yet. The work in front of us is mostly adoption: maintainers deciding the skill is part of the package, the same way they once decided the types were.

If you ship a library, you can start that today. Scaffold a skill, write down the five things you wish every agent knew about your API, and put it in your next release. Your users' agents will get smarter about your code the moment they update — and you will answer those five questions one last time.

Resources & links

External tools and repos:

• vercel-labs/skills — the npx skills CLI that installs skills across 70+ agents, including Kiro's .kiro/skills/ auto-loading.
• vuejs-ai/skills — community Vue collection with the vue-best-practices skill; install via npx skills add vuejs-ai/skills.
• antfu/skills — Anthony Fu's collection covering Vue, Vite, Nuxt, Pinia, VueUse, and Vitest; install via npx skills add antfu/skills --skill='*'.
• @tanstack/intent — npx @tanstack/intent scaffold to author and ship SKILL.md files inside your npm package.

Related skills on this site:

• skilld — generate version-aware skills from your installed npm dependencies.
• superpowers — a broad skill collection and a good reference for skill structure.
• context-engineering — the discipline of getting the right knowledge into the model at the right moment.
• agent-toolkit-aws — another example of distributing capability-as-skill.

Guides to go deeper:

• The Most Popular AI Coding Skills — where shipped-with-package skills fit in the wider landscape.
• Spec-Driven Development with AI Agents — the upstream discipline that pairs well with versioned skills.

Learn the broader track:

• Agentic Automation — the full track this skill belongs to.