sync-upstream 是一个面向 fork 仓库的上游同步技能。它的核心前提是：fork 与上游的差异往往是有意为之——重命名、改变行为、删除文件——而普通合并并不知道这些意图，可能在无冲突的情况下把上游文本重新覆盖回来。因此该技能分为两半：解决显式冲突，以及追查静默覆盖。
用途 用于将上游仓库合并进当前 fork，并在合并过程中保护 fork 有意保留的差异，避免上游改动悄悄抹掉 fork 的特性或命名。
主要能力
- 读取 ledger：fork 的差异记录在 ledger 文件中，优先查找 .agents/fork-divergences.md，其次查找 CLAUDE.md / AGENTS.md 指向的位置。若没有 ledger，则说明情况，依据 diff 和 CLAUDE.md 工作，并在最后补写一份。
- 执行合并：若已有合并进行中（git status 显示未合并路径），跳过合并直接进入冲突解决。否则优先使用仓库自带的同步脚本（如 scripts/sync-upstream.sh 或 package.json 中的类似脚本），否则执行 git fetch upstream && git merge upstream/main --no-commit --no-ff，并记录 merge base（git merge-base HEAD upstream/main）。
- 解决冲突文件：通过 git diff --name-only --diff-filter=U 列出冲突文件，对每个文件用 git diff <merge-base> upstream/main -- <path> 查看上游真实改动，再按类型解决：纯外观改动（改写、重命名）取 fork 侧；新增实质内容取上游侧并改写为 fork 的命名与事实；两者兼有则取上游文本并重新应用所有 ledger 条目；fork 有意改变或新增的行为始终取 fork 侧。规则包括：绝不对冲突文件执行 git checkout --ours <file>；描述 fork 行为的文档必须对照 fork 的 SKILL.md 重新检查，而不仅是重命名。
- 扫描静默覆盖：对 ledger 中每个重命名，统计合并前后上游侧名称的出现次数（git grep -c 与 grep -rc），找出计数上升或仅出现在合并后列表中的文件并修复；对行为差异用上游独有短语做同样检查；再用 git status 检查被上游重命名、移动或删除的文件。
- 检查仓库不变量：阅读 CLAUDE.md 中声明的不变量并逐项验证，通常包括必须列出所有已提升技能的清单、README.md 与各 bucket README.md 的条目、路由或索引技能映射，以及仓库文档中的校验命令（如 claude plugin validate . --strict、lint、链接检查）。上游新提升进发布 bucket 的技能属于决策而非修复，应列出并询问人工。
- 更新 ledger 并报告：把每个被捍卫的差异和新发现的差异写入 ledger，删除已过时的条目；按组报告已解决冲突及方向、捕获并修复的静默覆盖、检查的不变量及失败项、留给人工的决策。不提交，合并保持开放供人工审查，除非用户要求完成。
使用方式 该技能以技能形式提供，具体安装与调用方式暂未提供。使用时需在 fork 仓库中运行，依赖 git 与仓库自身的脚本和文档。
适用场景 适用于维护 fork 仓库、需要定期同步上游改动、且 fork 存在有意差异（重命名、行为变更、删除文件）的项目。
限制 不自动提交；没有 ledger 时扫描效果受限；上游新提升技能的处理需人工决策；具体安装命令、平台支持等信息暂未提供。