[Owlbay]

做了什么

从最新 main（含已合并的 #6，0645b71）开出。

上游清单

新增 docs/UPSTREAMS.md，由 scripts/render-upstreams.py 根据 skills.json 和 skills.lock.json 生成。每个已同步上游写明仓库、作者、许可证、安装范围、锁定提交，以及收录的 skill 和分类。未收录路径来自 skills.json 的 excluded：

• emilkowalski：performance-cheatsheet.md（不是 skill，要点已在 animation-performance）
• jakubkrehel：build-design、state-machine、teardown（不在安装清单里）

参考整理单独一节，目前是 enesozturk/dimensional-drawing，不进 vendor/，不锁定提交。

scripts/check.sh 会重新生成并比对这份文档，过期就失败。README 和 docs/README.md 已链过去。

每周检查并开 PR

新增 .github/workflows/upstream-update.yml，每周一 01:00 UTC，也可 workflow_dispatch。它用 scripts/sync-upstream.py 拉取最新提交；有变化时先跑 scripts/check.sh 和 scripts/sync-upstream.py --check，再由 scripts/upstream-pr.py --push 开 PR，或强制更新已打开的 upstream-sync 分支上的同一个 PR。没有变化不开 PR，也不合并。

PR 正文包含每个上游的旧/新提交、compare 链接、变更文件、许可证文件有没有变化，以及新 skill。新 skill 不写入 skills.json。扫描只看已经在同步的 skill 目录（例如 skills/、plugin/skills/），忽略 .claude/、.cursor/ 里的副本。

原来的 .github/workflows/sync-upstream.yml 会直接推到默认分支，已删掉，避免和这个 PR 流程抢写。

actions/checkout 固定在 11bd71901bbe5b1630ceea73d27597364c9af683（v4.2.2）。workflow 权限只有 contents: write 和 pull-requests: write，用仓库自带的 GITHUB_TOKEN。

顺手跟上的锁定提交

为了让 --check 通过，这次把已经前进的上游锁定一起更新了。已同步文件内容没有变化：

• impeccable：7510e23 → 5e745ac（上游改的是 README）
• emilkowalski：2d22863 → a81dbca（提交说明是 add remove-animations skill）

skills/remove-animations 是新 skill，没有自动收录。要收的话另改 skills.json 并指定分类。

需要在仓库设置里做的事

workflow 用 GITHUB_TOKEN 推送 upstream-sync 并开 PR。请到 Settings → Actions → General：

1. Workflow permissions 选 Read and write permissions。组织如果把 token 限制成只读，workflow 里的 permissions 提不上去。
2. 勾选 Allow GitHub Actions to create and approve pull requests。不勾的话，token 不能创建 PR。

不需要额外的 PAT。upstream-sync 不要设成分支保护，否则每周的强制更新会被拒绝。

验证

• scripts/check.sh：通过（含清单比对和 upstream-pr.py --self-test）
• scripts/sync-upstream.py --check：通过，四家上游都已是最新
• upstream-pr.py --self-test：PR 正文含 compare 链接、许可证提示、新 skill 提示；已排除和 .claude/ 副本不会被当成新 skill
• 干净工作区上 upstream-pr.py --dry-run --before skills.lock.json：打印「没有变化，不开 PR」
• 临时 git 仓库上复现 workflow 的空/非空判断：干净则不开 PR，有未提交文件则会进入检查
• 脏工作区配上假的 --report：正文列出 brand-new，并写明没有自动加入清单
• actionlint 1.7.7 检查 upstream-update.yml 和 check.yml：通过
• 本环境没有 act，没有在 Docker 里跑完整 Actions