skills-npm

June 17, 2026 · View on GitHub

A CLI that discovers agent skills shipped inside npm packages and creates symlinks for coding agents to consume.

Why?

Current skill distribution approaches (e.g. @vercel-labs/skills) have friction:

Git-only source - Only supports git repos as skills source
Version mismatch - Skills and tools update separately, causing compatibility issues
Manual management - Cloning skills from git repos requires extra steps per project
Sharing overhead - Teams must commit cloned files or repeat setup on each machine

This project proposes a convention: ship skills inside npm packages. When you npm install a tool, its skills come bundled. Run skills-npm to symlink them for your agent.

Read the full proposal: PROPOSAL.md

Usage

Install as a dev dependency and run setup once:

npm i -D skills-npm
npx skills-npm setup

skills-npm setup wires the tool into your package.json prepare script, adds the ignore pattern to your .gitignore, and runs the first sync. After that, skills are re-symlinked for your agent automatically whenever you install dependencies.

setup merges into any existing prepare script (it appends with && and is a no-op if already wired), resulting in:

{
  "private": true,
  "scripts": {
    "prepare": "skills-npm"
  }
}

skills-npm symlinks the skills from node_modules to skills/npm-<package-name>-<skill-name> for your agent, and setup adds the following to your .gitignore:

**/skills/npm-*

Note

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.

Configuration

You can create a skills-npm.config.ts file in your project root to configure the behavior:

// skills-npm.config.ts
import { defineConfig } from 'skills-npm'

export default defineConfig({
  // Source to discover skills from: 'node_modules' or 'package.json'
  source: 'package.json',
  // Target specific agents (defaults to all detected agents)
  agents: ['cursor', 'windsurf'],
  // Scan recursively for monorepo packages (default: false)
  recursive: false,
  // Whether to update .gitignore (default: true)
  gitignore: true,
  // Skip confirmation prompts (default: false)
  yes: false,
  // Dry run mode (default: false)
  dryRun: false,
  // Include specific packages or skills
  include: [
    // Include all skills from a package
    '@some/package',
    // Include all skills from packages matching a wildcard pattern
    '@some/*',
    // Include specific skills from packages matching a wildcard pattern
    { package: '@some/*', skills: ['integration'] },
    // Include specific skills from a package
    { package: '@slidev/cli', skills: ['presenter-mode'] },
  ],
  // Exclude specific packages or skills
  exclude: [
    // Exclude all skills from a package
    '@some/package',
    // Exclude all skills from packages matching a wildcard pattern
    '@some/*',
    // Exclude specific skills from packages matching a wildcard pattern
    { package: '@some/*', skills: ['integration'] },
    // Exclude specific skills from a package
    { package: '@slidev/cli', skills: ['presenter-mode'] },
  ],
})

include and exclude support package wildcard patterns such as @some/*. These filters only apply to packages that were already discovered from node_modules or package.json.

Options

Option	Type	Default	Description
`cwd`	`string`	Workspace root	Current working directory
`source`	`'node_modules' \| 'package.json'`	`'package.json'`	Source to discover skills from
`agents`	`string \| string[]`	All detected	Target agents to install to
`recursive`	`boolean`	`false`	Scan recursively for monorepo packages
`gitignore`	`boolean`	`true`	Whether to update .gitignore
`yes`	`boolean`	`false`	Skip confirmation prompts
`dryRun`	`boolean`	`false`	Show what would be done without making changes
`include`	`(string \| { package: string, skills: string[] })[]`	`undefined`	Packages or skills to include. Supports package wildcard patterns like `@some/*`
`exclude`	`(string \| { package: string, skills: string[] })[]`	`[]`	Packages or skills to exclude. Supports package wildcard patterns like `@some/*`

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.

CLI Options

skills-npm [options]          # discover and symlink skills (run by the prepare hook)
skills-npm setup [options]    # add the prepare script, then run the first sync (run once)

Options:
  --cwd <cwd>             Current working directory
  -s, --source <source>   Source to discover skills from (default: 'package.json')
  -a, --agents            Comma-separated list of agents to install to
  -r, --recursive         Scan recursively for monorepo packages
  --yes                   Skip confirmation prompts
  --dry-run               Show what would be done without making changes
  --force                 Force full reload, ignore cache
  --no-cleanup            Keep stale npm-* skills in agent directories
  --no-gitignore          Do not update .gitignore
  -h, --help              Display help
  -v, --version           Display version

Agent detection

When agents is not set, skills-npm auto-detects which coding agents you use and installs to those. Detection combines two signals:

Config directory - an agent's home directory exists (e.g. ~/.cursor, ~/.claude).
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.

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.

In an interactive terminal, the prompt lists all agents with the detected ones pre-selected, so you can add or remove any. 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.

For Package Authors

Include a skills/ directory in your package:

my-tool/
├── package.json
├── dist/
└── skills/
    └── my-skill/
        └── SKILL.md

See PROPOSAL.md for detailed instructions.

Showcases

Packages that ships their built-in skills: