skillpm

skillpm — Package manager for Agent Skills. Built on npm.

The Agent Skills spec defines what a skill is — but not how to publish, install, version, or share them. There's no registry, no dependency management, no way for one skill to build on another. Without dependencies, skills become monoliths — authors duplicate instructions because there's no way to reuse another skill.

skillpm fills that gap. It's a lightweight orchestration layer — ~630 lines of code, 3 runtime dependencies — that maps Agent Skills onto npm's ecosystem. Same package.json, same node_modules/, same registry. Skills become npm packages you can publish, install, version, and depend on — just like any other package. Small skills that compose, not monoliths that overlap.

Quick start

# Install a skill (no global install needed)
npx skillpm install <skill-name>

# List installed skills
npx skillpm list

# Scaffold a new skill package
npx skillpm init

Or install the CLI globally:

npm install -g skillpm

Note: Skills are always workspace-local. This installs the skillpm CLI — not skills.

How it works

When you run skillpm install <skill>:

1. npm install — npm handles resolution, download, lockfile, node_modules/
2. Scan — skillpm scans node_modules/ for packages containing skills/*/SKILL.md
3. Link — for each skill found, skillpm calls skills to wire it into agent directories (Claude, Cursor, VS Code, Codex, and many more)
4. Configs — for each skill with a configs/ directory, skillpm copies agent definitions, rules, and prompts into the workspace (auto-prefixed to avoid conflicts)
5. MCP config — skillpm collects skillpm.mcpServers from all skills (transitively) and configures each via add-mcp

That's it. Agents see the full skill tree with MCP servers configured.

What's missing from the spec — and what skillpm adds

skillpm doesn't reinvent anything. It orchestrates three battle-tested tools: npm, skills, and add-mcp.

Commands

Aliases: i/add for install, rm/remove for uninstall, ls for list.

Monorepo / npm workspace support

If your repo is an npm workspace monorepo where each skill is a first-party package (e.g. skills/<name>/ entries in the root package.json workspaces field), npm installs them as symlinks inside node_modules/:

node_modules/
  @org/
    my-skill → ../../skills/my-skill   ← symlink

skillpm sync (and skillpm install) automatically detects these symlinks and treats them as workspace packages:

• Configs are copied from the symlinked skill's configs/ directory into the workspace root, exactly as for externally installed skills.
• Workspace packages are identified in log output: Linking workspace package @org/[email protected].

This lets contributors regenerate deployed copies (agent definitions, prompts, rules) by running:

skillpm sync

No manual copy steps needed. Commit the regenerated files as usual.

Creating a skill

mkdir my-skill && cd my-skill
skillpm init

See the full Creating Skills guide for package structure, SKILL.md format, dependencies, and publishing.

What are Agent Skills?

Agent Skills are modular, reusable packages of instructions, scripts, and resources that AI agents can dynamically load to extend their capabilities. They follow an open standard adopted by Claude, Codex, Cursor, Gemini CLI, Augment, and others.

How this relates to plugin specs (GitHub CLI / Claude Code)

Plugin specs and Agent Skills solve different layers:

• Plugin specs define host-specific runtime integrations (for example, how one tool can load an extension).
• Agent Skills define reusable instruction packages that can be shared across agent systems.

For skillpm, this does not change the core approach: skills remain npm packages, dependency resolution stays in npm, and wiring/config is still handled by skills + add-mcp.

Development

npm install           # install dependencies
npm run build         # compile TypeScript
npm test              # run tests
npm run lint          # lint

License

MIT