Getting Started

pnpm (Recommended)

Standalone CLI

npm / yarn / bun

1. 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.

Declare the skills your project needs

Create a skills.json file at the workspace root. You can create it manually or use the CLI to initialize:

# Interactive — prompt for installDir and linkTargets
npx skills-package-manager init

# Non-interactive — write the default manifest immediately
npx skills-package-manager init --yes

# 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 Initialization

If you're not using pnpm, you can manage skills using the standalone CLI. Initialize your project to create a skills.json manifest.

Bootstrap your project

# Run once with npx, no global install required
npx skills-package-manager init --yes

Add your first skill

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

Materialize & Link

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"
  }
}

Initialize and Add Skills

If you haven't already, initialize your manifest and start adding skills:

npx skills-package-manager init --yes
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. Started with pnpm-plugin-skills

#Install the pnpm plugin

#Declare the skills your project needs

#Run pnpm as usual

#Add .agents/skills etc to .gitignore

#2. Add more skills when needed

#3. Refresh remote skill versions

#1. Quick Initialization

#Bootstrap your project

#Add your first skill

#Materialize & Link

#2. Advanced Workflow

#Update to latest versions

#Link local developments

#Lifecycle Integration

#Install SPM as a dev dependency

#Configure the prepare script

#Initialize and Add Skills