Skip to content

Choosing a runner

Skills invoke CLIs by shelling out. The runner word at the front of that command decides how much each call costs, how reproducible it is, and what has to be installed before the skill works at all. This page records how to choose one.

npx <pkg>@<version> re-resolves and re-spawns on every call — even when the package is already cached — and it never reuses a global install. upx is a local-first alternative: it resolves a semver range against installs that already exist and spawns the binary directly, falling back to npx on a miss. Measured against a warm npx on npm 12, that is roughly 3× faster per call (method and numbers — re-run them before quoting them, since the gap narrows as npm gets faster).

upx’s own documentation carries the resolution algorithm and the failure modes that belong to the runner. What follows is what the choice means for a plugin.

The npx install cache (~/.npm/_npx) is shared process-wide and is not concurrency-safe. When several tasks shell out to the same uncached npx <pkg>@<version> at once — parallel CI jobs, or several agents working at the same time — the concurrent installs race to populate the same directory and fail with ENOTEMPTY. The symptom is not a clean error: a validation step reports that it “did not run”, intermittently, on some runs only.

Two mitigations were used in practice, in escalating order:

  1. Warm the cache serially before the parallel work, so the concurrent calls all hit a populated cache. This narrows the window; it does not close it.
  2. Remove the subprocess. Where the CLI also ships a programmatic API, importing it in-process removes the resolution, the spawn, and the cache entirely. This is the only complete fix, and it is available only when the tool exposes a library entry point.

upx is a latency fix, not a correctness fix.

It trades reproducibility for speed, by design

Section titled “It trades reproducibility for speed, by design”

plugin version pins skills to an exact version at release. Adopting upx deliberately widens that pin to a caret range (^<major>, or ^0.<minor> for a 0.x package). The version a skill runs is then whatever satisfying copy happens to be nearest — which may not be the version the skill was written and tested against. A stale global install that still satisfies the range wins silently. npx <pkg>@<exact> cannot do this.

It is not ambient, so it needs a bootstrap

Section titled “It is not ambient, so it needs a bootstrap”

npx ships with npm; it is on every machine that has Node. upx only exists after npm i -g @repobuddy/upx. A skill whose command word is upx will fail with command not found anywhere that install has not happened.

This matters most for non-npm plugin distribution. A plugin installed from a git source drops skill files into a consuming repo that depends on nothing — a bare upx there is exactly the “requires a global install” failure that pinned npx <pkg>@<version> was adopted to avoid. Keep npx as the runner word for skills that must work on a cold machine.

The fallback path still has npx’s problems

Section titled “The fallback path still has npx’s problems”

A upx miss runs npx. On a cold cache with parallel callers, the cache race is unchanged — it just happens less often, because hits skip it. If the goal is to eliminate the race rather than make it rarer, the answer is still to import the library in-process.

The corpus now contains both forms, and tooling has to recognize both and preserve whichever a reference already uses. Detection is textual — a <runner> <pkg>@<version> pattern in Markdown — so it depends on the reference carrying an explicit @<version>. Bootstrap idioms such as npx skills add <repo> --skill <name> are untouched only because they carry no version, and non-workspace packages are skipped on a separate axis. This is a heuristic boundary, not a declared one; treat a rewrite tool’s output as something to review rather than trust.

The fastest call is the one with no runner word at all. When the CLI belongs to the plugin shipping the skill, the skill can run the command from a script in its own scripts/ directory.

A skill does not always travel with its package

Section titled “A skill does not always travel with its package”

How the skill reached the agent decides what sits next to it:

Channel What the agent sees
npm-sourced plugin install the whole package, with its dependency tree
git-sourced plugin install (Copilot CLI, Cursor, GitHub-hosted marketplaces) the repository, with no node_modules
pnpm 12.11 agent skills (docs) one skill folder, linked as .claude/skills/pnpm-<pkg>-<skill>, or copied when a link fails

pnpm links the skills of a project’s direct dependencies, one folder at a time. Through a symlink, Node resolves a script to its real path inside node_modules, so a script that climbs out of the skill to the package root still works. Through a copy, the same climb lands in .claude/ and finds nothing. Node also refuses to strip types from a file under node_modules (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING), so shipping the .ts source is no answer either. The skill also gets a different name in this channel, pnpm-<pkg>-<skill>, so a plugin-qualified reference such as /my-plugin:doctor points at nothing there.

A script that works in every channel is one file that reaches back into nothing.

Write the script as an ordinary module in your package source, next to its tests, and declare it as a script entry:

"scripts": {
"skills/doctor/scripts/doctor.mjs": { "source": "src/skills/doctor.ts", "command": "doctor" }
}

plugin build compiles it into skills/doctor/scripts/doctor.mjs: Node built-ins stay imports, and everything else, your own modules and their dependencies, is inlined. Commit the output. The entry can import the same command function your CLI registers, so the skill and the CLI print the same output:

src/skills/doctor.ts
import { runDoctor } from '../doctor/doctor.js'
await runDoctor(process.argv.slice(2))

The skill body names it relative to itself:

Terminal window
node scripts/doctor.mjs

Three things make this work, and each fails a different way if you skip it.

Resolve from import.meta.url, never the working directory. An agent runs the script from the repository it is working on, so the working directory is that repository rather than the skill. That is what you want for the command’s input. It is useless for finding anything the skill ships.

Keep node in front. A file written by a build step ships as mode 100644, so its shebang never runs it, and on Windows a shebang does nothing regardless of mode.

Keep the script small. The build warns above 150 KB. One command with a small argument parser compiles to tens of kilobytes; a whole CLI with an SDK can pass a megabyte. A skill that needs most of the CLI should run it through a forwarder instead of compiling it in.

Run the plugin’s CLI through a forwarder

Section titled “Run the plugin’s CLI through a forwarder”

A skill that runs its plugin’s CLI calls a forwarding script per CLI with node, not a runner word. In a checkout it runs your local build, and anywhere else the pinned release. See Running your CLI from skills.

A CLI called through a runner in skill text, rather than through a forwarder, gets a pinned npx <pkg>@<version>.

Pin it to the version that shipped the skill. A skill states the flags and output of its own version, so an unpinned call can hand an agent a CLI its documentation does not describe. A hand-written script that shells out to npx follows the same rule. Write the pin as one npx <pkg>@<version> string so the release finds it:

const [npx, ...npxArgs] = 'npx my-cli@1.4.0'.split(' ')

A compiled script takes the version from globalThis.__SKILL_SCRIPT__.version instead.

The release keeps every such pin current, in Markdown and in scripts: plugin version re-pins the plugin’s own package and every other workspace package the skills reference, whichever release tool calls it. A compiled script or a forwarder needs no literal pin: its header embeds the package, the bin and the version, and plugin version stamps that version too.

Situation Use
The CLI ships in the same plugin as the skill A forwarder in the skill’s scripts/, { "forward": "<bin>" }, run as node <this skill's folder>/scripts/<bin>.mjs, with no runner line beside it
A skill runs another package’s CLI A forwarder that pins it: { "forward": "<bin>", "package": "<pkg>", "version": "<exact>" }
The CLI exposes a library API and you control the call site Import in-process — no runner at all
A skill shipped to unknown machines, or via a non-npm plugin source npx <pkg>@<exact>
A skill called many times per run, on a machine you set up upx <pkg>@^<major>
A dist-tag (@latest, @next) npx — upx cannot match a tag
A declared dependency in your own package scripts node_modules/.bin, via your package manager
  • @repobuddy/upx — the runner itself: measurements, the resolution algorithm, and its own failure modes
  • Installation — installing upx
  • The adopt-upx skill rewrites npx <pkg>@<version> references to upx <pkg>@^<major>
  • The upgrade-plugin skill bumps pins for both runner words, preserving each reference’s existing word