技能目录整理与去重
何时使用
- 用户抱怨技能太多、太乱、有重复
- 出现大量
skill_2053xxxxxxxx/xxx__skillhub这类无意义目录名 - 想盘点装了哪些技能、各自占多大、哪些功能重叠
- 某些技能"装了但不生效"（很可能是文件名或 frontmatter 有问题）
铁律（违反会造成技能失效或数据丢失）
- 技能必须顶层平铺。 绝大多数宿主（WorkBuddy / Claude Code / OpenClaw）不递归扫描子目录，
把技能移进分类/子目录/会导致集体失效。要分类就只做重命名 + 生成索引报告，不要建子文件夹。 - 删除一律走回收站，禁止
rm -rf/del /F。脚本内已用SHFileOperationW+FOF_ALLOWUNDO实现。 - 动手前先完整备份整个 skills 目录（zip），并校验
testzip()通过。 - scan 只读，apply 默认 dry-run，必须显式
--yes才落盘。先在 dry-run 里核对清单再执行。 - Windows 原生 Python 不认 Git Bash 的
/d/路径，脚本内一律用C:/D:/盘符格式。
四步流程
脚本路径：scripts/housekeep.py（单文件，仅标准库，零依赖）。加载技能后先定位脚本：
HK=~/.workbuddy/skills/skills-housekeeping/scripts/housekeep.py
SK=~/.workbuddy/skills
PY=python # Windows 用 venv 里的 python.exe
第 1 步：备份（必做）
python "$HK" backup --root ~/.workbuddy/skills --out ~/skills_backup.zip
输出文件数、压缩前后体积，并自动跑 testzip() 完整性校验。
第 2 步：扫描（只读）
python "$HK" scan --root ~/.workbuddy/skills --json scan.json
输出四类建议：
| 类别 | 判定依据 | 处理 |
|---|---|---|
| 重复副本 | 正文去空白后哈希相同 / frontmatter name 相同 |
保留一个，其余送回收站 |
| 无意义目录名 | 以 skill_ 开头或 __skillhub 结尾 |
改回 slug |
| 文件名错误 | 主文件叫 skills.md |
改回 SKILL.md（否则永不加载） |
| 元数据缺陷 | 无 frontmatter / name 非小写连字符 |
补齐或规范化 |
保留哪一份的优先级：版本号高 > 文件数多 > 体积大 > 安装时间新。
版本号从 _skillhub_meta.json / _meta.json 读（含 installedAt 毫秒时间戳、source）。
若胜出方目录名是 skill_xxx 而落败方是语义名，则保留语义名那一份。
第 3 步：执行（先 dry-run）
# 预演
python "$HK" apply --root ~/.workbuddy/skills \
--merge playwright-scraper-skill:skill_2053082580726448129 \
--delete codebuddy-code,skill_2053082413554933760
# 确认清单无误后真正执行
python "$HK" apply --root ~/.workbuddy/skills \
--merge playwright-scraper-skill:skill_2053082580726448129 \
--delete codebuddy-code,skill_2053082413554933760 --yes
apply 依次做：合并增强元数据 → skills.md 改名 → 语义化重命名 → 规范 name 字段 → 送回收站。
第 4 步：出报告
python "$HK" report --root ~/.workbuddy/skills --out 技能索引报告.html
按关键词自动归到 18 个功能域（浏览器自动化 / 搜索 / 金融 / PDF / 图像生成 / 微信…），
每组可折叠，列出目录名、用途、占用、文件数；顶部是统计卡片，底部附还原方法。
未命中任何规则的进"其他"组，方便人工复核。
两个容易踩的坑
坑 1：marketplace 版带增强字段，不能直接删。
skill_2053xxx 这类目录（source=marketplace）的 SKILL.md 常带 description_zh / description_en /
allowed-tools，而语义名目录（source=skillhub）往往只有英文描述。
正确做法是先用 --merge keep:src 把增强版并入语义名目录，再删副本。
被覆盖的原文件会存为 SKILL.md.bak_before_merge。
坑 2：只看目录名会漏判。
两个目录名不同、name 也不同，但正文可能一字不差。必须做正文哈希比对，不能只比名字。
反过来，同名不同版本也要靠 _meta.json 的 version 分胜负，别盲目删。
验证清单
执行完必须逐项确认：
python "$HK" scan --root ~/.workbuddy/skills
- [ ] 无
skill_前缀 /__skillhub后缀残留 - [ ] 无"缺少 SKILL.md"的目录
- [ ] 无"重复组"
- [ ] 技能总数 = 原数 − 删除数
- [ ] 抽查 2-3 个重命名后的技能，SKILL.md 内容完好
报告应包含
- 整理成果卡片（总数 / 删除 / 重命名 / 修复 / 总占用）
- 本次操作明细（删了什么、为什么删）
- 按功能域分组的完整技能索引
- 需人工判断的重叠组 + 建议
- 还原方法（备份 zip 路径、回收站、单项还原步骤）
关键：功能相近但内容不同的技能不要自动删（如 5 个图像生成技能后端各不相同），
应在报告中标注让用户自己挑。只有内容完全相同或版本明确更旧的副本才可自动删除。
实战参考
一次真实整理的产出：111 个技能 → 103 个，删除 7 个重复副本、重命名 25 个 skill_2053xxx、
修复 4 个"装了却不生效"的技能（2 个主文件误命名为 skills.md，2 个缺 frontmatter）。
全程零丢失，7 个副本进回收站可还原。
