القائمة
更新本项目的上游 submodule，并基于真实 git 变更分析生成文档报告。用于用户要求同步 `upstream/` 下仓库、检查上游最近更新、梳理新增内容、在 `docs/` 写更新说明，或筛选哪些更新值得优先吸收和推荐时。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
何时使用需要为编程项目、monorepo 或多级目录创建/更新 AGENTS.md、CLAUDE.md 软链接、项目级 agent 操作手册、子目录局部规则、验证命令和 Coding Agent 上下文边界时使用。
分析代码库结构并生成中文 token-lean 架构文档。
用于构建或维护个人 LLM 驱动的知识库。触发词：将资料导入 wiki、查询 wiki 知识、检查 wiki 质量、'添加到 wiki'、'我了解什么关于'，或任何提到 'LLM wiki' 的场景。
当有书面实施计划要在单独会话中执行并带审查检查点时使用
用户明确要求隔离工作区、并行分支验证或临时试验时使用 - 创建隔离的 git worktree
开始开发编程相关对话时使用 - 建立如何查找和使用 skills，在做出任何响应前要求先检查适用的 skill
| name | update-upstream-repos |
| description | 更新本项目的上游 submodule，并基于真实 git 变更分析生成文档报告。用于用户要求同步 `upstream/` 下仓库、检查上游最近更新、梳理新增内容、在 `docs/` 写更新说明，或筛选哪些更新值得优先吸收和推荐时。 |
用这个 skill 处理“更新上游仓库并写总结”这一类任务。目标不是只改 gitlink，而是产出一份有证据的更新报告。
按下面顺序执行，不要跳步：
用户请求
|
v
检查约束与受影响文档
|
v
识别要更新的 submodule
|
v
拉取远端并更新 gitlink
|
v
基于真实 commit 区间生成摘要
|
v
阅读必要的上游 README / docs / skill 文件
|
v
写 docs 报告 + 同步 AGENTS/CLAUDE
先做这些检查：
find . -type f \( -name 'AGENTS.md' -o -name 'CLAUDE.md' \)，识别需要同步的文档。AGENTS.md、.gitmodules、README.md 中与 submodule 和文档同步有关的段落。如果网络慢或访问失败，先设置项目约定的代理：
export https_proxy=http://127.0.0.1:7897
export http_proxy=http://127.0.0.1:7897
export all_proxy=socks5://127.0.0.1:7897
先看当前状态：
git submodule status --recursive
git status --short
推荐更新方式：
git submodule update --remote
git -C upstream/<repo> fetch --all --tags
git -C upstream/<repo> pull --ff-only
git submodule update --remote 会按 .gitmodules 里的 branch = main 前进，但通常会把 submodule 工作树留在 detached HEAD。这个项目要求更新后把所有已初始化的 upstream/* submodule 都切回本地 main，避免未发生 gitlink 变化的新初始化仓库停在 detached HEAD。
更新后立刻执行：
uv run .agents/skills/update-upstream-repos/scripts/switch_updated_submodules_to_main.py
如只想处理根仓库当前有 gitlink diff 的 submodule，可显式加 --changed-only；常规上游同步不要使用这个窄模式。
更新后不要立刻总结，先确认根仓库里真的有 gitlink 变化：
git diff --submodule=short HEAD
如果没有变化，就明确写明“已检查但当前没有可同步更新”。
使用本 skill 自带脚本生成 Markdown 草稿：
uv run .agents/skills/update-upstream-repos/scripts/generate_upstream_report.py
常用变体：
uv run .agents/skills/update-upstream-repos/scripts/generate_upstream_report.py \
--output docs/upstream-updates/YYYY-MM-DD-upstream-updates.md
uv run .agents/skills/update-upstream-repos/scripts/generate_upstream_report.py \
--range upstream/superpowers:<old_sha>..<new_sha>
脚本只负责整理事实：
脚本不会替你下结论。任何“值得推荐”的判断都必须回到真实 commit、README、docs 或具体文件 diff。
优先使用本 skill 自带的零依赖校验脚本：
uv run .agents/skills/update-upstream-repos/scripts/validate_skill.py
这个脚本只使用 Python 标准库，避免 uv run 环境下缺少 PyYAML 时校验失败。
必要时，也可以验证切分支脚本是否可用：
uv run .agents/skills/update-upstream-repos/scripts/switch_updated_submodules_to_main.py --help
只针对发生变化的仓库补充阅读，避免把整个上游仓库都塞进上下文：
判断“值得推荐”的依据只能来自这些证据：
写报告前，先打开 references/report-template.md。
输出文档时遵守这些规则：
docs/upstream-updates/，命名优先使用 YYYY-MM-DD-upstream-updates.md如果本次更新改变了稳定事实，必须同步更新相关 AGENTS.md 或 CLAUDE.md。稳定事实包括：
不要写流水账。只写后续 agent 真正需要知道的高信息密度知识。