organize-skills

整理技能

重新整理技能库，让名称能体现每项技能实际依赖的对象；重命名时，保持符号链接和交叉引用一致。

许多配置会在共享目录中保留一个唯一的规范技能库，并将其符号链接到各个工具的中心目录（例如 ~/.claude/skills/、~/.codex/skills/）。有些技能位于项目仓库中，并通过符号链接接入中心目录。因此，一次重命名可能会影响多个符号链接，以及所有引用旧名称的文档——本技能负责管理这些连带变更。

步骤 1 — 清点

列出每项技能及其实际位置。中心目录中的条目通常是指向规范目录的符号链接：

for hub in <hub-1> <hub-2>; do
  echo "== $hub =="; ls -la "$hub"
done

使用 readlink -f 将每个名称解析到实际目录。记下哪些技能位于项目仓库中，哪些位于共享库中——重命名仓库内的技能时，必须在对应仓库中使用 git mv。

步骤 2 — 按后端分类（命名规则）

命名约定：前缀表示技能依赖的后端，依据是它实际调用的对象，而非主题。搜索每个技能目录，查找能表明依赖关系的内容：

grep -rlE "<api-host>/api|/api/<x>|<db-client>|<AUTH_TOKEN_NAME>" "$skill_dir"

• 调用特定产品的 API / 数据库 → 使用该产品的前缀（例如 acme-*）。
• 纯本地技能（浏览器自动化、离线 SOP、文件处理，不依赖后端）→ 使用通用 / 本地前缀。
• 如果某个系列包含许多技能，可保留主题中缀（例如 acme-seo-* 与 acme-reddit-*），方便相关技能排列在一起。

重命名前，先向用户说明分类结果。某项技能可能看起来与特定产品相关，但如果完全不调用后端，就应归入本地类别；反之亦然——以依赖关系为准。

步骤 3 — 重命名（并修复所有受影响的内容）

对于每次重命名 OLD → NEW：

1. 移动规范目录。
   • 位于共享库中：mv <lib>/OLD <lib>/NEW
   • 位于仓库中：cd <repo> && git mv <skills-path>/OLD <skills-path>/NEW && git commit
   • 技能放错了仓库？将其移到共享库，而不是只在原处重命名。
2. 重新设置各中心目录中的符号链接。 移除失效的旧链接，并创建指向规范目录的新链接。对镜像该技能库的每个工具中心目录都执行此操作。
3. 更新 NEW/SKILL.md 中的 name: frontmatter，使其与目录名一致——加载器依据该字段识别技能，而非文件夹名称。
4. 修复交叉引用。 其他技能以及任何长期记忆 / 笔记文件中，都可能按名称或旧路径提及 OLD：

   grep -rln "OLD" <lib> <memory-dirs> 2>/dev/null
   

   先替换最具体的字符串（先替换完整的旧路径，再替换单独的名称），这样，同时移动的技能也能正确更新路径。

步骤 4 — 验证

# broken symlinks in any hub
for hub in <hub-1> <hub-2>; do
  find -L "$hub" -maxdepth 1 -type l ! -exec test -e {} \; -print
done
# no lingering old names
grep -rn "OLD" <lib> 2>/dev/null
# each renamed skill's name: matches its dir
grep -m1 "^name:" <lib>/NEW/SKILL.md

确认加载器已使用新名称重新注册每项重命名后的技能。清理时发现任何原有的失效符号链接，也一并移除——修复成本很低，留着却容易造成混乱。

注意事项

• 切勿移除未重命名的技能。只更改命名约定要求修改的内容。
• 重命名成本低且可撤销；真正的代价在于交叉引用失效——步骤 3.4 和步骤 4 才是本技能的重点，而不是 mv。
• 对仓库内的重命名，每次逻辑上的重命名单独提交，以便分别二分排查和回滚。