skills-vault/README.zh.md

Skills Vault

English

用于备份和恢复 Agent Skills 的 CLI。

skvlt 会将你已经安装的 skills 快照为一个小型 YAML 清单，然后在之后按来源恢复它们。它适合在多台机器之间迁移、在重装工具后恢复环境，或者将团队共享的 skill 基线纳入存储库管理。

Important

这个包只支持 Bun 运行时。请先安装 Bun，然后通过全局安装、源码，或打包后的 npm tarball 使用 skvlt。

为什么使用 Skills Vault？

• 将已安装的 skills 备份为可确定复现的 skvlt.yaml 清单。
• 只恢复缺失的 skills，或者按清单完整重装。
• 保留安装作用域，让全局安装和项目级安装都能准确往返恢复。
• 在恢复前后通过 doctor 检查本地环境状态。
• 为 Bash、Zsh 和 PowerShell 生成 shell 补全脚本。
• 通过 --json 输出结构化 JSON，便于自动化和脚本集成。

快速开始

前置条件

• bun >=1.3.11
• 可通过 bunx skills 访问上游 skills CLI

安装

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

然后确认 CLI 已可用：

skvlt --help
skvlt --version

社区

• 在发起 Pull Request 之前先阅读 CONTRIBUTING.md。
• 参与前请查看 CODE_OF_CONDUCT.md。
• 需要支持时请参考 SUPPORT.md 选择合适渠道。
• 私下报告安全漏洞请遵循 SECURITY.md。

用法

1. 备份已安装的 skills

为当前已安装的 skills 创建清单：

skvlt backup

预览生成的 YAML，而不写入文件：

skvlt backup --dry-run

使用显式锁文件备份项目级安装：

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

2. 从清单恢复

恢复 ./skvlt.yaml 中记录但当前缺失的 skills：

skvlt restore

预览底层将执行的 bunx skills add ... 命令：

skvlt restore --dry-run

只恢复单个来源：

skvlt restore --only-source anthropics/skills

指定 agent，并使用复制而不是符号链接：

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

从所有选定来源强制完整重装：

skvlt restore --reinstall-all

让上游来源自行决定要安装哪些 skills：

skvlt restore --all

3. 检查本地状态

快速检查 Bun、skills CLI、清单文件，以及全局 skills 一致性：

skvlt doctor

4. 启用 shell 补全

skvlt completion bash
skvlt completion zsh
skvlt completion powershell

清单格式

默认情况下，Skills Vault 会写入 ./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"

每个来源都会按备份时本地锁文件中看到的精确 skill 名称分组。恢复时会遵循清单中的作用域，除非你显式用 --project-scope 覆盖。

命令

backup

将已安装的 skills 记录到清单中。

skvlt backup [options]

常用选项：

• --output <path>：将清单写到 ./skvlt.yaml 以外的位置
• --lock-file <path>：指定要读取的 skills 锁文件
• --project-scope：备份项目级安装，而不是全局安装
• --dry-run：将清单输出到 stdout

restore

根据清单重建本地环境。

skvlt restore [options]

常用选项：

• --manifest <path>：从其他路径的清单恢复
• --only-source <source>：只恢复单个来源，可重复传入
• --agent <agent>：透传一个或多个 agent 目标
• --copy：复制文件而不是创建符号链接
• --all：从每个选定来源安装全部 skills
• --reinstall-all：重装清单中列出的所有 skills
• --continue-on-error：某个来源失败后继续处理后续来源
• --concurrency <count>：设置 dry run 预览的并发数
• --dry-run：输出生成的安装命令

Note

实际恢复会故意以串行方式执行安装，以保证锁文件安全，因为上游 skills CLI 会修改共享的全局状态。

doctor

检查当前环境与 skill 状态。

skvlt doctor [options]

常用选项：

• --manifest <path>：检查非默认路径的清单

completion

输出当前 shell 的补全脚本。

skvlt completion <bash|zsh|powershell>

JSON 输出

每个顶层命令都支持 --json，方便将 skvlt 集成进脚本或 CI：

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

开发

安装依赖：

bun install

在本地运行主要工作流：

bun run format
bun run test
bun run check

构建可发布的 tarball：

npm pack

发布包：

npm publish --access public

说明

• 全局清单默认读取 ~/.agents/.skill-lock.json。
• 全局恢复会校验 ~/.agents/.skill-lock.json 与 ~/.agents/skills 之间的关系。
• 项目级备份目前需要显式传入 --lock-file，以保持来源元数据明确。

许可证

基于 MIT License 发布。详见 LICENSE。