skills-npm

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