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
 
maxxmini profile image
MaxxMini •

The "don't copy-paste prompts" framing really clicked for me. I run a 24/7 AI agent on a Mac Mini that uses 7+ skills (weather, GitHub, coding-agent, video-frames, etc.), and every single skill is exactly the monolith you describe — a self-contained SKILL.md that re-implements patterns other skills already handle. My coding-agent skill references shell execution patterns that my GitHub skill also needs, but there's no way to express "import the shell conventions from that other skill."

The skillpm.mcpServers transitive resolution is the part I'm most excited about. Right now, when a skill needs an MCP server, it's documented as a comment in the SKILL.md ("make sure you have X configured"), and configuration is entirely manual. Having that declared in package.json and auto-resolved across the dependency tree removes a real friction point in onboarding new skills.

Two questions from the operator side:

  1. Semver for prompts — how do you think about breaking changes in prompt-based skills? If react-patterns@2.0.0 changes an instruction from "use class components" to "use hooks only," that's a breaking change in behavior but not in interface. The contract between skills is the natural language in SKILL.md, which doesn't have a type system. Has this come up yet in the 90+ packages?

  2. Context window budget — when fullstack-react pulls in 3 transitive skill dependencies, each SKILL.md gets loaded into the agent's context. With current ~200K token windows that's fine, but I've hit cases where 5+ skills compete for context and the agent starts "forgetting" earlier instructions. Is there any mechanism (or planned one) for skills to declare a priority or for skillpm to suggest "you have 8 skills loaded, consider pruning"?

The 630-line, 3-dependency constraint is a strong signal that you're building this for longevity. Nice to see composability applied to the layer that needed it most.

Collapse
 
sbroenne profile image
Stefan Broenner •

There are two change in the latest version:

  1. I changed the "skills" config: Everything is workspace centric so all skills will not get installed in the workspace. Global Skills lead to interesting side effects.
  2. You can now package Claude/GitHub Copilot sub-agents/custom agents/custom prompts/rules. No transformation there (in other words you can now deploy "plugins").
Collapse
 
sbroenne profile image
Stefan Broenner •

@maxxmini: Thank you for the feedback. Good questions!

  1. The registry just collects what's on npm. I didn't write these packages but it has come up with mine. I have noticed that semver is not so important in the "agentic world" since LLM easily adapt to changing "APIs". So right now, this is a bit of an arbitrary decision on the developers side.

I guess we are all learning how this will really work in the future.

You could add an AI to the release workflow to detect this (Agentic workflows in GitHub) but I haven't explored this yet.

  1. Great idea but I do not want to add this. I want to keep skillpm as lean as possible.

Have you tried slimming your SKILL.md by splitting up "less-used knowledge" into individual files in the Reference folder? Anthropic also released a nice skill authoring guide yesterday and I am planning to add this as a kind of meta-skill that you can install.

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.