# Skills Vault

**_[English](./README.md)_**

[![npm version](https://img.shields.io/npm/v/skvlt)](https://www.npmjs.com/package/skvlt)
[![npm downloads](https://img.shields.io/npm/dm/skvlt?label=downloads)](https://www.npmjs.com/package/skvlt)
[![CI](https://img.shields.io/github/actions/workflow/status/xixu-me/skills-vault/ci.yml?branch=main&label=ci)](https://github.com/xixu-me/skills-vault/actions/workflows/ci.yml)
[![Bun](https://img.shields.io/badge/Bun-%3E%3D1.3.11-f9f1e1)](https://bun.sh/)
[![License](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)

Skills Vault 是一个用于备份和恢复 [Agent Skills](https://agentskills.io) 的 CLI。

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

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

> [!IMPORTANT]
> 仅支持 Bun 运行时。Skills Vault 设计上就是通过 [Bun](https://bun.com) 安装和运行的。

## 为什么需要 Skills Vault

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

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

## 快速开始

备份当前已安装的 skills：

```bash
bunx skvlt backup
```

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

```bash
bunx skvlt restore --dry-run
```

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

```bash
bunx skvlt restore --all
```

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

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

```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`。

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

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

### `restore`

从 manifest 安装 skills。

```bash
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](https://github.com/xixu-me/skvlt) 中维护的 `skvlt.yaml`。

### `doctor`

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

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

`doctor` 会检查：

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

### `completion`

输出 shell 补全脚本。

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

## JSON 输出

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

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

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

## 本地开发

安装依赖：

```bash
bun install --frozen-lockfile
```

常用命令：

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

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

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

## 打包与发布说明

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

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

```bash
npm pack --dry-run --json
```

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

```bash
npm publish --access public
```

## 故障排查

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

关于贡献、支持和安全策略，请参阅 [`CONTRIBUTING.md`](./CONTRIBUTING.md)、[`SUPPORT.md`](./SUPPORT.md) 和 [`SECURITY.md`](./SECURITY.md)。

## 许可证

基于 MIT 许可证发布。详见 [`LICENSE`](./LICENSE)。