Skills Vault

_[汉语](./README.zh.md)_

Skills Vault is a CLI for backing up and restoring Agent Skills.

It is built for the common round-trip:

1. snapshot what is installed today
2. commit or move the manifest
3. restore the same set of skill sources on another machine

[!IMPORTANT] Bun-only runtime. Skills Vault is designed to be installed and run with Bun.

Why Skills Vault

Skills Vault exists to fill the gap described in vercel-labs/skills#729: a declarative manifest for portable, reproducible skill setups across machines and teams.

• Back up installed skills into a deterministic skvlt.yaml file.
• Restore from that manifest by source, by agent, or all at once.
• Preview installs before making changes with --dry-run.
• Check local setup quickly with doctor.
• Generate completion scripts for bash, zsh, and powershell.

Quick Start

Back up your current skills:

bunx skvlt backup

Preview what a restore would run:

bunx skvlt restore --dry-run

Restore everything recorded in the manifest:

bunx skvlt restore --all

If you want a curated, ready-to-use manifest, see xixu-me/skvlt, a maintained collection of skvlt.yaml snapshots.

The default manifest is ./skvlt.yaml. A typical file looks like this:

total_sources: 2
total_skills: 3
scope: "global"

sources:
  "alpha/source":
    count: 1
    skills:
      - "beta"

  "beta/source":
    count: 2
    skills:
      - "alpha"
      - "zulu"

Commands

backup

Snapshot installed skills into skvlt.yaml.

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

backup reads installed skill names, joins them with lock-file metadata, and writes a grouped manifest keyed by source.

[!NOTE] Global backup reads from ~/.agents/.skill-lock.json by default. Project-scope backup currently requires --lock-file.

restore

Install skills from a manifest.

bunx skvlt restore --all
bunx skvlt restore --only-source xixu-me/skills
bunx skvlt restore --project-scope
bunx skvlt restore --dry-run

By default, restore respects the scope recorded in the manifest. Use --project-scope to force a project install even when the manifest was created from global state.

--dry-run prints the derived bunx skills add ... commands without running them. Live installs run in lock-safe mode and are serialized to avoid global lock-file races.

For a curated manifest source, you can start from xixu-me/skvlt and restore from the skvlt.yaml maintained there.

doctor

Inspect the local Skills Vault environment and global skill state.

bunx skvlt doctor
bunx skvlt doctor --manifest ./skvlt.yaml

doctor checks:

• the Bun runtime
• bunx skills --help
• whether the manifest exists
• whether the global lock file and skills directory are present
• whether tracked and installed global skills still match

completion

Print shell completion scripts.

bunx skvlt completion bash
bunx skvlt completion zsh
bunx skvlt completion powershell

JSON Output

All top-level commands support --json for structured output:

bunx skvlt --json doctor
bunx skvlt --json backup --dry-run

Successful responses include ok, command, and data. Failures include ok, command, and a stable error.code plus message.

Local Development

Install dependencies:

bun install --frozen-lockfile

Useful commands:

bun run ./src/cli.ts --help
bun run ./src/cli.ts doctor
bun run backup
bun run restore
bun run test
bun run check

bun run check is the main verification gate. It runs formatting checks, the Bun test suite, and npm pack --dry-run --json.

If you change workflow files, also run:

bunx prettier --check ".github/**/*.yml"

Package And Release Notes

The npm package publishes the skvlt bin from src/cli.ts and intentionally ships the src directory as its runtime payload.

Before publishing, verify the tarball contents locally:

npm pack --dry-run --json

The release workflow uses trusted publishing. The publish step is:

npm publish --access public

Troubleshooting

• If restore reports a global state mismatch, inspect ~/.agents/.skill-lock.json and ~/.agents/skills.
• If environment checks fail, start with bunx skvlt doctor.
• If packaging checks fail, run bun run check and review the tarball output from npm pack --dry-run --json.

For contribution, support, and security policy details, see CONTRIBUTING.md, SUPPORT.md, and SECURITY.md.

License

Licensed under MIT. See LICENSE.