skills-npm

April 8, 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

npm i -D skills-npm

Add a prepare script to your package.json so the skills are symlinked automatically for your agent whenever you install dependencies:

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

skills-npm will symbol links the skills from node_modules to skills/npm-<package-name>-<skill-name> for your agent. It's recommend to add the following to your .gitignore:

skills/npm-*

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]

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
  --ignore-paths <paths>  Ignore paths for searching package.json
  --gitignore             Whether to update .gitignore (default: true)
  --yes                   Skip confirmation prompts
  --dry-run               Show what would be done without making changes
  -h, --help              Display help
  -v, --version           Display version

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:

Note

PR are welcome to add more packages that ships their built-in skills.