Skip to content
Back to search

skills-npm

Install agent skills from npm

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/antfu--skills-npm/badge.svg)](/listings/antfu--skills-npm)

HTML

<a href="/listings/antfu--skills-npm"><img src="/api/listings/antfu--skills-npm/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 316 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # skills-npm
  2. [![npm version][npm-version-src]][npm-version-href]
  3. [![npm downloads][npm-downloads-src]][npm-downloads-href]
  4. [![bundle][bundle-src]][bundle-href]
  5. [![JSDocs][jsdocs-src]][jsdocs-href]
  6. [![License][license-src]][license-href]
  7. > [!NOTE]
  8. > This package is merging with the [`skills`](https://github.com/vercel-labs/skills) CLI. [Read more](https://github.com/vercel-labs/skills/issues/2323).
  9. >
  10. > You can run it with `npx skills experimental_sync` to replace `npx skills-npm`.
  11. >
  12. > `skills-npm` will eventually be deprecated after the functionality is fully integrated into the `skills` CLI.
  13. >
  14. > Run `npx skills-npm migrate` to switch a project over. See [Migrating to `skills experimental_sync`](#migrating-to-skills-experimental_sync).
  15. A CLI that installs [agent skills](https://agentskills.io) through npm: it symlinks skills shipped inside your installed packages, and fetches the remote skills your packages declare in a `skills` field via the [`skills`](https://github.com/vercel-labs/skills) CLI.
  16. ## Why?
  17. Cloning skills from git repos one by one (e.g. `npx skills add`) has friction:
  18. - **Version mismatch** - Skills and tools update separately, causing compatibility issues
  19. - **Manual management** - Each project repeats the same `add` commands
  20. - **Sharing overhead** - Teams must commit cloned files or repeat setup on each machine
  21. This project proposes two conventions that let npm do the distribution:
  22. - **Ship skills inside npm packages** under a `skills/` directory. When you `npm install` a tool, its skills come bundled and are symlinked for your agent.
  23. - **Curate skills in a `skills` field** of `package.json`. A package can list skills hosted elsewhere; installing the package installs the list. A package that is nothing but this field is a **skills pack**.
  24. **Read the full proposal: [PROPOSAL.md](./PROPOSAL.md)** and the field spec: **[SPEC.md](./SPEC.md)**
  25. > [!NOTE]
  26. > Requires Node.js 22.20 or later (the floor of the `skills` CLI it drives).
  27. ## Usage
  28. Install as a dev dependency and run `setup` once:
  29. ```bash
  30. npm i -D skills-npm
  31. npx skills-npm setup
  32. ```
  33. `skills-npm setup` wires the tool into your `package.json` `prepare` script and runs the first sync. After that, skills are re-symlinked for your agent automatically whenever you install dependencies.
  34. `setup` merges into any existing `prepare` script (it appends with `&&` and is a no-op if already wired), resulting in:
  35. ```json
  36. {
  37. "private": true,
  38. "scripts": {
  39. "prepare": "skills-npm"
  40. }
  41. }
  42. ```
  43. `skills-npm` symlinks each skill from `node_modules` into your agent's skills directory under the skill's own name (the `SKILL.md` frontmatter `name`, sanitized the same way the [`skills`](https://github.com/vercel-labs/skills) CLI sanitizes install names). The symlinks are relative and point into `node_modules`, so you can commit them: they are restored on every fresh clone as soon as `npm install` runs. No `.gitignore` changes are made.
  44. > [!NOTE]
  45. > Keep `skills-npm` as a `devDependency`. The `prepare` script runs on `install` (and before `publish`/`pack`), but never for people who install your published package, so it is safe to commit.
  46. ## Remote skills and skills packs
  47. Besides the `skills/` directory, skills-npm reads a `skills` field from your own `package.json` and from the packages it scans (your direct dependencies by default). Each entry is a git-hosted source in the same syntax the `skills` CLI accepts, or `npm:<package>` to pull in skills shipped by another npm package:
  48. ```json
  49. {
  50. "skills": [
  51. "vercel-labs/agent-skills@web-design-guidelines",
  52. "owner/repo#v1.2.0",
  53. { "source": "owner/repo", "skills": ["a", "b"], "ref": "v2.0.0" },
  54. "npm:@vueuse/skills"
  55. ]
  56. }
  57. ```
  58. Publish a package with only this field and you have a shareable, versioned **skills pack**: `npm i -D @acme/frontend-skills` installs the whole list for everyone on the team. The full syntax and semantics are in [SPEC.md](./SPEC.md).
  59. How remote entries are handled:
  60. - **The `skills` CLI does the fetching.** skills-npm spawns `skills add <source> --skill … -a <your agents> -y` for each distinct source, so the result is exactly what `npx skills add` would produce: a copy under `.agents/skills/<name>`, per-agent symlinks, and an entry in `skills-lock.json`. Commit those files as you would after `npx skills add`.
  61. - **Fetch once, not on every install.** An entry whose skills are already recorded in `skills-lock.json` from the same source (and ref) is skipped. `--force` refetches everything; to pull newer upstream content run `npx skills update`.
  62. - **Failures fail the run.** A source that cannot be cloned or an invalid entry (a local path, a non-git URL, a `ref` given twice) exits non-zero, so a broken pack never passes silently. Use `--no-remote` (or `remote: false`) for offline installs: network entries are left as they are, `npm:` entries still resolve.
  63. - **Removal follows the field.** When no honored package requests a remote skill anymore, skills-npm runs `skills remove <name>` for it (unless `--no-cleanup`). Skills you installed by hand are never touched.
  64. - **`npm:` entries** are resolved from the declaring package (so pnpm's isolated layout works) and symlinked like any shipped skill. The pack must list the target package in its `dependencies`.
  65. Pin refs in packs (`owner/repo#v1.2.0`, or `"ref"`) so every consumer gets the same content. A commit must be a full 40-character SHA.
  66. ## Lock file
  67. Each sync writes `skills-npm-lock.json` in your project root: a committed manifest of the skills skills-npm manages, keyed by skill name:
  68. ```json
  69. {
  70. "version": 3,
  71. "skills": {
  72. "presenter-mode": { "package": "@slidev/cli", "version": "52.1.0", "skillPath": "skills/presenter-mode/SKILL.md" },
  73. "vueuse-functions": { "package": "@vueuse/skills", "version": "1.3.0", "skillPath": "skills/vueuse-functions/SKILL.md", "via": "@acme/frontend-skills" }
  74. },
  75. "remote": {
  76. "web-design-guidelines": { "package": "@acme/frontend-skills", "source": "vercel-labs/agent-skills", "ref": "v1.4.0" }
  77. }
  78. }
  79. ```
  80. It records *what* is installed and *who asked for it*, not *where*; agent directories are derived per machine, mirroring how the `skills` CLI keeps agent selection out of its committed lock. `skillPath` locates the skill inside the package the same way `skills-lock.json` does; `version` is the installed package version, for readers of the lock (your package manager's lock file remains the source of truth). `via` marks a shipped skill that is only installed because a pack requested it with `npm:`; `remote` lists the skills fetched on behalf of a `skills` field.
  81. ## Conflicts
  82. When the same skill name comes from more than one place, skills-npm applies this priority ladder:
  83. 1. **Explicit installs win** - a name listed in the `skills` CLI's `skills-lock.json` that skills-npm did not install itself is never touched, even when the skill is missing on disk.
  84. 2. **Existing content wins** - a real directory or a symlink not pointing into `node_modules` is never replaced.
  85. 3. **Shipped beats remote** - a skill shipped in an npm package beats a remote entry of the same name.
  86. 4. **Direct beats transitive** - a skill from a direct dependency beats the same name from a transitive one; identical remote requests from several packages count as one.
  87. 5. **Ties are skipped** - if two direct (or only transitive) dependencies collide, all contenders are skipped with a warning; resolve with `include`/`exclude`.
  88. Cleanup only ever removes symlinks that point into `node_modules` and remote skills recorded in `skills-npm-lock.json`, so nothing else in your agent directories is at risk.
  89. ## Migrating to `skills experimental_sync`
  90. `npx skills-npm migrate` moves a project to the `skills` CLI:
  91. - Each `skills-npm` command in your `package.json` scripts becomes `skills experimental_sync -y`. Flags are carried over in their new spelling (`--agents a,b` becomes `-a a b`). Flags with no equivalent (`--force`, `--cwd`, `--source`) are dropped, with a warning.
  92. - The `skills-npm` dependency becomes `skills@^1.7.2`. If it uses a pnpm `catalog:` specifier, the entry in `pnpm-workspace.yaml` is renamed instead.
  93. - `skills-npm-lock.json` is deleted. `skills experimental_sync` records its skills in `skills-lock.json`.
  94. `skills experimental_sync` does not read `skills-npm.config.*`. If you have one, `migrate` warns about it: move its options to flags in the `prepare` script, then delete the file. Reinstall your dependencies afterwards to run the first sync. Use `--dry-run` to preview the changes.
  95. ## Migrating from v3
  96. `skills-npm-lock.json` moves to version 3: each entry's `skillFolder` becomes `skillPath` (the path to `SKILL.md` inside the package, as in `skills-lock.json`) and gains the installed package `version`. It is rewritten on the first sync. Packages are now also scanned for a root `SKILL.md`, `dist/skills/` and `.agents/skills/`, so a few more skills may appear.
  97. ## Migrating from v2
  98. v3 requires Node.js 22.20+ and adds `skills` as a dependency. `skills-npm-lock.json` moves to version 2 (a `remote` map and an optional `via` per entry); it is rewritten on the first sync. Nothing changes for projects without a `skills` field.
  99. ## Migrating from v1
  100. v1 created `npm-<package>-<skill>` links and gitignored them. On the first v2 sync, stale `npm-*` links are removed automatically and re-created under the new names. The old `**/skills/npm-*` block in `.gitignore` no longer matches anything; skills-npm won't edit your `.gitignore`, so remove it whenever convenient (a hint is printed while it remains). If you want the links shared with your team, commit them along with `skills-npm-lock.json`.
  101. ## Configuration
  102. You can create a `skills-npm.config.ts` file in your project root to configure the behavior:
  103. ```ts
  104. // skills-npm.config.ts
  105. import { defineConfig } from 'skills-npm'
  106. export default defineConfig({
  107. // Source to discover skills from: 'node_modules' or 'package.json'
  108. source: 'package.json',
  109. // Target specific agents (defaults to all detected agents)
  110. agents: ['cursor', 'windsurf'],
  111. // Scan recursively for monorepo packages (default: false)
  112. recursive: false,
  113. // Skip confirmation prompts (default: false)
  114. yes: false,
  115. // Dry run mode (default: false)
  116. dryRun: false,
  117. // Fetch remote skills from `skills` fields (default: true); false for offline installs
  118. remote: true,
  119. // Include specific packages or skills
  120. include: [
  121. // Include all skills from a package
  122. '@some/package',
  123. // Include all skills from packages matching a wildcard pattern
  124. '@some/*',
  125. // Include specific skills from packages matching a wildcard pattern
  126. { package: '@some/*', skills: ['integration'] },
  127. // Include specific skills from a package
  128. { package: '@slidev/cli', skills: ['presenter-mode'] },
  129. ],
  130. // Exclude specific packages or skills
  131. exclude: [
  132. // Exclude all skills from a package
  133. '@some/package',
  134. // Exclude all skills from packages matching a wildcard pattern
  135. '@some/*',
  136. // Exclude specific skills from packages matching a wildcard pattern
  137. { package: '@some/*', skills: ['integration'] },
  138. // Exclude specific skills from a package
  139. { package: '@slidev/cli', skills: ['presenter-mode'] },
  140. ],
  141. })
  142. ```
  143. `include` and `exclude` string patterns match either a package name (`@some/*`) or a sanitized skill name (`presenter-mode`). These filters only apply to packages that were already discovered from `node_modules` or `package.json`. For remote entries they match the requesting package, and the skill name only where the entry names skills (a bare `owner/repo` can only be filtered by package).
  144. ### Options
  145. | Option | Type | Default | Description |
  146. |--------|------|---------|-------------|
  147. | `cwd` | `string` | Workspace root | Current working directory |
  148. | `source` | `'node_modules' \| 'package.json'` | `'package.json'` | Source to discover skills from |
  149. | `agents` | `string \| string[]` | All detected | Target agents to install to |
  150. | `recursive` | `boolean` | `false` | Scan recursively for monorepo packages |
  151. | `yes` | `boolean` | `false` | Skip confirmation prompts |
  152. | `dryRun` | `boolean` | `false` | Show what would be done without making changes |
  153. | `include` | `(string \| { package: string, skills: string[] })[]` | `undefined` | Packages or skills to include. Supports package wildcard patterns like `@some/*` |
  154. | `exclude` | `(string \| { package: string, skills: string[] })[]` | `[]` | Packages or skills to exclude. Supports package wildcard patterns like `@some/*` |
  155. | `cleanup` | `boolean` | `true` | Remove stale skills-npm symlinks and remote skills nobody requests anymore |
  156. | `remote` | `boolean` | `true` | Fetch remote skills declared in `skills` fields; `false` skips network entries |
  157. > The `cwd` defaults to the workspace root, which is detected by searching up for `pnpm-workspace.yaml`, `lerna.json`, or a `package.json` with `workspaces` field. Falls back to the nearest `package.json`.
  158. ## CLI Options
  159. ```bash
  160. skills-npm [options] # discover and symlink skills (run by the prepare hook)
  161. skills-npm setup [options] # add the prepare script, then run the first sync (run once)
  162. skills-npm migrate [options] # switch the project to `skills experimental_sync` (accepts --cwd, --dry-run)
  163. Options:
  164. --cwd <cwd> Current working directory
  165. -s, --source <source> Source to discover skills from (default: 'package.json')
  166. -a, --agents Comma-separated list of agents to install to
  167. -r, --recursive Scan recursively for monorepo packages
  168. --include <patterns> Comma-separated package names or patterns to include
  169. --exclude <patterns> Comma-separated package names or patterns to exclude
  170. -y, --yes Skip confirmation prompts
  171. --dry-run Show what would be done without making changes
  172. -f, --force Force full reload, ignore cache and refetch remote skills
  173. --no-cleanup Keep stale skills-npm symlinks and remote skills in agent directories
  174. --no-remote Skip remote skills declared in "skills" fields (offline)
  175. -h, --help Display help
  176. -v, --version Display version
  177. ```
  178. ## Agent detection
  179. When `agents` is not set, `skills-npm` auto-detects which coding agents you use and installs to those. Detection combines two signals:
  180. - **Config directory** - an agent's home directory exists (e.g. `~/.cursor`, `~/.claude`).
  181. - **Installed command** - the agent's CLI is found on your `PATH` (e.g. `claude`, `codex`, `gemini`, `cursor-agent`). This catches agents that are installed but have not created their config directory yet.
  182. The command check is conservative: only agents with an unambiguous CLI name are probed, so generic names and GUI-only editors are matched by the directory check alone.
  183. In an interactive terminal, the prompt is the same one `npx skills add` shows: every agent is searchable, your last selection (shared with the `skills` CLI) or, failing that, the detected agents are pre-selected. Non-interactively (e.g. from the `prepare` hook), the detected set is used directly. Pass `--agents` (or set `agents` in the config) to bypass detection entirely.
  184. Whatever you pick, `.agents/skills` is always linked: it is the shared directory read by every agent using the universal layout (Cursor, Codex, OpenCode, Amp, ...), so the committed links work for teammates on any agent.
  185. When skills-npm itself runs inside a coding agent (Claude Code, Cursor, Codex, ...), it skips all prompts and targets that agent unless `agents` is set explicitly.
  186. ## For Package Authors
  187. Ship the skills you own in a `skills/` directory:
  188. ```
  189. my-tool/
  190. ├── package.json
  191. ├── dist/
  192. └── skills/
  193. └── my-skill/
  194. └── SKILL.md
  195. ```
  196. `dist/skills/` and `.agents/skills/` are scanned too, and a package that *is* a single skill can put `SKILL.md` at its root. These are the same locations `skills experimental_sync` looks in.
  197. Curate skills you don't own in a `skills` field. A skills pack is just a package with that field and nothing else:
  198. ```json
  199. {
  200. "name": "@acme/frontend-skills",
  201. "version": "1.0.0",
  202. "skills": [
  203. "vercel-labs/agent-skills#v1.4.0@web-design-guidelines",
  204. "npm:@vueuse/skills"
  205. ],
  206. "dependencies": {
  207. "@vueuse/skills": "^1.0.0"
  208. }
  209. }
  210. ```
  211. See [PROPOSAL.md](./PROPOSAL.md#for-package-authors) and [SPEC.md](./SPEC.md).
  212. ## Showcases
  213. Packages that ships their built-in skills:
  214. - [`@slidev/cli`](https://github.com/slidevjs/slidev)
  215. - [`eslint-vitest-rule-tester`](https://github.com/antfu-collective/eslint-vitest-rule-tester)
  216. - [`@vitejs/devtools-kit`](https://github.com/vitejs/devtools)
  217. - [`@vueuse/skills`](https://github.com/vueuse/vueuse/tree/main/packages/skills)
  218. > [!NOTE]
  219. > PR are welcome to add more packages that ships their built-in skills.
  220. ## Sponsors
  221. <p align="center">
  222. <a href="https://cdn.jsdelivr.net/gh/antfu/static/sponsors.svg">
  223. <img src='https://cdn.jsdelivr.net/gh/antfu/static/sponsors.svg' alt="sponsors" />
  224. </a>
  225. </p>
  226. ## License
  227. [MIT](./LICENSE) License © [Anthony Fu](https://github.com/antfu)
  228. <!-- Badges -->
  229. [npm-version-src]: https://img.shields.io/npm/v/skills-npm?style=flat&colorA=080f12&colorB=1fa669
  230. [npm-version-href]: https://npmjs.com/package/skills-npm
  231. [npm-downloads-src]: https://img.shields.io/npm/dm/skills-npm?style=flat&colorA=080f12&colorB=1fa669
  232. [npm-downloads-href]: https://npmjs.com/package/skills-npm
  233. [bundle-src]: https://img.shields.io/bundlephobia/minzip/skills-npm?style=flat&colorA=080f12&colorB=1fa669&label=minzip
  234. [bundle-href]: https://bundlephobia.com/result?p=skills-npm
  235. [license-src]: https://img.shields.io/github/license/antfu/skills-npm.svg?style=flat&colorA=080f12&colorB=1fa669
  236. [license-href]: https://github.com/antfu/skills-npm/blob/main/LICENSE
  237. [jsdocs-src]: https://img.shields.io/badge/jsdocs-reference-080f12?style=flat&colorA=080f12&colorB=1fa669
  238. [jsdocs-href]: https://www.jsdocs.io/package/skills-npm

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.