201 lines
5.4 KiB
Markdown
201 lines
5.4 KiB
Markdown
# Skills Vault
|
|
|
|
**_[汉语](./README.zh.md)_**
|
|
|
|
[](https://www.npmjs.com/package/skvlt)
|
|
[](https://www.npmjs.com/package/skvlt)
|
|
[](https://github.com/xixu-me/skills-vault/actions/workflows/ci.yml)
|
|
[](https://bun.sh/)
|
|
[](./LICENSE)
|
|
|
|
Skills Vault is a CLI for backing up and restoring [Agent Skills](https://agentskills.io).
|
|
|
|
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](https://bun.com).
|
|
|
|
## Why Skills Vault
|
|
|
|
Skills Vault exists to fill the gap described in [vercel-labs/skills#729](https://github.com/vercel-labs/skills/issues/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:
|
|
|
|
```bash
|
|
bunx skvlt backup
|
|
```
|
|
|
|
Preview what a restore would run:
|
|
|
|
```bash
|
|
bunx skvlt restore --dry-run
|
|
```
|
|
|
|
Restore everything recorded in the manifest:
|
|
|
|
```bash
|
|
bunx skvlt restore --all
|
|
```
|
|
|
|
If you want a curated, ready-to-use manifest, see [xixu-me/skvlt](https://github.com/xixu-me/skvlt), a maintained collection of `skvlt.yaml` snapshots.
|
|
|
|
The default manifest is `./skvlt.yaml`. A typical file looks like this:
|
|
|
|
```yaml
|
|
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`.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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](https://github.com/xixu-me/skvlt) and restore from the `skvlt.yaml` maintained there.
|
|
|
|
### `doctor`
|
|
|
|
Inspect the local Skills Vault environment and global skill state.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
bunx skvlt completion bash
|
|
bunx skvlt completion zsh
|
|
bunx skvlt completion powershell
|
|
```
|
|
|
|
## JSON Output
|
|
|
|
All top-level commands support `--json` for structured output:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
bun install --frozen-lockfile
|
|
```
|
|
|
|
Useful commands:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
npm pack --dry-run --json
|
|
```
|
|
|
|
The release workflow uses trusted publishing. The publish step is:
|
|
|
|
```bash
|
|
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`](./CONTRIBUTING.md), [`SUPPORT.md`](./SUPPORT.md), and [`SECURITY.md`](./SECURITY.md).
|
|
|
|
## License
|
|
|
|
Licensed under MIT. See [`LICENSE`](./LICENSE).
|