Skill Snapshot

为 Claude Code 技能创建快照，支持版本回退。存储在 GitHub 私有仓库，按分类目录组织。

触发词

•"快照"、"snapshot"、"保存技能"、"备份技能"
•"回退技能"、"恢复技能"、"restore skill"
•"/skill-snapshot"

命令格式

code

/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 文件中：

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

bash ~/.claude/skills/skill-snapshot/scripts/scan.sh

输出示例：

code

【需要备份】

  [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

bash ~/.claude/skills/skill-snapshot/scripts/save.sh "<skill>" "[message]"

restore - 恢复版本

参数：

•<skill>: 技能名称（必填）
•[version]: 版本号（可选，默认列出可用版本）

流程：

•拉取最新仓库
•查找匹配的 tag（兼容新旧格式）
•Checkout 到指定 tag
•复制到 ~/.claude/skills/<skill>/
•切回 main 分支

执行脚本：

bash

bash ~/.claude/skills/skill-snapshot/scripts/restore.sh "<skill>" "[version]"

migrate - 迁移旧格式

将旧格式快照（skill/vN）迁移到新的分类目录格式（category/skill/vN）。

执行脚本：

bash

bash ~/.claude/skills/skill-snapshot/scripts/migrate.sh

流程：

•扫描所有旧格式 tags
•根据 categories.conf 确定分类
•为每个旧 tag 创建对应的新格式 tag
•推送新 tags（保留旧 tags）

list - 列出快照

参数：

•[skill]: 技能名称（可选，不填则按分类列出所有）

执行脚本：

bash

bash ~/.claude/skills/skill-snapshot/scripts/list.sh "[skill]"

存储结构

code

~/.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：首次使用

code

用户: 帮我初始化技能快照
Claude: [执行 init]

场景 2：修改前保存

code

用户: 我要改 paper-mapping，先保存一下
Claude: [执行 save paper-mapping "修改前备份"]
输出:
  技能: paper-mapping
  分类: writing
  版本: v2
  ✓ 快照已保存: writing/paper-mapping/v2

场景 3：改坏了回退

code

用户: paper-mapping 改坏了，退回上一版
Claude: [执行 restore paper-mapping v1]
输出: 已恢复到 writing/paper-mapping/v1

场景 4：查看历史

code

用户: paper-mapping 有哪些版本？
Claude: [执行 list paper-mapping]
输出:
  === paper-mapping 快照历史 ===
  分类: writing

  v1 - 2025-01-05 - 初始版本 [新]
  v2 - 2025-01-08 - 添加断点续写 [新]

场景 5：迁移旧格式

code

用户: 帮我把旧的快照迁移到分类目录
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