skills-npm

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:

• @slidev/cli
• eslint-vitest-rule-tester
• @vitejs/devtools-kit
• @vueuse/skills

[!NOTE]
PR are welcome to add more packages that ships their built-in skills.

Sponsors

License

MIT License © Anthony Fu