Skillpm

skillpm — Agent Skill Package Manager

When to use this skill

Use this skill when the user wants to:

• Install, uninstall, or update Agent Skill packages
• Create (scaffold) a new Agent Skill package
• Publish an Agent Skill to npmjs.org
• List installed skills or check their dependency trees
• Configure MCP servers required by skills
• Re-wire agent directories after manual changes

Key concepts

• skillpm wraps npm. All packages live on npmjs.org. Same package.json, same node_modules/, same package-lock.json.
• One skill per npm package. The skill lives in skills/<name>/SKILL.md inside the package.
• Transitive dependency resolution. skillpm walks the full dependency tree to discover all skills and MCP server requirements.
• Agent directory wiring. skillpm uses the skills CLI to link installed skills into 37+ agent directories (Claude, Cursor, VS Code, Codex, Gemini CLI, etc.).
• Config files. Skills can include a configs/ directory to ship native agent config files (subagent definitions, rules, prompts). The directory mirrors the workspace layout — files are copied on install with an auto-prefix (de-scoped package name, or a shorter skillpm.configPrefix override) to prevent conflicts.
• MCP server configuration. Skills can declare MCP servers in package.json under skillpm.mcpServers[]. skillpm configures them via add-mcp.

Commands

All commands can be run without global install via npx skillpm <command>.

Install a skill

npx skillpm install <skill-name>
# Aliases: skillpm i, skillpm add

This runs npm install, scans node_modules/ for skill packages, links them into agent directories, copies config files, and configures any required MCP servers.

Install all dependencies

npx skillpm install

Reads package.json, installs all dependencies, and wires discovered skills.

Uninstall a skill

npx skillpm uninstall <skill-name>
# Aliases: skillpm rm, skillpm remove

List installed skills

npx skillpm list
# Aliases: skillpm ls
npx skillpm list --json   # machine-readable JSON output

Shows all installed skill packages with descriptions and MCP server requirements. Use --json for scripting.

Scaffold a new skill

npx skillpm init

Creates package.json (with "agent-skill" keyword) and skills/<name>/SKILL.md in the current directory. Edit the SKILL.md to define the skill.

Publish a skill

npx skillpm publish

Validates the package structure and SKILL.md against the Agent Skills spec (via skills-ref validate), then delegates to npm publish.

Re-wire agent directories

npx skillpm sync

Re-scans node_modules/ and re-links all skills into agent directories without reinstalling. Useful after manual changes.

Monorepo / npm workspace support: If your repo uses npm workspaces, npm creates symlinks in node_modules/ pointing to your first-party skill packages. skillpm sync detects these symlinks and copies their configs/ files into the workspace root — same as for externally installed skills. Contributors run skillpm sync after editing a skill's source files, then commit the regenerated configs.

node_modules/
  @org/
    my-skill → ../../skills/my-skill   ← symlink (npm workspace)

Workspace packages appear in sync output as: Linking workspace package @org/my-skill@1.0.0.

Configure MCP servers

npx skillpm mcp add <source>    # Add an MCP server (delegates to add-mcp)
npx skillpm mcp list            # List configured MCP servers

npm passthrough

Any command not handled by skillpm is passed through to npm:

npx skillpm outdated            # → npm outdated
npx skillpm audit               # → npm audit
npx skillpm update              # → npm update
npx skillpm why <skill>         # → npm why <skill>

This means skillpm is a superset of npm — all npm commands work transparently.

Creating a skill package

Package structure

my-skill/
├── package.json                 # keywords: ["agent-skill"], dependencies, skillpm.mcpServers
├── README.md
├── LICENSE
├── skills/
│   └── my-skill/
│       ├── SKILL.md             # Skill definition (YAML frontmatter + Markdown body)
│       ├── scripts/             # Optional executable scripts
│       ├── references/          # Optional reference docs
│       └── assets/              # Optional templates/data
└── configs/                      # Optional — mirrors workspace layout
    ├── .claude/
    │   ├── agents/reviewer.md   # Claude subagent
    │   └── rules/conventions.md # Claude rules
    ├── .cursor/
    │   ├── agents/reviewer.md   # Cursor agent
    │   └── rules/conventions.md # Cursor rules
    └── .github/
        ├── agents/reviewer.md   # Copilot agent
        └── instructions/conventions.instructions.md

package.json for a skill

{
  "name": "my-skill",
  "version": "1.0.0",
  "keywords": ["agent-skill"],
  "repository": {
    "type": "git",
    "url": "git+https://github.com/user/repo.git"
  },
  "dependencies": {
    "other-skill": "^1.0.0"
  },
  "skillpm": {
    "mcpServers": ["@anthropic/mcp-server-filesystem"]
  }
}

• Skill dependencies go in standard dependencies — npm handles resolution.
• The skillpm.mcpServers array lists MCP servers that agents need for this skill.
• The "agent-skill" keyword is required for publishing.
• Use git+https:// prefix for repository.url (npm requires this format).

Bundling agent configs, rules, and prompts

SKILL.md teaches agents what to do — instructions read at runtime. The configs/ directory lets you also ship config files (subagent definitions, rules, instructions) in the native format of each agent system. It mirrors the workspace layout — files get copied to the workspace root on install, auto-prefixed to avoid conflicts.

The prefix used is: configPrefix (if set in skillpm field) → de-scoped package name (e.g. @acme/fullstack-react → fullstack-react). Set configPrefix to a short name when the package name is long.

Each agent system uses different names and directories:

To ship config files, create a configs/ directory that mirrors the workspace layout for each target system:

On uninstall, all copied files are removed automatically (tracked via .skillpm/manifest.json).

Not every skill needs configs/ — only use it when you want to ship native agent config files. Since configs/ contains dotfile directories, add them to package.json files:

{
  "files": ["skills/", "configs/"]
}

SKILL.md frontmatter

---
name: my-skill
description: What this skill does.
license: MIT
allowed-tools: Bash Read
---

Version comes from package.json — do not duplicate it in SKILL.md.

Creating a skill package

Scaffold from scratch

mkdir my-skill && cd my-skill
npx skillpm init
# Edit skills/my-skill/SKILL.md with instructions
# Edit package.json to add dependencies and MCP servers
npx skillpm publish

Wrap an existing skill for npm

If you already have a skills/<name>/SKILL.md (e.g. from npx skills add), add a package.json to make it publishable:

cd my-existing-skill/
npm init -y

Then edit package.json to add the required keyword and optional MCP servers:

{
  "name": "my-existing-skill",
  "version": "1.0.0",
  "keywords": ["agent-skill"],
  "skillpm": {
    "mcpServers": ["@some/mcp-server"]
  }
}

Ensure the directory structure matches:

my-existing-skill/
├── package.json                 # Must have "agent-skill" in keywords
└── skills/
    └── my-existing-skill/
        └── SKILL.md             # Must have name and description in frontmatter

Then validate and publish:

npx skillpm publish

skillpm publish validates before publishing:

• package.json exists with "agent-skill" keyword
• skills/<name>/SKILL.md exists
• SKILL.md validates against the Agent Skills spec (skills-ref validate): name format, required fields, directory naming

Error handling

• If skillpm install fails, check that npm can resolve the package: npm view <skill-name>
• If skillpm publish fails with a keyword error, add "agent-skill" to the keywords array in package.json
• If skills aren't appearing in agent directories after install, run npx skillpm sync to re-wire