| name | skill-snapshot |
| description | Use when creating, listing, diffing, saving, or restoring reversible snapshots of local Claude Code skills with a Git-backed workflow. |
Skill Snapshot
为 Claude Code 技能创建快照，支持版本回退。存储在 GitHub 私有仓库，按分类目录组织。
触发词
- "快照"、"snapshot"、"保存技能"、"备份技能"
- "回退技能"、"恢复技能"、"restore skill"
- "/skill-snapshot"
命令格式
/skill-snapshot <command> [args]
可用命令
| 命令 | 说明 | 示例 |
|---|
init | 初始化私有仓库 | /skill-snapshot init |
scan | 扫描技能，按分类显示备份状态 | /skill-snapshot scan |
save <skill> [message] | 保存快照到分类目录 | /skill-snapshot save my-skill "添加断点续写" |
restore <skill> [version] | 恢复版本 | /skill-snapshot restore my-skill v2 |
list [skill] | 列出快照（按分类分组） | /skill-snapshot list my-skill |
diff <skill> [version] | 对比差异 | /skill-snapshot diff my-skill v1 |
migrate | 迁移旧格式快照到分类目录 | /skill-snapshot migrate |
sync-configs | 同步所有 CLAUDE.md 配置 | /skill-snapshot sync-configs |
分类配置
技能分类定义在 categories.conf 文件中：
# 格式: skill-name=category
collaborating-with-codex=ai-collaboration
paper-mapping=writing
obsidian-bases=obsidian
coding-standards=development
planning-with-files=workflow
skill-authoring=meta
agent-browser=utilities
预定义分类
| 分类 | 说明 | 示例技能 |
|---|
ai-collaboration | AI 协作工具 | collaborating-with-codex, task-dispatcher |
writing | 写作与文档 | paper-mapping, pdf2md-academic |
obsidian | Obsidian 相关 | obsidian-bases, nb-query, notebooklm |
development | 开发模式 | coding-standards, tdd-workflow |
workflow | 工作流程 | planning-with-files, changelog |
meta | 元技能管理 | skill-authoring, skill-catalog |
utilities | 工具类 | agent-browser, web-fetch-fallback |
uncategorized | 未分类（默认） | 未在配置中定义的技能 |
版本标签格式
- 新格式:
<category>/<skill-name>/v<n>（如 writing/paper-mapping/v1）
- 旧格式:
<skill-name>/v<n>（如 paper-mapping/v1，兼容但建议迁移）
忽略规则
scan 命令根据以下规则自动判断哪些技能需要备份：
| 规则 | 跳过原因 |
|---|
archive/ 目录 | 归档目录 |
| 符号链接 | 外部安装的技能 |
skill-snapshot | 快照工具本身 |
包含 .git/ | 自带版本控制 |
包含 .venv/ 或 node_modules/ | 包含大量依赖 |
| 体积 > 10MB | 体积过大 |
缺少 SKILL.md | 可能不是有效技能 |
执行流程
scan - 扫描技能
扫描所有技能，按分类显示备份状态。
执行脚本：
bash ~/.claude/skills/skill-snapshot/scripts/scan.sh
输出示例：
【需要备份】
[ai-collaboration]
✓ collaborating-with-codex (7 files, 68K) [已有: ai-collaboration/collaborating-with-codex/v1]
✓ task-dispatcher (7 files, 48K) [已有: ai-collaboration/task-dispatcher/v1]
[writing]
✓ paper-mapping (1 files, 8K) [已有: writing/paper-mapping/v1]
○ new-skill (3 files, 12K) [未备份]
【跳过】
✗ skill-snapshot - 快照工具本身
✗ external-plugin - 符号链接（外部安装）
save - 保存快照
参数：
<skill>: 技能名称（必填）[message]: 快照说明（可选，默认为时间戳）
流程：
- 验证技能存在于
~/.claude/skills/<skill>/
- 从
categories.conf 获取分类
- 确定下一个版本号
- 复制技能目录到
~/.claude/skill-snapshots/<category>/<skill>/
- Git add, commit, tag, push
执行脚本：
bash ~/.claude/skills/skill-snapshot/scripts/save.sh "<skill>" "[message]"
restore - 恢复版本
参数：
<skill>: 技能名称（必填）[version]: 版本号（可选，默认列出可用版本）
流程：
- 拉取最新仓库
- 查找匹配的 tag（兼容新旧格式）
- Checkout 到指定 tag
- 复制到
~/.claude/skills/<skill>/
- 切回 main 分支
执行脚本：
bash ~/.claude/skills/skill-snapshot/scripts/restore.sh "<skill>" "[version]"
migrate - 迁移旧格式
将旧格式快照（skill/vN）迁移到新的分类目录格式（category/skill/vN）。
执行脚本：
bash ~/.claude/skills/skill-snapshot/scripts/migrate.sh
流程：
- 扫描所有旧格式 tags
- 根据
categories.conf 确定分类
- 为每个旧 tag 创建对应的新格式 tag
- 推送新 tags（保留旧 tags）
list - 列出快照
参数：
[skill]: 技能名称（可选，不填则按分类列出所有）
执行脚本：
bash ~/.claude/skills/skill-snapshot/scripts/list.sh "[skill]"
存储结构
~/.claude/skill-snapshots/ # 本地仓库
├── ai-collaboration/ # 分类目录
│ ├── collaborating-with-codex/
│ │ ├── SKILL.md
│ │ └── scripts/
│ └── task-dispatcher/
├── writing/
│ ├── paper-mapping/
│ └── pdf2md-academic/
├── obsidian/
│ ├── obsidian-bases/
│ └── nb-query/
├── development/
├── workflow/
├── meta/
├── utilities/
├── claude-configs/ # CLAUDE.md 配置备份
│ ├── global/
│ ├── obsidian/
│ ├── solidity/
│ ├── solana/
│ └── README.md
└── README.md
GitHub Tags (新格式):
├── ai-collaboration/collaborating-with-codex/v1
├── writing/paper-mapping/v1
├── obsidian/nb-query/v1
└── ...
使用示例
场景 1：首次使用
用户: 帮我初始化技能快照
Claude: [执行 init]
场景 2：修改前保存
用户: 我要改 paper-mapping，先保存一下
Claude: [执行 save paper-mapping "修改前备份"]
输出:
技能: paper-mapping
分类: writing
版本: v2
✓ 快照已保存: writing/paper-mapping/v2
场景 3：改坏了回退
用户: paper-mapping 改坏了，退回上一版
Claude: [执行 restore paper-mapping v1]
输出: 已恢复到 writing/paper-mapping/v1
场景 4：查看历史
用户: paper-mapping 有哪些版本？
Claude: [执行 list paper-mapping]
输出:
=== paper-mapping 快照历史 ===
分类: writing
v1 - 2025-01-05 - 初始版本 [新]
v2 - 2025-01-08 - 添加断点续写 [新]
场景 5：迁移旧格式
用户: 帮我把旧的快照迁移到分类目录
Claude: [执行 migrate]
输出:
发现 43 个技能需要迁移:
collaborating-with-codex → ai-collaboration/ (3 个版本)
paper-mapping → writing/ (1 个版本)
...
是否继续迁移? (y/N)
注意事项
- 分类配置: 新技能需要在
categories.conf 中添加分类，否则归入 uncategorized
- 向后兼容: restore/list 命令兼容新旧两种格式的 tags
- 迁移建议: 建议执行
migrate 将旧格式迁移到新格式
- 符号链接跳过: 外部安装的技能（符号链接）不支持快照
- 网络依赖: save/restore/migrate 需要网络连接推送到 GitHub
