skills-vault/README.zh.md

Skills Vault

English

Skills Vault 是一个用于备份和恢复 Agent Skills 的 CLI。

它主要服务于这样一个常见流程：

1. 把当前机器上已安装的 skills 快照出来
2. 提交或移动这个 manifest
3. 在另一台机器上恢复同一组 skill source

Important

仅支持 Bun 运行时。Skills Vault 设计上就是通过 Bun 安装和运行的。

为什么需要 Skills Vault

Skills Vault 的存在，是为了补上 vercel-labs/skills#729 里提到的缺口：缺少一种声明式 manifest，来支持可移植、可复现的 skills 配置。

• 把已安装的 skills 备份为确定性的 skvlt.yaml
• 按 source、按 agent，或者一次性从 manifest 恢复
• 通过 --dry-run 在真正改动前先预览
• 用 doctor 快速检查本地环境
• 为 bash、zsh 和 powershell 生成补全脚本

快速开始

备份当前已安装的 skills：

bunx skvlt backup

预览一次 restore 将会执行什么：

bunx skvlt restore --dry-run

恢复 manifest 中记录的全部内容：

bunx skvlt restore --all

如果你想直接使用一个精选好的 manifest，可以查看 xixu-me/skvlt，这是一个持续维护的 skvlt.yaml 集合。

默认 manifest 路径是 ./skvlt.yaml。一个典型文件如下：

total_sources: 2
total_skills: 3
scope: "global"

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

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

命令

backup

把已安装的 skills 快照到 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 会先读取已安装的 skill 名称，再结合 lock file 元数据，最终按 source 分组写出 manifest。

Note

全局备份默认读取 ~/.agents/.skill-lock.json。项目级备份目前仍然需要显式传入 --lock-file。

restore

从 manifest 安装 skills。

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

默认情况下，restore 会遵循 manifest 中记录的 scope。如果希望即使 manifest 来自全局状态，也强制恢复到项目作用域，可以使用 --project-scope。

--dry-run 会打印推导出的 bunx skills add ... 命令，但不会真正执行。实际安装时会采用 lock-safe 模式串行执行，以避免全局 lock file 竞争。

如果你想从一个精选 manifest 起步，也可以直接使用 xixu-me/skvlt 中维护的 skvlt.yaml。

doctor

检查本地 Skills Vault 环境和全局 skill 状态。

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

doctor 会检查：

• Bun 运行时
• bunx skills --help
• manifest 是否存在
• 全局 lock file 和 skills 目录是否存在
• lock file 中追踪的技能与实际安装状态是否一致

completion

输出 shell 补全脚本。

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

JSON 输出

所有顶层命令都支持 --json 结构化输出：

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

成功时会返回 ok、command 和 data。失败时会返回 ok、command，以及稳定的 error.code 和错误消息。

本地开发

安装依赖：

bun install --frozen-lockfile

常用命令：

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 是主要的发布前校验入口。它会运行格式检查、完整的 Bun 测试，以及 npm pack --dry-run --json。

如果你修改了 workflow 文件，也请额外运行：

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

打包与发布说明

npm 包会把 src/cli.ts 作为 skvlt 可执行入口，并且有意只将 src 目录作为运行时载荷发布。

发布前，可以先在本地检查 tarball 内容：

npm pack --dry-run --json

Release workflow 使用 trusted publishing。实际发布步骤为：

npm publish --access public

故障排查

• 如果 restore 报告全局状态不一致，请检查 ~/.agents/.skill-lock.json 和 ~/.agents/skills
• 如果环境检查失败，先运行 bunx skvlt doctor
• 如果打包检查失败，运行 bun run check，并检查 npm pack --dry-run --json 的输出

关于贡献、支持和安全策略，请参阅 CONTRIBUTING.md、SUPPORT.md 和 SECURITY.md。

许可证

基于 MIT 许可证发布。详见 LICENSE。