#CLI commands

The spm CLI covers the four main actions of skill management: add, init, install, and update.

#spm add

Add a skill to your project.

# Interactive discovery and selection
spm add owner/repo
spm add https://github.com/owner/repo

# Non-interactively add a specific skill
spm add owner/repo --skill find-skills

# Use a full specifier directly
spm add https://github.com/owner/repo.git#path:/skills/my-skill
spm add file:./local-source#path:/skills/my-skill

Behavior overview:

1. Perform a shallow clone of the GitHub repository
2. Scan SKILL.md files and discover candidate skills
3. Select interactively or target a specific skill with --skill
4. Write to skills.json
5. Immediately install and link the new skill

#spm init

Initialize skills.json in the current project.

# Interactive
spm init

# Non-interactive defaults
spm init --yes

Init behavior:

• spm init prompts for installDir and additional linkTargets
• spm init --yes writes default values directly
• Fails if skills.json already exists
• Does not create skills-lock.yaml

#spm install

Install all skills declared in skills.json.

spm install

Useful for:

• Initializing a new environment
• Restoring skill dependencies in CI
• Re-syncing the local skill directory after changing the manifest

#Install Process

When you run spm install, the following happens:

1. Read manifest — Load skills.json to get the list of skills to install
2. Read lockfile — Load skills-lock.yaml if it exists
3. Sync lockfile — Resolve each skill in the manifest to produce the lockfile entries for this install
   • This step may involve git/network requests, even when a corresponding entry already exists in skills-lock.yaml
4. Prune — Remove skills that are no longer in the manifest
5. Fetch — Download/copy skills to installDir
6. Link — Create symlinks in linkTargets
7. Write lockfile — Save updated skills-lock.yaml

#--frozen-lockfile

Prevent lockfile modifications and fail if it's out of sync.

spm install --frozen-lockfile

When to use:

• CI/build environments where you want reproducible installs
• When you want to ensure the lockfile is not accidentally modified
• When you want faster installs (no git network requests to resolve refs)

Behavior differences from normal install:

Error scenarios:

#Troubleshooting

Install fails with "Lockfile is out of sync"

This means the specifiers in skills.json don't match what's in skills-lock.yaml. Common causes:

1. You edited skills.json manually without updating the lockfile
2. Someone else committed a new lockfile and your manifest is outdated

Solutions:

• Run spm install without --frozen-lockfile to update the lockfile
• Or revert your manifest changes to match the lockfile

#spm update

Refresh already-declared git-based skills.

spm update
spm update find-skills rspress-custom-theme

Update behavior:

• Uses skills.json as the source of truth
• Re-resolves git refs to the latest commit
• Skips local file: skills
• Fails immediately on unknown skill names
• Writes back skills-lock.yaml only after fetch and link both succeed

#When to use which