Ship the Turborepo Agent Skill inside the turbo npm package

[gtbuchanan]

The Turborepo Agent Skill at skills/turborepo currently lives only in the source repo, so consumers reach it out-of-band — npx skills add vercel/turborepo, manual download, third-party installers, etc. Bundling it into the published turbo package would let tools that discover skills under node_modules/*/skills/ (e.g. skills-npm, per this proposal) pick it up automatically — versioned with the same turbo you're already running, no extra install step, no per-machine drift.

Current state

• The published tarball does not include skills/
• Skill source lives at the repo root (skills/turborepo/), outside packages/turbo/, so the publish manifest can't reach it as-is

Proposed change

1. Copy or symlink skills/turborepo/ into packages/turbo/skills/turborepo/ at publish time
2. Add "skills" to files in packages/turbo/package.json

After this, consumers using skills-npm (or any equivalent discovery tool) get the skill simply by depending on turbo, and the skill version is guaranteed to match the binary version.

Why this matters

• Version alignment — the skill advertises metadata.version: 2.9.7-canary.11; bundling makes that promise concrete instead of relying on independent install timing
• Zero-friction onboarding — agents in CI sandboxes, ephemeral dev containers, and fresh clones get accurate Turborepo guidance without an extra setup step
• Single source of truth — the same release that fixes a skill issue (e.g. #12638) automatically reaches every consumer

[anthonyshew]

Do you have examples of harnesses or chats where the agent went looking into node_modules to find the Skill?

It's a nice proposal, but if its not actually getting used by the community, I don't see any utility.

[gtbuchanan]

Did you click the link to skills-npm I provided? Or did you have a specific question that antfu didn't cover in his proposal?

skills-npm symlinks the package skills to the agent skills directory at the root of the repo, which is already a location agents search for skills.

[anthonyshew]

Yes, and that doesn't answer what I asked. Are there examples of harnesses or chats that you have that don't required augmentation to make this paradigm work?

Realistically, I don't expect something like this to get used broadly. Generally, people just use the harness they're given and let the LLM work. If this were a blessed pattern in the Agent Skill spec, that would be a lot better - but it isn't, so I can't trust that this is going to actually going to get used.

[gtbuchanan]

that doesn't answer what I asked

Given that my post directly referenced skills-npm as the supporting mechanism (not the agents themselves), surely you can see my confusion around your initial question. No offense intended.

Are there examples of harnesses or chats that you have that don't required augmentation to make this paradigm work?

No. I don't have examples because agents don't do that yet AFAIK. The intent behind skills-npm is to get that type of pattern adopted.

Realistically, I don't expect something like this to get used broadly. Generally, people just use the harness they're given and let the LLM work. If this were a blessed pattern in the Agent Skill spec, that would be a lot better - but it isn't, so I can't trust that this is going to actually going to get used.

Fair enough. I only suggested the idea because I felt antfu was well-respected enough in the industry to carry some weight, but I get the hesitation. I'll see if they're receptive to the idea of adding this to the Agent Skills spec.

For reference, I'm also trying to drive adoption of this idea via tools like mise. It doesn't seem completely unreasonable to me for a tool to package it's skills alongside it's binary so that they don't drift independently through different install mechanisms.

[anthonyshew]

No worries, I definitely get where you're coming from. I'm quite aligned. I've been frustrated with the spec for these, this specific issue being my chief complaint. I also don't think this is unreasonable, but I've previously chosen to be discerning on this one. I'll be okay with being "late" (in the first 10% of adopters instead of first 1%) to this.

something something "great product is about what you don't add, just as much as what you do add" something something

[amotarao]

Not the OP, but this question happens to be the one thing I can add a data point to, so jumping in.

The concern reads fair to me: bundling only pays off if something on the consumer side actually reads what gets bundled. Here is what does today.

npx skills experimental_sync (from vercel-labs/skills) crawls node_modules and, for each package, looks for SKILL.md at the package root, skills/*/SKILL.md, and .agents/skills/*/SKILL.md, then links what it finds into the agent directories — it's listed in that repo's AGENTS.md alongside add and update. So the node_modules convention isn't only the third-party proposal linked above: the CLI people already use to install this skill looks there too. turbo just isn't among the packages it can find, since the published tarball is files: ["bin", "schema.json"].

On whether the version drift is real rather than theoretical: in a monorepo I work on, turbo is pinned at 2.10.12 while the installed skill carries metadata.version: 2.10.13-canary.6, because npx skills add vercel/turborepo resolves against the default branch. Nothing surfaces that gap, so the agent follows guidance written for a release we don't run — and the skill does document surface that moves between releases (flag availability, turbo ls stability, and so on).

Pinning the tag works today:

npx skills add vercel/turborepo#v2.10.12 -s turborepo

It leaves each consumer to translate an npm version into this repo's tag convention and re-pin on every bump, Dependabot ones included, which is where the drift tends to come back. Bundling removes that mapping instead of automating it: experimental_sync records the entry as sourceType: "node_modules", which skills update skips by design, so the package version becomes the single source of truth and the lockfile you already have pins the skill along with the binary.

If the direction sounds workable and @gtbuchanan isn't already on it, I'd be glad to help with the publish-time copy step.

[anthonyshew]

Shippped in https://github.com/vercel/turborepo/releases/tag/v2.11.5-canary.2!