spm

README

spm — Skills Package Manager

spm is a CLI tool for managing AI agent skills. It resolves and installs skill packages from GitHub or local directories into .agents/skills/<name>/, tracking dependencies via spm.json and spm.lock.json — similar to npm or go mod, but for agent skill files.

Installation

From source with go install (recommended)

Requires Go 1.26.2+.

go install github.com/cstavro/spm@latest

Installs the spm binary to $GOPATH/bin (default ~/go/bin). Make sure that directory is on your PATH.

To install a specific version:

go install github.com/cstavro/spm@v1.0.0

Pre-built binaries

Download a binary for your platform from the Releases page and place it somewhere on your PATH.

Build from source

git clone https://github.com/cstavro/spm
cd spm
make build
# Move the binary somewhere on your PATH
mv spm /usr/local/bin/spm

Usage

spm add <source> [name]

Add a skill and install it immediately.

spm add github:owner/repo/subdir@v1.0.0
spm add github:owner/repo/subdir my-skill   # explicit name
spm add ./local/path my-local-skill

• name defaults to the last path segment of source.
• Errors if the skill already exists — use spm update <name> instead.

spm install

Install all skills declared in spm.json.

spm install

• Skips re-download when the lock commit/hash matches and all files are present on disk.

spm update [name]

Update one or all skills, bypassing the lock.

spm update             # update all skills
spm update my-skill    # update a single skill

• Pinned versions are re-fetched at the same version. Omit the version in spm.json to track latest.

spm remove <name>

Remove a skill from spm.json, the lock, and disk.

spm remove my-skill
spm rm my-skill        # alias

spm list

List all installed skills.

spm list
spm ls    # alias

Outputs a table with NAME, SOURCE, VERSION, COMMIT, and FILES.

---

Source Formats

Scheme	Example
GitHub	github:owner/repo/subdir@v1.0.0
Local (relative)	./path/to/skill
Local (absolute)	/abs/path/to/skill
Local (home)	~/path/to/skill

Version is the last @-delimited segment with no /. Without a version, spm tries: latest release → latest tag → HEAD.

---

Config Files

spm.json — skill declarations (commit to version control):

{
  "skills": {
    "caveman": {
      "source": "github:JuliusBrussee/caveman/caveman",
      "version": "v1.6.0"
    }
  }
}

spm.lock.json — resolved state (commit to version control):

{
  "skills": {
    "caveman": {
      "source": "github:JuliusBrussee/caveman/caveman",
      "resolved_version": "v1.6.0",
      "commit": "c2ed24b3e5d412cd0c25197b2bc9af587621fd99",
      "files": ["SKILL.md"]
    }
  }
}

Skills are installed to .agents/skills/<name>/ relative to the directory containing spm.json.

---

GitHub Authentication

spm reads credentials in this order:

1. GITHUB_TOKEN environment variable
2. gh auth token (GitHub CLI)

Public repos work without a token but may hit API rate limits.

---

Dev Setup

Requirements: Go 1.26.2+.

make build   # build binary → ./spm
make test    # run tests (go test ./...)
make fmt     # auto-format with gofmt -w
make lint    # check formatting without modifying files
make vet     # static analysis (go vet ./...)
make all     # lint + vet + build

go run . <subcommand>   # run from source without building

Project Layout

main.go                   # entrypoint → cmd.Execute()
cmd/                      # Cobra subcommands: add, install, update, remove, list
internal/config/          # spm.json and spm.lock.json load/save
internal/resolver/        # GitHub and local resolvers
internal/installer/       # install/uninstall skill files to disk