skills-npm CLI
skills-npm links agent skills shipped in your dependencies in node_modules and listed in the skills field of package.json
- 578 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- Creates and removes symlinks in agent directories (`.agents/skills`, `~/.claude`) and writes `skills-npm-lock.json`
- Runs `skills add` for remote sources, which downloads code from git repositories named in dependencies' `package.json` files
- The `prepare` script runs on every dependency install
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/skills-npmDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Creates and removes symlinks in agent directories (`.agents/skills`, `~/.claude`) and writes `skills-npm-lock.json`
- Runs `skills add` for remote sources, which downloads code from git repositories named in dependencies' `package.json` files
- The `prepare` script runs on every dependency install
This is third-party code. Review the repository files before installing.
What it does
skills-npm is a command line tool by Anthony Fu that distributes skills through npm. A package with `SKILL.md` files in its `skills/` directory ships them with the dependency: skills-npm finds those skills in `node_modules` and creates symlinks in your agents' directories under the name from the skill's frontmatter. The `.agents/skills` directory is always linked, and Cursor, Codex, OpenCode and Amp read it. Besides bundled skills the tool reads a `skills` field in `package.json`. An entry such as `vercel-labs/agent-skills@web-design-guidelines` or `owner/repo#v1.2.0` names a skill in a git repository, and skills-npm runs `skills add` from the skills CLI for it. A package with only that field becomes a skills pack installed on every team machine with `npm i -D @acme/frontend-skills`. `npm:package` entries take skills from a dependency. The flow: `npm i -D skills-npm`, then `npx skills-npm setup` wires `skills-npm` into the `prepare` script and runs the first sync. After that skills refresh on every dependency install. Versions and sources go into `skills-npm-lock.json`, which you commit. The tool detects agents from home directories and commands on PATH, and inside Claude Code or Cursor it picks the current agent itself.
Who it is for. Authors of npm packages who want to ship skills together with a library, and teams where every developer should have the same skill set at the right versions.
Good fit when
- You publish a library and put `skills/my-skill/SKILL.md` in the package so a user's agent knows your API at the right version
- A team needs one set of a dozen skills, and a package with a `skills` field is easier to assemble than cloning repositories one by one
- Skills should update with dependencies rather than by hand: a `prepare` script in `package.json` is enough
- Participants use different agents, and links have to be laid out across the Claude Code, Cursor and Codex directories in one run
- You need to see what was installed: `skills-npm-lock.json` lists the package, version and `SKILL.md` path
Not a fit when
- The project is not on Node.js and has no `package.json`: the tool reads dependencies from `node_modules` and the `skills` field
- You want to install a single skill from GitHub once: `npx skills add owner/repo` is enough
- Node is older than 22.20: the tool requires that version or newer
- You need a long-term tool: the author is merging it into the skills CLI and `skills-npm` will eventually be deprecated
Example request
Set up skills-npm in this project and show which skills from our dependencies it found for Claude Code and CursorLimitations
- Node.js 22.20 or newer is required. The tool calls the skills CLI and relies on its format.
- The author is merging the package into the skills CLI: `npx skills experimental_sync` replaces `npx skills-npm`, and `npx skills-npm migrate` moves a project over. The package will be deprecated once the features are integrated.
- Installs can slow down: `skills add` runs for each new remote source, and a source that cannot be reached over the network fails the run. `--no-remote` covers offline installs.
- If one skill name comes from two direct dependencies, both are skipped with a warning, and `include` and `exclude` settle the conflict.
How to disable. Remove `skills-npm` from the `prepare` script and from `devDependencies`, then delete `skills-npm-lock.json`. The tool cleans symlinks in agent directories that point into `node_modules` on its next run while it is installed. Skills you installed by hand are left alone.
FAQ
How do I install skills-npm in a project?
Run `npm i -D skills-npm` and `npx skills-npm setup` once. The command adds `skills-npm` to the `prepare` script and runs the first sync. Keep the tool in `devDependencies`: `prepare` does not run for people who install your published package.
How do I ship a skill with my npm package?
Put `SKILL.md` in the package's `skills/<name>/` directory, for example `skills/my-skill/SKILL.md`. `dist/skills/` and `.agents/skills/` are scanned too, and a single-skill package can keep `SKILL.md` at its root. After `npm install` skills-npm links it for the user's agent.
How do I build a skill set for a team?
Create a package whose `package.json` has only a `skills` field, for example `"vercel-labs/agent-skills#v1.4.0@web-design-guidelines"` or `"npm:@vueuse/skills"`. Pin versions with `#tag` or a full 40-character SHA. The team installs it as `npm i -D @acme/frontend-skills`.
How does skills-npm differ from `npx skills add`?
`npx skills add` installs a skill from a git repository once and by hand. skills-npm does it on every dependency install, takes skills shipped inside npm packages and records them in `skills-npm-lock.json`. Remote sources are still installed through `skills add`.
What if the project already uses the skills CLI?
Run `npx skills-npm migrate`. It rewrites script calls to `skills experimental_sync -y`, moves to `skills@^1.7.2` and deletes `skills-npm-lock.json`. It does not read `skills-npm.config.*`, so move its options into flags.
Discussion
No questions or reviews yet.
Related
CLI toolsThe author's personal set: shared agent rules and dozens of skills for GitHub, the browser, macOS, messaging and releases, plus a sync script
Dozens of mizchi's agent skills: frontend audits, AWS, Cloudflare, SQL, Playwright and OpenTelemetry, installed one by one
A set of skills from real work: npm supply-chain audit, CLI building, Obsidian plugin release and an AGENTS.md hierarchy
dotnet-skills: a skill installer for .NET
dotnet-skills
An installer for a .NET skill catalog that picks skills from project files for Claude Code, Codex, Copilot and Gemini CLI
Over 1,100 ready-made skills for Claude Code, Codex, Gemini CLI and Cursor, plus an MCP server that picks a skill for the task
Builder Skills
Skills for agents
A set of small skills from Builder.io for agent work habits: visual plans and diff recaps, docs-first checks, cross-agent review and clean status updates
README in short
The README opens with a note on the merge into the skills CLI and explains why cloning skills one by one is awkward: versions drift and commands repeat. Then come setup, remote skills and packs, the lock file, conflict rules, migrations between versions, configuration and CLI options. It ends with a section for package authors and a list of packages that already ship skills.