skvlt snapshots the skills you already have installed into a small YAML manifest, then restores them later by source. It is designed for moving between machines, recovering a setup after reinstalling tools, or checking a team's shared skill baseline into a repo.

Important

This package has a Bun-only runtime. Install Bun first, then use skvlt through a global install, from source, or from a packed npm tarball.

Why Skills Vault?

Back up installed skills into a deterministic skvlt.yaml manifest.
Restore only missing skills, or reinstall everything from the manifest.
Preserve install scope so global and project-scoped backups round-trip cleanly.
Inspect local health with doctor before or after a restore.
Generate shell completion scripts for Bash, Zsh, and PowerShell.
Emit structured JSON for automation and scripting with --json.

Getting Started

Prerequisites

Bun >=1.3.11
Access to the upstream skills CLI through bunx skills

Install

npm install -g @xixu-me/skills-vault

Or with Bun:

bun add -g @xixu-me/skills-vault@latest

Then confirm the CLI is available:

skvlt --help
skvlt --version

Community

Read CONTRIBUTING.md before opening a pull request.
Review CODE_OF_CONDUCT.md for participation expectations.
Use SUPPORT.md to choose the right support channel.
Follow SECURITY.md for private vulnerability reporting.

Usage

1. Back up installed skills

Create a manifest for your currently installed skills:

skvlt backup

Preview the generated YAML without writing a file:

skvlt backup --dry-run

Back up project-scoped installs with an explicit lock file:

skvlt backup --project-scope --lock-file ./skills-lock.json --output ./skvlt.yaml

2. Restore from a manifest

Restore the missing skills recorded in ./skvlt.yaml:

skvlt restore

Preview the underlying bunx skills add ... commands:

skvlt restore --dry-run

Restore only one source:

skvlt restore --only-source anthropics/skills

Target specific agents and copy files instead of symlinking:

skvlt restore --agent codex --agent claude-code --copy

Force a full reinstall from every selected source:

skvlt restore --reinstall-all

Let the upstream source decide the installed skill set:

skvlt restore --all

3. Check local state

Run a quick health check for Bun, the skills CLI, your manifest, and global skill consistency:

skvlt doctor

4. Enable shell completions

skvlt completion bash
skvlt completion zsh
skvlt completion powershell

Manifest Format

By default, Skills Vault writes ./skvlt.yaml.

total_sources: 2
total_skills: 3
scope: "global"

sources:
  "anthropics/skills":
    count: 2
    skills:
      - "alpha"
      - "beta"

  "github/awesome-copilot":
    count: 1
    skills:
      - "gamma"

Each source is grouped with the exact skill names seen in the local lock file at backup time. During restore, the manifest scope is respected unless you explicitly override it with --project-scope.

Commands

`backup`

Capture installed skills into a manifest.

skvlt backup [options]

Useful options:

--output <path>: write the manifest somewhere other than ./skvlt.yaml
--lock-file <path>: choose which skills lock file to read
--project-scope: back up project-scoped installs instead of global installs
--dry-run: print the manifest to stdout

`restore`

Recreate a local setup from a manifest.

skvlt restore [options]

Useful options:

--manifest <path>: restore from a different manifest path
--only-source <source>: restore a single source, repeatable
--agent <agent>: pass through one or more agent targets
--copy: copy files instead of symlinking
--all: install all skills from each selected source
--reinstall-all: reinstall every skill listed in the manifest
--continue-on-error: keep processing later sources after a failure
--concurrency <count>: set preview concurrency for dry runs
--dry-run: print the generated install commands

Note

Live restores intentionally serialize installs in lock-safe mode because the upstream skills CLI mutates shared global state.

`doctor`

Inspect the current environment and skill state.

skvlt doctor [options]

Useful options:

--manifest <path>: check a non-default manifest path

`completion`

Print a completion script for your shell.

skvlt completion <bash|zsh|powershell>

JSON Output

Every top-level command accepts --json, which makes skvlt easier to integrate into scripts and CI:

skvlt --json --version
skvlt --json backup --dry-run
skvlt --json doctor

Development

Install dependencies:

bun install

Run the main workflows locally:

bun run format
bun run test
bun run check

Build a publishable tarball:

npm pack

Publish the package:

npm publish --access public

Notes

Global manifests read from ~/.agents/.skill-lock.json by default.
Global restores verify the relationship between ~/.agents/.skill-lock.json and ~/.agents/skills.
Project-scoped backup currently requires --lock-file so the source metadata stays explicit.

License

Under the MIT License. See LICENSE.