skills-package-manager

A package manager for agent skills
Manage, install, and link SKILL.md-based skills into your AI coding agents

Quick Start • Features • How It Works • Specifier Format • Documentation

---

✨ Features

• 🚀 Zero-config setup — Get started with a single command
• 🔗 Git-based versioning — Lock to specific commits, tags, or branches
• 📦 pnpm integration — Auto-install skills during pnpm install
• 🎯 Multiple sources — GitHub repos, local files, or npm packages
• 🔒 Reproducible installs — Lockfile ensures consistent environments
• ⚡ Parallel resolution — Fast dependency resolution
• 🧩 AI agent ready — Seamless integration with Claude and other agents

🚀 Quick Start

Initialize a project

# Create a new skills.json manifest
npx skills-package-manager init

# Or skip the prompts
npx skills-package-manager init --yes

Add skills

# 🔍 Interactive — browse and select from a repo
npx skills-package-manager add vercel-labs/skills

# 🎯 Direct — specify skill by name
npx skills-package-manager add vercel-labs/skills --skill find-skills

# 🔗 Full GitHub URL
npx skills-package-manager add https://github.com/rstackjs/agent-skills --skill rspress-custom-theme

# 📁 Local skill
npx skills-package-manager add file:./my-skills#path:/skills/my-skill

Install all skills

npx skills-package-manager install

💡 Tip: Use --frozen-lockfile in CI/CD to ensure reproducible installs without modifying the lockfile.

Update skills

# Update all skills
npx skills-package-manager update

# Update specific skills only
npx skills-package-manager update find-skills rspress-custom-theme

📋 Usage Scenarios

Scenario	Command	Why
🏠 First time setup	npx skills-package-manager install	Creates lockfile if missing
🔄 After git pull	npx skills-package-manager install	Updates skills if manifest changed
🏭 CI/CD pipeline	npx skills-package-manager install --frozen-lockfile	Ensures exact versions, fails on misconfig
⬆️ Version updates	npx skills-package-manager update	Updates lockfile with latest versions

🏗️ How It Works

skills-package-manager uses two files to manage your skills:

skills.json — Manifest

Declares which skills to install and where to put them:

{
  "installDir": ".agents/skills",
  "linkTargets": [".claude/skills"],
  "skills": {
    // GitHub skill with path
    "find-skills": "https://github.com/vercel-labs/skills.git#path:/skills/find-skills",
    // Local skill
    "my-local-skill": "file:./local-source#path:/skills/my-local-skill",
    // Short form — uses repo root
    "create-ex": "https://github.com/therealXiaomanChu/ex-skill.git"
  }
}

skills-lock.yaml — Lockfile

Locks resolved versions for reproducible installs:

lockfileVersion: "0.1"
installDir: .agents/skills
linkTargets:
  - .claude/skills
skills:
  find-skills:
    specifier: https://github.com/vercel-labs/skills.git#path:/skills/find-skills
    resolution:
      type: git
      url: https://github.com/vercel-labs/skills.git
      commit: abc1234...
      path: /skills/find-skills
    digest: sha256-...

📝 Specifier Format

Type	Format	Example
GitHub shorthand	owner/repo	vercel-labs/skills
GitHub URL	https://github.com/owner/repo	https://github.com/vercel-labs/skills
Git + path	url.git#path:/skills/name	https://github.com/owner/repo.git#path:/skills/my-skill
Git + ref + path	url.git#ref&path:/skills/name	https://github.com/owner/repo.git#main&path:/skills/my-skill
Local file	file:./path#path:/skills/name	file:./local-source#path:/skills/my-skill

🔌 pnpm Integration

Install pnpm-plugin-skills as a config dependency for auto-install on every pnpm install:

pnpm add pnpm-plugin-skills --config

This automatically adds it to configDependencies in pnpm-workspace.yaml.

📚 Documentation

• 📖 Getting Started Guide
• 📘 API Reference
• 🏗️ Architecture

🛠️ Development

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run the test suite
pnpm test

# Start docs dev server
pnpm --filter website dev

Project Structure

skills-package-manager/
├── packages/
│   ├── skills-package-manager/  # Core library and spm CLI
│   └── pnpm-plugin-skills/      # pnpm plugin (auto-install on pnpm install)
├── website/                     # Documentation site (Rspress)
├── skills.json                  # Example manifest
├── skills-lock.yaml             # Example lockfile
└── pnpm-workspace.yaml

🧰 Tech Stack

Technology	Purpose
	Strict type checking
	Modern build tool (bundle mode)
	Fast test runner
	Package manager with workspace support
	Documentation site generator

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

ISC © skills.sh

---

⬆ Back to Top

Made with ❤️ for AI coding agents