#Commands

#npx skills-package-manager add

Add one or more skills, then install and link them immediately after writing the manifest.

For the npx workflow, this is also the main migration pitch: teams already familiar with npx skills add ... can usually start by replacing it with npx skills-package-manager add ... and keep the same high-level add habit.

#Options

#Examples

# Add one skill from a multi-skill source
npx skills-package-manager add https://github.com/rstackjs/agent-skills --skill rspress-custom-theme

# Add all discovered skills and link them into multiple local agent directories
npx skills-package-manager add ../local-skills --agent claude-code --agent continue -y

# Add to the global workspace using an agent-specific global directory
npx skills-package-manager add ../local-skills -g --agent claude-code --skill hello-skill -y

#npx skills-package-manager init

Initialize a new skills.json manifest.

• npx skills-package-manager init: interactive initialization for installDir and additional linkTargets
• npx skills-package-manager init --yes: non-interactive initialization with defaults
• selfSkill defaults to false in the generated manifest
• Fails if skills.json already exists

#npx skills-package-manager install

Install all skills defined in skills.json, synchronize skills-lock.yaml, installDir, and linkTargets, and also install the bundled skills-package-manager-cli self skill when selfSkill is enabled. The helper skill is not written to skills-lock.yaml.

If patchedSkills contains an entry for a managed skill, the referenced patch file is applied after the base skill content is materialized. local: skills cannot be patched because their source directories are user-owned.

#Options

#Specifier Compatibility

When using --frozen-lockfile, the manifest and lockfile specifiers are compared semantically:

Manifest specifiers without a ref (commit/branch) are compatible with any lockfile ref. This allows teams to omit specific commits in skills.json while still using --frozen-lockfile in CI.

#Examples

#First-time install

When setting up a project for the first time (no lockfile exists):

npx skills-package-manager install

This will:

• Resolve all git refs to specific commits
• Create skills-lock.yaml with pinned versions
• Install skills to installDir
• Create symlinks in linkTargets

#CI install with frozen lockfile

In CI/CD pipelines, use --frozen-lockfile for reproducible builds:

npx skills-package-manager install --frozen-lockfile

This ensures:

• The exact versions in skills-lock.yaml are installed
• No network requests to resolve git refs (faster)
• CI fails if lockfile is out of sync (catching misconfigurations)

#After adding a new skill

After running npx skills-package-manager add or manually editing skills.json:

npx skills-package-manager install

This will:

• Resolve the new skill's git ref
• Update skills-lock.yaml with the new entry
• Install and link the new skill

#Troubleshooting out-of-sync errors

If you get "Lockfile is out of sync" with --frozen-lockfile:

# Option 1: Update the lockfile (recommended for local dev)
npx skills-package-manager install

# Option 2: Check what changed
git diff skills.json skills-lock.yaml

#npx skills-package-manager update

Refresh the resolvable skills declared in the manifest to their latest locked versions, with the option to update only selected skills.

#npx skills-package-manager patch

Prepare a skill for patching.

#Options

#Workflow

1. Resolve the currently locked content for the target skill.
2. Extract an editable copy.
3. Reapply the committed patch by default so you continue from the current patched state.
4. Write patch edit metadata for patch-commit.

#npx skills-package-manager patch-commit

Generate a patch file from an edited patch directory and commit it into the project.

#Options

#Workflow

1. Read the patch edit metadata from the directory created by patch.
2. Diff the edited copy against the original resolved skill content.
3. Write a patch file such as patches/hello-skill.patch.
4. Record the patch under patchedSkills in skills.json.
5. Update skills-lock.yaml with patch path and digest metadata.
6. Reinstall and relink the patched skill immediately.