#Getting Started

#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 a specific skill by name
npx skills-package-manager add vercel-labs/skills --skill find-skills
npx skills-package-manager add vercel-labs/skills@find-skills

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

Example skills.json:

{
  "installDir": ".agents/skills",
  "linkTargets": [".claude/skills"],
  "selfSkill": false,
  "skills": {
    "find-skills": "https://github.com/vercel-labs/skills.git#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, skills-lock.yaml, and npx skills-package-manager commands. This helper skill is not written to skills-lock.yaml. 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:

1. Read skills.json
2. Resolve each skill source
3. Generate or update skills-lock.yaml
4. Materialize skills into installDir
5. 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:

.agents/skills
.claude/skills

#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

#Materialize & Link

npx skills-package-manager install

This command will:

1. Resolve dependencies and generate skills-lock.yaml.
2. Download/Copy files to .agents/skills.
3. Symlink them to your agent folders (e.g., .claude/skills).

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