sync-skill-registry

name	sync-skill-registry
description	技能注册表同步工具。扫描任意 agent skill 目录中的 */SKILL.md 并自动更新对应 skill-invocation.md 中的技能列表表格。用于新增、修改或删除本地技能后同步注册表。触发词：同步注册表、更新技能列表、sync skill registry、update skill registration、刷新技能列表、同步技能表格。
category	工具发现

sync-skill-registry（技能注册表同步）

读取任意 agent skill 目录中的 */SKILL.md frontmatter 元数据，自动更新 skill-invocation.md 中的技能表格，确保注册表与本地技能文件保持一致。

工作流程

# 1️⃣ 预览变更（推荐先 dry-run）
python3 .claude/skills/sync-skill-registry/scripts/sync_skill_registry.py --dry-run

# 2️⃣ 确认无误后应用
python3 .claude/skills/sync-skill-registry/scripts/sync_skill_registry.py

# 首次安装时先预览，再去掉 --dry-run 执行；skill 会随首次应用复制到目标项目
python3 skills/sync-skill-registry/scripts/sync_skill_registry.py --profile generic --root /path/to/project --create --with-skill --dry-run
python3 skills/sync-skill-registry/scripts/sync_skill_registry.py --profile generic --root /path/to/project --create --with-skill

# 完全自定义路径
python3 skills/sync-skill-registry/scripts/sync_skill_registry.py --root /path/to/project --skills-dir .my-agent/skills --registry-file .my-agent/rules/common/skill-invocation.md --dry-run

何时使用

场景	说明
新增本地技能	创建了新的 <skills-dir>/<name>/SKILL.md 后运行
修改现有技能	更新了 SKILL.md 的 name、description 或 category 后运行
删除本地技能	移除了某个 SKILL.md 后运行（自动移除表格条目）
定期同步	不确定当前注册表是否最新时运行 --dry-run 检查
批量清理	多个技能变更后一次同步

工作原理

1. 扫描：遍历 <skills-dir>/*/SKILL.md，解析 YAML frontmatter（name, description, category）
2. 解析：读取当前 skill-invocation.md，提取现有表格条目
3. 比较：
   • 新增：SKILL.md 存在但表格中缺失 → 生成新行加入对应分类
   • 更新：SKILL.md 和表格中都存在 → 用 frontmatter 覆盖表格行
   • 删除：上次同步标记为受管、但 SKILL.md 已不存在 → 移除行
   • 保留：无 SKILL.md 的条目（如 excalidraw-diagram、dataviz）→ 保持不变
4. 生成：按分类重新生成 Markdown 表格
5. 写入：替换 ## 技能列表 至 ### 1. 分析意图 之间的内容

分类确定优先级

1. SKILL.md frontmatter 中的 category 字段（首选）
2. FALLBACK_CATEGORIES 映射（symlink 技能如 skill-creator）
3. 当前表格中的位置推断
4. 默认值"未分类"

注意事项

• 只管理 ## 技能列表 ~ ### 1. 分析意图 之间的表格内容
• 生成区会写入 skill-registry:managed 所有权标记；首次升级保留无法判定来源的旧条目，后续同步可准确删除已移除的本地 skill
• 不修改手动维护部分（核心原则、Obsidian 说明、分析意图、匹配技能、错误处理）
• 不创建或删除任何 SKILL.md 文件
• 支持 --profile <name> 读取 profiles/*.yaml 中的任意内置 profile，也支持 --skills-dir 与 --registry-file 完全自定义路径
• 同步 --dry-run 预览变更，确认后再应用