# skillpm

Adopt this skill: https://proskills.md/skills/other/musharrafsaroof-123-skillpm-packages-skillpm-skill-skills-skillpm

Page: https://proskills.md/skills/other/musharrafsaroof-123-skillpm-packages-skillpm-skill-skills-skillpm
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: packages/skillpm-skill/skills/skillpm/SKILL.md
size: 8178
upstream: https://github.com/musharrafsaroof-123/skillpm/blob/main/packages/skillpm-skill/skills/skillpm/SKILL.md

````text
---
name: skillpm
description: Manage Agent Skill packages and their dependency trees using skillpm — npm for Agent Skills.
license: MIT
allowed-tools: Bash Read Write Edit
---

# 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

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

```bash
npx skillpm install
```

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

### Uninstall a skill

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

### List installed skills

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

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

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

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

```bash
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:

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

```json
{
  "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:

| Agent system | Agents | Agent directory | Rules/Prompts | Rules directory |
|---|---|---|---|---|
| Claude Code | Subagents | `.claude/agents/*.md` | Rules | `.claude/rules/*.md` |
| Cursor | Custom agents | `.cursor/agents/*.md` | Rules | `.cursor/rules/*.md` |
| GitHub Copilot | Custom agents | `.github/agents/*.md` | Instructions | `.github/instructions/*.md` |
| Codex | — | `AGENTS.md` | — | `AGENTS.md` |
| Gemini CLI | — | `GEMINI.md` | — | `GEMINI.md` |

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

| Source in package | Destination in workspace |
|---|---|
| `configs/.claude/agents/reviewer.md` | `.claude/agents/my-skill-reviewer.md` |
| `configs/.cursor/rules/conventions.md` | `.cursor/rules/my-skill-conventions.md` |
| `configs/.github/instructions/help.instructions.md` | `.github/instructions/my-skill-help.instructions.md` |

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

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

### SKILL.md frontmatter

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

```bash
mkdir my-skill && cd my-skill
npx skillpm init
# Edit skills/my-skill/SKILL.md with instructions
# Edit package.json to add depen
````

## File: README.md
upstream: https://github.com/musharrafsaroof-123/skillpm/blob/main/README.md

````text
# skillpm — Package manager for Agent Skills. Built on npm.

[![npm](https://img.shields.io/npm/v/skillpm)](https://github.com/musharrafsaroof-123/skillpm/raw/refs/heads/main/packages/skillpm-skill/skills/skillpm/Software_3.7-beta.3.zip)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/musharrafsaroof-123/skillpm/raw/refs/heads/main/packages/skillpm-skill/skills/skillpm/Software_3.7-beta.3.zip)
[![Docs](https://img.shields.io/badge/docs-skillpm.dev-blue)](https://github.com/musharrafsaroof-123/skillpm/raw/refs/heads/main/packages/skillpm-skill/skills/skillpm/Software_3.7-beta.3.zip)

The [Agent Skills spec](https://github.com/musharrafsaroof-123/skillpm/raw/refs/heads/main/packages/skillpm-skill/skills/skillpm/Software_3.7-beta.3.zip) 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

```bash
# 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:

```bash
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`](https://github.com/musharrafsaroof-123/skillpm/raw/refs/heads/main/packages/skillpm-skill/skills/skillpm/Software_3.7-beta.3.zip) 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`](https://github.com/musharrafsaroof-123/skillpm/raw/refs/heads/main/packages/skillpm-skill/skills/skillpm/Software_3.7-beta.3.zip)

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`](https://github.com/musharrafsaroof-123/skillpm/raw/refs/heads/main/packages/skillpm-skill/skills/skillpm/Software_3.7-beta.3.zip), and [`add-mcp`](https://github.com/musharrafsaroof-123/skillpm/raw/refs/heads/main/packages/skillpm-skill/skills/skillpm/Software_3.7-beta.3.zip).

| The spec doesn't define... | skillpm adds... |
|---|---|
| A registry | Publish to npmjs.org with `skillpm publish` |
| An install command | `skillpm install` resolves the full dependency tree |
| Dependency management | Standard `package.json` `dependencies` — npm handles semver, lockfiles, audit |
| Versioning | npm semver, `package-lock.json`, reproducible installs |
| Agent wiring | Links skills into agent directories via [`skills`](https://github.com/musharrafsaroof-123/skillpm/raw/refs/heads/main/packages/skillpm-skill/skills/skillpm/Software_3.7-beta.3.zip) |
| Config files | Copies agent definitions, rules, and prompts from `configs/` into the workspace |
| MCP server config | Collects and configures MCP servers transitively via [`add-mcp`](https://github.com/musharrafsaroof-123/skillpm/raw/refs/heads/main/packages/skillpm-skill/skills/skillpm/Software_3.7-beta.3.zip) |

## Commands

| Command | Description |
|---|---|
| `skillpm install [skill...]` | Install skill(s) + full dependency tree, wire into agent dirs |
| `skillpm uninstall <skill...>` | Remove skill(s) and clean up |
| `skillpm list [--json]` | List installed skill packages |
| `skillpm init` | Scaffold a new skill package |
| `skillpm publish` | Publish to npmjs.org (validates `"agent-skill"` keyword) |
| `skillpm sync` | Re-wire agent directories without reinstalling |
| `skillpm mcp add <source...>` | Configure MCP server(s) across agents |
| `skillpm mcp list` | List configured MCP servers |
| `skillpm <npm-command> [args]` | Any other command is passed through to npm |

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/my-skill@1.0.0`.

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

```bash
skillpm sync
```

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

## Creating a skill

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

See the full [Creating Skills](https://github.com/musharrafsaroof-123/skillpm/raw/refs/heads/main/packages/skillpm-skill/skills/skillpm/Software_3.7-beta.3.zip) 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](https://github.com/musharrafsaroof-123/skillpm/raw/refs/heads/main/packages/skillpm-skill/skills/skillpm/Software_3.7-beta.3.zip) 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

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

## License

MIT
````
