Sync Skills — Submodule Skill 与插件同步管理

概述

本仓库从 git submodule（claude-plugins-official、context7 等）引用第三方 skill 和插件，通过 复制同步 管理。

支持两种粒度：

• 组件级：同步单个 skill/commands/agents/hooks 子目录到目标插件
• 插件级：同步整个插件目录（含 plugin.json、README、LICENSE、截图等根级文件）

位置说明

.claude/skills/sync-skills/ 是本 skill 的唯一源，包含 SKILL.md、脚本和映射表，应直接提交到 git。 agents-dev/skills/sync-skills/ 是同步到 agents-dev 插件的副本，不提交到 git。

核心文件

skill-map.json 是唯一操作入口；skill-map.default.json 仅作模板，不要直接编辑。

何时使用

• 用户要求「添加一个来自 submodule 的 skill」「同步 skills」「新增映射」
• 用户提到 skill-map.json、sync-skills.py
• 需要从 claude-plugins-official 或其他 submodule 引入新 skill/插件
• 用户要求「添加插件」「同步插件」「从 submodule 复制插件」

工作流

添加新 skill 映射（组件级）

1. 确认源路径（submodule 内的 skill 目录）和目标路径（本仓插件目录下的位置）
2. 执行添加命令：

   python .claude/skills/sync-skills/scripts/sync-skills.py --add "<source_relative_path>" "<target_relative_path>"
   # 如果源可能不存在（可选依赖），加 --optional
   python .claude/skills/sync-skills/scripts/sync-skills.py --add "<source>" "<target>" --optional

3. 运行同步：

   python .claude/skills/sync-skills/scripts/sync-skills.py

4. 确认 .gitignore 中已添加对应的目标目录忽略规则

添加整个插件映射（插件级）

适用于纯镜像插件（目标完全来自 submodule，无自定义代码）。一条命令替换所有散装映射：

python .claude/skills/sync-skills/scripts/sync-skills.py --add-plugin <plugin_name>

行为：

• 自动构建路径：claude-plugins-official/plugins/<name> → <name>
• 清除该 target 下所有旧的散装映射（如 skills/、commands/ 等单独条目）
• 同步时复制整个插件目录（含 plugin.json、README、LICENSE、截图等）
• 输出 .gitignore 建议：整个插件目录应忽略不提交

适用条件：

• 目标插件是 submodule 源的完整镜像（无自定义代码混入）
• 反面例子：hookify、plugin-dev 有自定义 Python/配置，只能用组件级映射

完整流程：

# 1. 添加插件映射
python .claude/skills/sync-skills/scripts/sync-skills.py --add-plugin claude-md-management

# 2. 执行同步并提交（不再需要改 .gitignore）
python .claude/skills/sync-skills/scripts/sync-skills.py
git add claude-md-management/
git commit -m "feat(claude-md-management): mirror from upstream"

自动同步（提交前）

.claude/settings.json 中配置了 PreToolUse hook，每次 git commit 前自动执行：

1. git submodule update --init --recursive — 把 submodule 同步到 .gitmodules 锁定的 commit（不自动追 upstream 最新；想拉新版要主动跑 --remote，见下节）
2. python3 sync-skills.py — 把 submodule 内容复制到目标插件目录

无需手动操作，提交时自动触发。

Upstream 升级流程

镜像插件（claude-md-management / plugin-dev 等）的内容来自 submodule upstream，但版本号、发布节奏由本仓库控制。详见下节「版本与内容分治原则」。

判断 upstream 是否有更新：

# 检查所有 submodule 是否落后 upstream（不修改 working tree）
python .claude/skills/sync-skills/scripts/sync-skills.py --check-upstream

# 输出示例：
#   🆙 claude-plugins-official: 落后 12 commits (abc1234 → def5678 on main)
#       • def5678 feat(claude-md-management): add ...
#       • ...
#   ✅ context7: 已是最新
# exit code: 0=全部最新, 2=至少一个落后

SessionStart hook 已配置 --check-upstream --quiet，每次 Claude Code 启动会自动检查并提示。

应用升级：

# 拉 upstream HEAD 并同步内容到镜像目录（不 commit）
python .claude/skills/sync-skills/scripts/sync-skills.py --update

# 看变化、评审
git status --short
git diff <changed-dirs>

# 接受 → commit；不要 → git restore 对应目录
git add <accepted-dirs> && git commit -m "sync(upstream): pull from claude-plugins-official@<sha>"

# 若是面向用户的变更，按 multi-platform-plugin-guide bump 全仓版本

单独命令：

python .claude/skills/sync-skills/scripts/sync-skills.py --pull-upstream   # 只拉 submodule HEAD，不 sync
python .claude/skills/sync-skills/scripts/sync-skills.py                   # 只 sync，submodule 不动

手动同步

# 预览（不写入）
python .claude/skills/sync-skills/scripts/sync-skills.py --dry-run

# 正式同步
python .claude/skills/sync-skills/scripts/sync-skills.py

# 强制清除后重新复制
python .claude/skills/sync-skills/scripts/sync-skills.py --clean

查看当前映射

python .claude/skills/sync-skills/scripts/sync-skills.py --list

新机器安装流程

git clone --recurse-submodules https://github.com/SummerSec/SumSec-Skills.git
cd SumSec-Skills
python .claude/skills/sync-skills/scripts/sync-skills.py

规则

• 版本与内容分治原则：镜像插件（来自 submodule）遵循「版本号以本仓库为准、内容以 submodule upstream 为准」。
  • Why: 全仓 manifest 都对齐到本仓库 release 版本（如 1.0.22），不让 upstream 各插件的独立版本号（plugin-dev 1.0.0、claude-md-management 1.0.0……）污染本仓库节奏；同时内容由 sync-skills.py 自动从 submodule 复制，不在镜像目录里手改文件——避免 sync 把改动覆盖。
  • How to apply:
    • 不要手动编辑镜像目录下的 SKILL.md / scripts / references（如 claude-md-management/skills/*、plugin-dev/skills/*）——下次 sync 会被 upstream 覆盖；要改就改 upstream 或加新插件。
    • <mirror>/.claude-plugin/plugin.json 被 sync 自动保留：sync 脚本通过 PLUGIN_LEVEL_IGNORES 排除该文件，确保本仓库的 version 字段不被 upstream 覆盖（详见 sync-skills.py 顶部常量）。手改 plugin.json 版本号是安全的，下次 sync 不会动它。
    • upstream 升级走「Upstream 升级流程」章节，sync 后人工评审 diff 再 commit。
• 不要自动整合 skill 到聚合插件：来自 submodule 的 skill 默认按其所属的独立插件整体镜像（插件级映射）；不要把它从所属插件里抽出来再塞进 agents-dev 这类聚合插件。仅当用户明确要求「聚合到 X 插件」「合并到 agents-dev」时，才追加额外的组件级映射。
  • Why: 一个 skill 同时存在于「独立插件」和「聚合插件」会造成双轨上架、文档脱节、版本难对齐。
  • How to apply: 用户说「同步插件 X」「添加插件 X」时，只加一条插件级映射 <source>/X → X/，不动 agents-dev/ 或其它聚合插件；想聚合必须由用户主动开口。
• 映射表是唯一来源：所有 source → target 关系必须记录在 .claude/skills/sync-skills/scripts/skill-map.json
• 目标目录需要提交：同步生成的目录是 marketplace 上架内容（./claude-md-management、./plugin-dev 等），不提交会导致远端用户安装时目录为空。upstream submodule 升级后重跑 sync，把 diff 一起 commit。
• 不再使用 .gitignore 拦截同步产物：旧设计曾把这些目录 ignored，导致 marketplace 注册的插件在远端不可装。已废弃，不要再加回去。
• 插件级映射需 git rm --cached：如果目标目录之前提交过文件，需先从 git 跟踪中移除后再同步
• submodule 必须先初始化：同步前确保 git submodule update --init --recursive 已执行
• optional: true：用于源可能不存在的实验性 skill/插件，同步时跳过而非报错

skill-map.json 格式

支持两种条目类型：

组件级映射

{
  "source": "claude-plugins-official/plugins/plugin-dev/skills/agent-development",
  "target": "agents-dev/skills/agent-development"
}

插件级映射

{
  "source": "claude-plugins-official/plugins/claude-md-management",
  "target": "claude-md-management"
}

何时用组件级 vs 插件级

⚠️ 默认走插件级。来自 submodule 的插件就保持插件本体，不要拆开塞进 agents-dev 等聚合插件。组件级映射仅用于以下两种情况，且第二种必须由用户明确发起。