Skip to main content
Agent skill

Ws Ckpt

工作区快照管理。用户说"保存一下"、"存个快照"时创建 checkpoint,仅限 Linux; 说"回滚"、"撤销"、"恢复到之前"时 rollback;说"删掉快照"时 delete; 说"对比快照"、"快照改了什么"时 diff; 说"看看快照"、"有哪些快照"时 list;说"查看快照状态"、"查看快照剩余空间"时 status。

Get started

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Ws Ckpt when an AI agent needs a reusable SKILL.md workflow for this job: 工作区快照管理。用户说"保存一下"、"存个快照"时创建 checkpoint,仅限 Linux; 说"回滚"、"撤销"、"恢复到之前"时 rollback;说"删掉快照"时 delete; 说"对比快照"、"快照改了什么"时 diff; 说"看看快照"、"有哪些快照"时 list;说"查看快照状态"、"查看快照剩余空间"时 status。

When not to use it

Skip Ws Ckpt when the task is outside the analysis category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/ws-ckpt
# Save SKILL.md to ~/.claude/skills/ws-ckpt/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/ws-ckpt/SKILL.md. For a shared project, commit the folder at .claude/skills/ws-ckpt/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Ws Ckpt skill for this task: Use Ws Ckpt when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

70/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
77/100
Practical detail
68/100
Source evidence
63/100
Source signals
70/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# ws-ckpt 工作区快照管理

基于 btrfs COW 快照,为任意工作区提供 checkpoint/rollback;实际耗时取决于文件系统、工作负载和机器环境。

## 工作区路径(关键 — 必须遵守)

⚠️ **绝对禁止猜测或推断工作区路径。**

工作区级操作(checkpoint、rollback、diff、cleanup,以及按工作区执行的 delete/list/status)需要 `-w <workspace>`。执行这些操作前,必须按以下顺序确定路径:

1. 用户在**当前消息中明确给出**了路径 → 直接使用 2. 否则 → **必须向用户询问**:"请提供工作区路径(传给 `-w` 的目录)",拿到回复后再执行

不得从环境变量、默认路径、或任何隐含上下文中猜测。确定后,本次会话内复用同一个路径。

以下全局查询/操作允许省略 `-w`,不要为此追问路径:

- `list`:列出所有已注册工作区的快照; - `status`:查看 daemon 全局状态; - 快照 ID 全局唯一时的 `delete`。若 ID 有歧义,再要求用户提供 `-w`。

cwd 占用的拦截由 daemon 层统一处理,skill 不再做前置守卫。

## 触发规则

| 用户说 | 执行命令 | 说明 | |--------|----------|------| | "保存一下"、"存个快照"、"checkpoint"、"备份当前状态" | `checkpoint` | 创建快照 | | "回滚"、"撤销"、"恢复到之前"、"rollback"、"改坏了" | `rollback` | 回滚到指定快照 | | "对比快照"、"快照差异"、"diff"、"改了什么" | `diff` | 查看两个快照间的文件变更 | | "删掉快照"、"清理快照"、"delete snapshot" | `delete` | 删除指定快照 | | "看看快照"、"有哪些快照"、"list"、"列一下" | `list` | 列出快照 | | "状态"、"空间"、"status"、"工作区怎么样" | `status` | 查看工作区状态 |

## 命令用法

### checkpoint — 创建快照

```bash ws-ckpt checkpoint -w <workspace> [-s <snapshot-id>] [-m <message>] [--metadata <json>] ```

- `-w`:工作区路径(必填) - `-s`:快照 ID(可选,省略时自动生成) - `-m`:快照描述(可选) - `--metadata`:附加 JSON 元数据(可选)

```bash ws-ckpt checkpoint -w <path-to-workspace> -s before-refactor -m "重构前备份" ws-ckpt checkpoint -w <path-to-workspace> # ID 自动生成 ```

### rollback — 回滚到快照

```bash ws-ckpt rollback -w <workspace> [-s <snapshot> | -n <steps>] [--preview] ```

- `-w`:工作区路径(必填) - `-s`:目标快照 ID(与 `-n` 互斥) - `-n`:沿父链回滚 N 步(与 `-s` 互斥) - `--preview`:预览文件变更,不实际执行回滚

```bash ws-ckpt rollback -w <path-to-workspace> -s before-refactor ws-ckpt rollback -w <path-to-workspace> -n 1 # 回滚到上一个快照 ws-ckpt rollback -w <path-to-workspace> -s snap1 --preview # 仅预览 ```

### diff — 查看快照间差异

```bash ws-ckpt diff -w <workspace> -f <from-snapshot> [-t <to-snapshot>] ```

- `-w`:工作区路径(必填) - `-f`:源快照 ID(必填) - `-t`:目标快照 ID(可选,省略时与当前工作区状态比较)

```bash # 两个快照之间的差异 ws-ckpt diff -w <path-to-workspace> -f before-refactor -t after-refactor

# 快照与当前工作区的差异 ws-ckpt diff -w <path-to-workspace> -f before-refactor ```

### delete — 删除快照

```bash ws-ckpt delete -s <snapshot> --force [-w <workspace>] ```

- `-s`:要删除的快照 ID(必填) - `--force`:跳过确认,agent执行必须要求跳过确认 - `-w`:快照 ID 跨工作区重复时必须指定

```bash ws-ckpt delete -s old-snap --force ```

### list — 列出快照

```bash ws-ckpt list [-w <workspace>] [--format table|json] [--limit N] [--cursor TOKEN] ```

- 省略 `-w` 列出所有工作区的快照

```bash ws-ckpt list ws-ckpt list -w <path-to-workspace> ws-ckpt list --format json ```

默认命令会自动读取全部游标页,JSON 仍输出单个数组。仅当用户明确要求分页时使用 `--limit N`;响应中的 `next_cursor` 可通过 `--cursor '<token>'` 继续读取。游标是不透明 且绑定查询范围的,不要解析或修改。若记录包含 `detail: "summary"` / `omitted_fields`, 必须明确告知用户该记录因超大 `message`/`metadata` 只返回摘要,但快照 ID 仍可用于 rollback、diff、delete 等操作。摘要保留的 `created_at`、`pinned`、`missing` 仍在 `meta` 下;被省略字段缺席,不应当作原本为空。

### status — 查看状态

```bash ws-ckpt status [-w <workspace>] ```

- 省略 `-w` 查看全局状态

```bash ws-ckpt status ws-ckpt status -w <path-to-workspace> ```

### config — 查看或修改自动清理策略

`ws-ckpt config` 的作用域由 scope 决定:不带 scope = 只读 overview(全局配置 + workspace 覆盖统计,带任何修改 flag 会报错);`-g` 全局;`-w <workspace>` 局部。

```bash # 全局(daemon-wide) ws-ckpt config -g # 查看 ws-ckpt config -g --enable-auto-cleanup ws-ckpt config -g --auto-cleanup-keep 30d # 或整数 20

# 局部(只覆盖本 workspace 的 auto_cleanup / auto_cleanup_keep) ws-ckpt config -w <path-to-workspace> # 三栏视图: effective / local / global ws-ckpt config -w <path-to-workspace> --auto-cleanup-keep 5 ws-ckpt config -w <path-to-workspace> --disable-auto-cleanup ws-ckpt config -w <path-to-workspace> --reset # 删除 policy.toml,沿用全局 ```

`-w` 仅可覆盖 `auto_cleanup` 和 `auto_cleanup_keep`,interval/image/health-check 等是 daemon-wide,带 `-w` 设置会被 CLI 拒绝。

## 注意事项

- checkpoint 用 `-s` 指定快照 ID(可省略,自动生成);rollback 和 delete 也用 `-s` 指定快照 ID - daemon 必须运行中(`systemctl status ws-ckpt` 确认),否则所有命令报连接错误 - 执行破坏性操作前务必先 checkpoint

Intended uses

  • Use Ws Ckpt when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.