DEV Community

Cover image for skillpm - Package Manager for Agent Skills. Built on npm.
Stefan Broenner
Stefan Broenner

Posted on

skillpm - Package Manager for Agent Skills. Built on npm.

#npm #showdev #agentskills #skillsengineering

Every agent skill today is a monolith.

Authors cram React patterns, TypeScript best practices, and testing guidelines into a single massive SKILL.md — because there's no way to say "just depend on that other skill." No registry. No dependency management. No versioning. The Agent Skills spec defines what a skill is, but says nothing about how to publish, install, or share them.

We (Sonnet 4.6 & myself) built skillpm to fix that — a lightweight orchestration layer on top of npm. ~630 lines of code, 3 dependencies, zero reinvention. Small skills that compose, not monoliths that overlap.

The idea: don't reinvent npm — extend it

When we started, the tempting path was to build a custom registry, a custom resolver, a custom lockfile format. We chose the opposite.

skillpm is a thin orchestration layer on top of npm. Same package.json. Same node_modules/. Same package-lock.json. Same registry (npmjs.org). skillpm only adds what npm can't do on its own:

  1. Scanning node_modules/ for packages containing skills/*/SKILL.md
  2. Wiring discovered skills into agent directories via skills (Claude, Cursor, VS Code, Codex, and many more)
  3. Configuring MCP servers declared by skills, transitively across the dependency tree, via add-mcp

That's it. Everything else — resolution, caching, lockfiles, audit, semver — is npm.

How it works 

# Install a skill (no global install needed)
npx skillpm install excel-mcp-skill

# List what's installed
npx skillpm list

# Scaffold a new skill
npx skillpm init
Enter fullscreen mode Exit fullscreen mode

When you run npx skillpm install <skill>, here's what happens:

npx skillpm install react-patterns
  │
  ▼
📦 npm install react-patterns
   npm handles resolution, download, lockfile
  │
  ▼
🔍 Scan node_modules/
   find packages with skills/*/SKILL.md
  │
  ▼
🔗 npx skills add ./node_modules/...
   wire into Claude, Cursor, VS Code, Codex...
  │
  ▼
📄 Read skillpm.mcpServers
   walk entire dependency tree
  │
  ▼
🔌 npx add-mcp <server>
   configure each MCP server across agents
Enter fullscreen mode Exit fullscreen mode

Four tools, each doing one thing well, orchestrated together.

What a skill package looks like

A skill is just an npm package with a specific directory structure:

my-skill/
├── package.json          # keywords: ["agent-skill"]
├── README.md
├── LICENSE
└── skills/
    └── my-skill/
        ├── SKILL.md      # The skill definition
        ├── scripts/      # Optional executable scripts
        ├── references/   # Optional reference docs
        └── assets/       # Optional templates/data
Enter fullscreen mode Exit fullscreen mode

The SKILL.md is where the magic lives — YAML frontmatter for metadata, Markdown body with instructions for the agent:

---
name: my-skill
description: "Refactor React class components to functional components with hooks."
allowed-tools: Bash Read Edit
---

# React Refactoring

## When to use this skill
Use when the user asks to modernize React components...

## Instructions
1. Identify class components in the target files
2. Convert lifecycle methods to useEffect hooks
3. ...
Enter fullscreen mode Exit fullscreen mode

Skills can depend on other skills

This is where it gets interesting. Because skills are npm packages, they can depend on each other. This solves the biggest problem with Agent Skills today: prompt bloat.

Without dependency management, if you want a skill that builds a full-stack React app, you have to copy-paste instructions for React, TypeScript, testing, and styling into one massive SKILL.md. The agent gets overwhelmed, context windows fill up, and the skill becomes impossible to maintain.

skillpm brings standard software engineering practices to Agent Skills. You don't copy-paste code anymore; you shouldn't copy-paste prompts either. With skillpm, you just declare dependencies:

{
  "name": "fullstack-react",
  "version": "1.0.0",
  "keywords": ["agent-skill"],
  "dependencies": {
    "react-patterns": "^2.0.0",
    "typescript-best-practices": "^1.3.0",
    "testing-with-vitest": "^1.0.0"
  },
  "skillpm": {
    "mcpServers": ["@anthropic/mcp-server-filesystem"]
  }
}
Enter fullscreen mode Exit fullscreen mode

npx skillpm install fullstack-react resolves the entire tree — all three dependencies get installed, scanned, wired into agents, and their MCP servers configured. One command.

Instead of monolithic, 500-line prompt files, you can build small, composable, single-purpose skills that build on top of each other. It's modularity for AI.

MCP server configuration, handled

Skills often need MCP servers to function. The skillpm.mcpServers field declares those requirements:

{
  "skillpm": {
    "mcpServers": [
      "@anthropic/mcp-server-filesystem",
      "https://mcp.context7.com/mcp"
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

skillpm walks the entire dependency tree, collects all MCP server requirements (deduplicated), and configures each one via add-mcp. The user never has to manually configure MCP servers.

The ecosystem today

There are already 90+ skill packages on npm with the agent-skill keyword. We built an Agent Skills Registry that indexes them all — searchable, filterable by keyword, sortable by downloads or recency.

Most existing packages follow the original spec (root SKILL.md) rather than our npm packaging convention (skills/<name>/SKILL.md). skillpm handles both — legacy packages get installed with a friendly warning pointing to the migration guide.

Create and publish a skill in 60 seconds 

mkdir my-awesome-skill && cd my-awesome-skill
npx skillpm init
# Edit skills/my-awesome-skill/SKILL.md with your instructions
npx skillpm publish
Enter fullscreen mode Exit fullscreen mode

That's literally it. Your skill is now on npmjs.org, discoverable by anyone running npx skillpm install my-awesome-skill, and automatically wired into their agents.

Why not just use npm directly?

You can! Skills are valid npm packages. But skillpm adds what npm install alone can't do:

  • ✅ Scan for SKILL.md files in installed packages
  • ✅ Link skills into agent directories via skills
  • ✅ Configure MCP servers via add-mcp
  • ✅ Validate skill packages before publishing
  • ✅ Show you what skills are installed and where they're wired

That's the gap skillpm fills. It's npm + skill awareness.

Built on the shoulders of giants

We deliberately don't reinvent anything. skillpm shells out to four battle-tested tools:

Tool What it does How skillpm uses it
npm Package management All installs, resolution, lockfiles, caching
skills (Vercel) Agent directory linking Wires skills into agent directories
add-mcp MCP server configuration Configures servers across agents
skills-ref Spec validation Validates SKILL.md during publish

Get started 

# Try it now — no install required
npx skillpm install skillpm-skill

# Browse the registry
# https://skillpm.dev/registry/
Enter fullscreen mode Exit fullscreen mode

We're actively looking for contributors! 🤝

skillpm is a young project, and there's a lot of room to grow. Whether it's adding support for new agent directories, improving the CLI experience, or building out the registry, we'd love your help. Check out the GitHub repo and look for the good first issue label!

We'd love your feedback. Open an issue, try publishing a skill, or just tell us what you think.

What kind of skills are you building for your AI agents? Is this useful? What are we missing (e.g. custom agents, / prompts)? Let me know in the comments!

skillpm is MIT licensed and open source.

Top comments (4)

Collapse
 
snapsynapse profile image
snapsynapse •

Great timing on this. The "skills are just text files, use existing package infrastructure" insight is perfect, and building on npm instead of reinventing registry.

I've been working on the author side of a related problem: what happens before a skill reaches a package manager? When you're developing a skill across Claude Chat, then porting it to Code, then to Codex, there's no persistent filesystem connecting those surfaces. Version identity gets lost at every handoff.

I built skill-provenance a couple weeks ago to solve this: embedded version tracking, manifest with hashes, and a changelog that travels inside the skill bundle. The idea is that by the time a skill reaches a distribution tool like skillpm, it already knows what it is. Version, completeness, what changed, what's stale.

Feels like there's a natural handshake between author-side provenance and consumer-side package management. Would be curious if you've run into the "which version of this skill did I just upload?" problem yet with your users.

Some comments may only be visible to logged-in visitors. Sign in to view all comments.