check-upstream

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Compare

upstream

(mattpocock/skills) with this fork, recommend what to do, and — on an explicit go — merge it in as a PR that leaves every fork-only change standing.

Repo-local by design: it lives in

.claude/skills/

, outside

skills/

, so neither

scripts/link-skills.sh

nor a consumer's

skills update

distributes it. Keep it here.

Steps 1–3 are read-only. Nothing merges before a clear yes.

将上游仓库

upstream

（mattpocock/skills）与当前派生仓库进行对比，给出操作建议，并在用户明确确认后，以PR的形式合并上游变更，同时保留所有派生仓库独有的修改。

设计为仓库本地功能：它位于

.claude/skills/

目录下，不在

skills/

目录内，因此

scripts/link-skills.sh

脚本或用户的

skills update

命令都不会分发它。请将其保留在此处。

步骤1–3为只读操作。在得到明确的确认前，不会执行任何合并操作。

Steps

步骤

Report. Run
```
bash .claude/skills/check-upstream/scripts/report.sh
```
— refs, upstream commits since the fork point, the files upstream changed, release state, fork-only paths, and a merge preview naming every file that will conflict. Done when you have its output.
```
up to date
```
→ report that and stop.
Recommend. Read the diff behind each commit the report lists (
```
git show <sha>
```
); subject lines hide what actually changed. Give every one a verdict:
- take — wanted, lands on paths the fork left alone.
- collides — touches a file this fork has edited; name the fork behaviour at risk.
- irrelevant — touches only paths this fork does not carry.
Then split them on the release boundary the report prints: commits at or below the last version bump are released; the tail above it ships in the next version. Land on one recommendation — merge now, wait for the release, or merge with named edits — and give the reason in a line.

Done when every commit carries a verdict and one recommendation stands.
Gate. Show the verdicts, the conflict list, and the recommendation, then ask for explicit go. Merge only on a clear yes.
Merge. Branch off the fork's default branch —
```
git switch -c sync/upstream-$(date +%Y-%m-%d) main
```
— so whatever branch you were working on stays out of the sync PR. Record that base's sha (
```
git rev-parse main
```
); step 6 needs it. Then
```
git merge upstream/main
```
.
Resolve. Every conflict falls into one class:
- Index files —
```
README.md
```
  ,
```
skills/*/README.md
```
  ,
```
.claude-plugin/plugin.json
```
  ,
```
skills/engineering/ask-matt/SKILL.md
```
  . Resolve as a union: every upstream entry and every fork-only entry survives. Fork-authored skills live in
```
skills/fork/
```
  , listed in
```
skills/fork/README.md
```
  and under the top-level
```
README.md
```
  's Fork heading — a block upstream never writes to, so a conflict there is a merge artefact, not a real edit. Take the fork's side of that block whole.
- Version files —
```
package.json
```
  , the
```
version
```
  field in
```
.claude-plugin/plugin.json
```
  ,
```
CHANGELOG.md
```
  . Take upstream's side whole.
- .changeset/
  — keep both sides' entries.
- Shared skills the fork edited — apply upstream's edit around the fork's behaviour. When the two genuinely contradict, stop and ask the user which wins.
Verify.
```
bash .claude/skills/check-upstream/scripts/verify.sh <pre-merge sha>
```
— every fork-only path still byte-identical, every fork-only skill still named in each index file that named it. Then
```
claude plugin validate . --strict
```
. Done when both pass. Whatever verify.sh flags is either restored or explained to the user as a deliberate resolution.
The sync branch carries these scripts, since it branches off the default branch. While this skill still sits on an unmerged branch, extract them first —
```
git archive <branch> .claude/skills/check-upstream | tar -x -C .temp/
```
— and run that copy.
PR.
```
gh pr create --repo <fork> --base <default branch>
```
. Name the fork explicitly: on a fork,
```
gh
```
aims at the upstream parent by default, which fails as
```
does not have the correct permissions to execute CreatePullRequest
```
. Body: the merged range, each resolution you made, and whatever still needs the user's eye. Report the URL.

生成报告。运行
```
bash .claude/skills/check-upstream/scripts/report.sh
```
—— 输出内容包括引用信息、派生点之后上游的提交记录、上游修改的文件、发布状态、派生仓库独有的路径，以及会产生冲突的所有文件的合并预览。获取到输出后完成此步骤。如果输出显示
```
up to date
```
→ 报告此状态并停止操作。
给出建议。查看报告中列出的每个提交背后的差异（
```
git show <sha>
```
）；提交主题行无法体现实际变更内容。为每个提交给出判定：
- 采纳 —— 变更符合需求，且涉及的路径未被派生仓库修改。
- 冲突 —— 变更触及了派生仓库已编辑的文件；指出可能受影响的派生仓库功能。
- 无关 —— 仅变更了派生仓库未包含的路径。
然后根据报告中显示的发布边界对提交进行划分：最后一次版本更新及之前的提交为已发布；之后的提交将在下一版本中发布。最终给出一个明确建议——立即合并、等待发布，或合并时进行指定修改，并给出一行理由说明。

当所有提交都有判定且给出明确建议后，完成此步骤。
确认许可。展示判定结果、冲突列表和建议，然后请求用户明确确认。仅在得到明确同意后才进行合并。
执行合并。从派生仓库的默认分支创建新分支 ——
```
git switch -c sync/upstream-$(date +%Y-%m-%d) main
```
—— 确保当前工作分支不会被同步PR影响。记录该基准分支的sha值（
```
git rev-parse main
```
）；步骤6需要用到它。然后执行
```
git merge upstream/main
```
。
解决冲突。所有冲突分为以下几类：
- 索引文件 ——
```
README.md
```
  、
```
skills/*/README.md
```
  、
```
.claude-plugin/plugin.json
```
  、
```
skills/engineering/ask-matt/SKILL.md
```
  。以合并双方内容的方式解决：保留上游的所有条目和派生仓库独有的所有条目。派生仓库创建的技能位于
```
skills/fork/
```
  目录下，在
```
skills/fork/README.md
```
  和顶层
```
README.md
```
  的 Fork 标题下列出 —— 上游仓库永远不会修改该区块，因此此处的冲突属于合并 artefact，而非实际编辑冲突。直接保留派生仓库的该区块内容。
- 版本文件 ——
```
package.json
```
  、
```
.claude-plugin/plugin.json
```
  中的
```
version
```
  字段、
```
CHANGELOG.md
```
  。完全保留上游仓库的内容。
- .changeset/
  目录 —— 保留双方的所有条目。
- 派生仓库编辑过的共享技能 —— 在保留派生仓库功能的基础上应用上游的修改。当两者存在真正的矛盾时，停止操作并询问用户选择哪一方的内容。
验证结果。运行
```
bash .claude/skills/check-upstream/scripts/verify.sh <pre-merge sha>
```
—— 确保所有派生仓库独有的路径内容完全一致，所有派生仓库独有的技能仍在对应的索引文件中列出。然后执行
```
claude plugin validate . --strict
```
。当两个验证都通过后完成此步骤。
```
verify.sh
```
标记的任何问题要么恢复原样，要么向用户说明是故意的解决方案。
同步分支包含这些脚本，因为它是从默认分支创建的。如果此技能仍位于未合并的分支上，请先提取脚本 ——
```
git archive <branch> .claude/skills/check-upstream | tar -x -C .temp/
```
—— 然后运行该副本。
创建PR。执行
```
gh pr create --repo <fork> --base <default branch>
```
。明确指定派生仓库：在派生仓库上，
```
gh
```
工具默认指向上游父仓库，这会因
```
does not have the correct permissions to execute CreatePullRequest
```
而失败。PR正文需包含合并的提交范围、你解决的每个冲突，以及仍需用户关注的内容。报告PR的URL。