Skills NPM is a command-line tool that discovers agent skills shipped inside npm packages and symlinks them into the directories coding agents read. It proposes a convention: a package ships a skills/ directory alongside its code, so installing the package brings its skills with it and the two stay on one version.
Running skills-npm setup once wires the tool into the project's prepare script and adds an ignore pattern, so skills are re-linked whenever dependencies are installed. Discovered skills are symlinked out of node_modules to skills/npm- - .
A skills-npm.config.ts file in the project root controls behaviour: the discovery source (node_modules or package.json), which agents to target, recursive scanning for monorepo packages, whether to update the ignore file, dry-run mode, and include or exclude filters. A filter takes a package name, a wildcard pattern such as @some/*, or a package paired with named skills, and applies only to packages already discovered.
When no agents are configured, detection combines two signals: an agent's home config directory, and an unambiguous agent CLI name found on PATH, which catches an agent installed but not yet run. In an interactive terminal the prompt lists every known agent with the detected ones pre-selected; non-interactively the detected set is used directly.
Features
- Skill discovery: finds skills bundled in installed npm packages, read from node_modules or from package.json
- Automatic re-sync: the prepare hook re-links skills on every dependency install
- Agent detection: matches agents by config directory and by CLI name on PATH, with an interactive confirmation prompt
- Filtering: include and exclude lists take package names, wildcard patterns, or specific skills within a package
- Monorepo support: optional recursive scanning, with the working directory resolved to the detected workspace root by looking for pnpm-workspace.yaml, lerna.json, or a package.json with a workspaces field
- Dry run: a --dry-run flag reports what would change without writing anything
- Cleanup control: stale npm-* skills are removed from agent directories unless --no-cleanup is passed
