skills-npm

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

[!IMPORTANT] This project is a work in progress.

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:

• @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