Getting Started

pnpm (Recommended)

Standalone CLI

npm / yarn / bun

1. Get started with `pnpm-plugin-skills`

If your project already uses pnpm, the easiest way to adopt skills-package-manager is to start from pnpm install and let skill installation happen automatically inside the existing dependency workflow.

Install the pnpm plugin

Add the plugin to your workspace configuration:

pnpm add pnpm-plugin-skills --config

This tells pnpm to load pnpm-plugin-skills during installation.

Bootstrap the manifest

Run the same command for new projects and migrated projects:

npx skills-package-manager install

If local skills already exist, install migrates them into skills.json as local:* entries. If no local skills exist yet, it writes an empty default manifest.

Add skills when needed

add updates skills.json, installs the selected skills, and links configured agent targets:

# Interactive — clone repo, discover skills, select via multiselect prompt
npx skills-package-manager add vercel-labs/skills
npx skills-package-manager add https://github.com/rstackjs/agent-skills

# Non-interactive — add one or more specific skills by name
npx skills-package-manager add vercel-labs/skills --skill find-skills
npx skills-package-manager add vercel-labs/skills -s frontend-design -s skill-creator
npx skills-package-manager add vercel-labs/skills@find-skills

# skills CLI-compatible inspection and broad install flags
npx skills-package-manager add vercel-labs/skills --list
npx skills-package-manager add vercel-labs/skills --all

# Direct repo subpath or local path
npx skills-package-manager add https://github.com/tool-belt/skills/tree/main/guides/design/landing-page-design
npx skills-package-manager add ./my-skills

GitHub sources are written to skills.json using pinned github:owner/repo#<commit>&path:<path> specifiers.

Example skills.json:

{
  "installDir": ".agents/skills",
  "linkTargets": [".claude/skills"],
  "skills": {
    "find-skills": "github:vercel-labs/skills#abc1234&path:/skills/find-skills"
  }
}

This manifest defines:

installDir: where managed skills are materialized
linkTargets: which agent-specific directories receive links
selfSkill: whether to auto-install the bundled skills-package-manager-cli skill for help with skills.json and npx skills-package-manager commands. Defaults to false
skills: which skills should be installed

Run pnpm as usual

Now run the normal install command:

pnpm install

During this process, the plugin will:

Read skills.json
Resolve each skill source
Materialize skills into installDir
Link them into every directory listed in linkTargets

That means your regular pnpm bootstrap flow now also restores agent skill context.

Add `.agents/skills` etc to `.gitignore`

Since the skill directories are generated artifacts, you should add them to .gitignore:

.gitignore

.agents/skills
.claude/skills

2. Add more skills when needed

When you want to introduce another skill, you can either edit skills.json directly or use the CLI to update the manifest:

npx skills-package-manager add vercel-labs/skills --skill find-skills
npx skills-package-manager add https://github.com/rstackjs/agent-skills --skill rspress-custom-theme
npx skills-package-manager add vercel-labs/skills --list

3. Refresh remote skill versions

When remote git-based (URL or github:) or npm: skills should move forward, run:

npx skills-package-manager update

Then run:

pnpm install

update writes newer pins back to skills.json; pnpm install then restores the linked directories from that manifest.

1. Quick Start

If you're not using pnpm, start every project with the same command. install creates skills.json for new projects and migrates existing local skills when they are present.

Bootstrap the project

npx skills-package-manager install

If skills.json does not exist yet, install writes one. For migrated projects, it scans .agents/skills and .agent/skills, reuses matching skills-lock.json entries when present, and writes local:* entries. For new projects, it writes an empty manifest that is ready for add.

Add skills when needed

Select from a variety of sources (Git, NPM, Local).

# Interactive mode (discovers skills in a repo)
npx skills-package-manager add rstackjs/agent-skills

# Explicitly add a specific skill
npx skills-package-manager add rstackjs/agent-skills --skill pr-creator

# List skills or install all skills using skills CLI-compatible flags
npx skills-package-manager add rstackjs/agent-skills --list
npx skills-package-manager add rstackjs/agent-skills --all

add updates skills.json, installs the selected skills, and links them into configured agent folders.

Restore on another machine

npx skills-package-manager install

This command will:

Resolve each specifier from skills.json.
Download/Copy files to .agents/skills.
Symlink them to your agent folders (e.g., .claude/skills).

Tip

Remember to add .agents/skills and your agent link targets to your .gitignore to keep your repository lean!

2. Advanced Workflow

Update to latest versions

To move remote git skills to the latest main commit and npm skills to the registry latest version:

npx skills-package-manager update

Link local developments

Use the link: protocol in skills.json for rapid local skill testing without publishing.

Use the local: protocol when a skill already lives in a user-owned directory such as .agents/skills/my-skill and should not be copied, replaced, or pruned by SPM.

Lifecycle Integration

For npm, yarn, or bun, you can seamlessly integrate SPM into your project's lifecycle using the prepare script. This ensures your agent skills are automatically synchronized every time you run a fresh install.

Install SPM as a dev dependency

Add skills-package-manager to your project's devDependencies.

npm install -D skills-package-manager
# or
yarn add -D skills-package-manager
# or
bun add -d skills-package-manager

Configure the prepare script

Update your package.json to include the prepare lifecycle hook:

{
  "scripts": {
    "prepare": "skills-package-manager install"
  }
}

Bootstrap and Add Skills

Run the same bootstrap command first for both new projects and migrated projects. Then add skills when needed:

npx skills-package-manager install
npx skills-package-manager add <source>

Info

The prepare script runs automatically after npm install (and equivalent commands in Yarn/Bun), guaranteeing that your .agents/skills directory and agent symlinks are always up to date.

#Getting Started

#1. Get started with pnpm-plugin-skills

#Install the pnpm plugin

#Bootstrap the manifest

#Add skills when needed

#Run pnpm as usual

#Add .agents/skills etc to .gitignore

#2. Add more skills when needed

#3. Refresh remote skill versions

#1. Quick Start

#Bootstrap the project

#Add skills when needed

#Restore on another machine

#2. Advanced Workflow

#Update to latest versions

#Link local developments

#Lifecycle Integration

#Install SPM as a dev dependency

#Configure the prepare script

#Bootstrap and Add Skills

Getting Started

1. Get started with `pnpm-plugin-skills`

Install the pnpm plugin

Bootstrap the manifest

Add skills when needed

Run pnpm as usual

Add `.agents/skills` etc to `.gitignore`

2. Add more skills when needed

3. Refresh remote skill versions

1. Quick Start

Bootstrap the project

Add skills when needed

Restore on another machine

2. Advanced Workflow

Update to latest versions

Link local developments

Lifecycle Integration

Install SPM as a dev dependency

Configure the prepare script

Bootstrap and Add Skills