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:

• undefinedGit-only source - Only supports git repos as skills source
• undefinedVersion mismatch - Skills and tools update separately, causing compatibility issues
• undefinedManual management - Cloning skills from git repos requires extra steps per project
• undefinedSharing 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.

undefinedRead the full proposal: PROPOSAL.mdundefined

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({
  // 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 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 specific skills from a package
    { package: '@slidev/cli', skills: ['presenter-mode'] },
  ],
})

Options

Option	Type	Default	Description
cwd	string	Workspace root	Current working directory
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 (only these will be installed)
exclude	(string | { package: string, skills: string[] })[]	[]	Packages or skills to exclude from being installed

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

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

Sponsors

License

MIT License © Anthony Fu