基于上次更新提交差异更新 CLAUDE.md…

适用于维护带 CLAUDE.md、_/.last-update-docs 和 .claude/skills/.agents/skills 的技能仓库时，按上次更新提交到 HEAD 的差异同步文档。

适用场景

解决思路

1. 先读取 _/.last-update-docs 文件，取得 commit_hash；文件不存在时按首次处理，以直近一次提交为基准。
2. _/.last-update-docs 的格式为 commit_hash=<hash>、commit_subject=<1行目>、commit_date=<ISO 8601>；该文件由 .gitignore 排除，仅本地使用。
3. 确认变更：执行 git log <commit_hash>..HEAD --oneline 和 git diff <commit_hash>..HEAD --stat，把握变更文件与内容。
4. 更新 CLAUDE.md 时分两条系统列技能，分别更新 ## Current Skills 节和「リポジトリ管理スキル」节。
5. 系统 A 是可配布技能的全列挙（计数对象）。若存在 skills/ 目录，则列挙 skills/；否则若存在 .agents/skills/，则列挙 .agents/skills/；两者都不存在时作为空集合，不因非零退出中断。命令：if [ -d skills ]; then find -L skills -mindepth 2 -maxdepth 2 -name SKILL.md | sed -E 's#^skills/##; s#/SKILL.md$##' | sort; elif [ -d .agents/skills ]; then find -L .agents/skills -mindepth 2 -maxdepth 2 -name SKILL.md | sed -E 's#^\.agents/skills/##; s#/SKILL.md$##' | sort; fi
6. 更新 ## Current Skills (N) 的 N，N 仅统计系统 A；同时更新逗号分隔的技能名列表；若 ## Current Skills 节不存在则新建。
7. 系统 B 列挙 .claude/skills/ 与 .agents/skills/ 下的所有技能（列挙对象；是否计入 N 由 B1/B2/B3/B4 的内訳决定）。命令：find -L .claude/skills .agents/skills -mindepth 1 -maxdepth 1 -type d -exec test -f '{}/SKILL.md' ';' -print 2>/dev/null | sed -E 's#.*/##' | sort -u
8. 系统 B 的 find 必须带 -L 以追従 symlink，避免 .claude/skills/ 为 symlink 或技能实体在 .agents/skills/ 时漏列；-exec test -f '{}/SKILL.md' ';' 不经过 shell 再展开，目录名含空白也安全。
9. 系统 B 的分类不要按 symlink 位置判断；用 cd -P && pwd -P 物理解析路径，与 skills/<name> 或 .agents/skills/<name> 的物理解析结果比较。
10. B1：物理解析与 skills/<name>/ 一致；消费侧布局（无 skills/）中与 .agents/skills/<name>/ 一致也归 B1。B1 已由系统 A 计入，不因 B1 增减 N；写入 ## Current Skills (N)。
11. B2：.claude/skills/<name>/ 是含 SKILL.md 的实体，且不对应 skills/<name>/、.agents/skills/<name>/，也不在 skills-lock.json 中；不计入 N，写入「リポジトリ管理スキル（.claude/skills/ に配置）」。
12. B3：仅上游布局（存在 skills/）成立；.agents/skills/<name>/ 是实体，且 .claude/skills/<name> 的物理解析与 .agents/skills/<name> 的物理解析一致；不计入 N，写入「参照スキル（.claude/skills/ に配置）」。消费侧布局中同样一致归 B1，不归 B3。
13. B4：误配置或判定不能（skills-lock.json 掲載的实目录、物理解析不一致/不可达、symlink 到别目标、jq 缺失导致 tiebreak 未执行等）；不计入 N，不写入 CLAUDE.md，只向 stderr 输出 WARN，作为需人工处理的结构问题。
14. 定义 resolve、classify_b、extract_b1、extract_b2、extract_b3 函数。resolve 用 cd -P -- "$1" 2>/dev/null && pwd -P 返回物理路径，不可达返回空；classify_b 对系统 B 每个名字排他分类，输出 <区分>\t<名字>（B1/B2/B3），B4 只 WARN 到 stderr；extract_b1/b2/b3 从 classify_b 输出按区分过滤。
15. classify_b 的判定顺序：① .claude/skills/<n> 解析为空 → B4 WARN；② skills/<n> 解析非空且一致 → B1；③ skills/<n> 解析非空但不一致 → B4 WARN；④ .agents/skills/<n> 解析非空且一致，若存在 skills/ 目录则 B3，否则 B1；⑤ .agents/skills/<n> 解析非空但不一致 → B4 WARN；⑥ .claude/skills/<n> 解析为 .claude/skills 解析结果加 /<n> → B2 候选，再用 skills-lock.json tiebreak：无 jq→B4；jq exit 0（掲載あり）→B4 误配置；jq exit 1（掲載なし）→B2；其他→解析失败 B4；⑦ 其他情况→B4 WARN。
16. tiebreak 细节：skills-lock.json 存在时，用 jq -e --arg n "${n}" '.skills[$n] != null' skills-lock.json >/dev/null 2>&1，其退出状态 0/1/其他 三值；不要将其他误读为掲載なし，必须 fail-closed 归 B4。
17. 系统 A 的列挙元随 skills/ 是否存在切换；B1/B3 判定也随 skills/ 是否存在分支：上游布局（有 skills/）与消费侧布局（无 skills/）。
18. 用 B2、B3 更新 CLAUDE.md 的「リポジトリ管理スキル（.claude/skills/ に配置）」「参照スキル（.claude/skills/ に配置）」节；节不存在则新建。
19. 件数整合式：执行各系统抽取命令，确认 B1 + B2 + B3 + B4 = B（-L 付き全列挙）和 A − B1 = B1 に現れない配布スキル数。B4 用名称集合差分 B4 = B − (B1 ∪ B2 ∪ B3) 算出，不要数 stderr 的 WARN 行。
20. 若整合式不成立，检查 B2/B3 抽取（含 tiebreak）或计数方法；若 B4 ≥ 1，按对应 WARN 手动确认结构（symlink 化、重做 tiebreak 等；update-docs 自身不改结构）。数值示例见同目录 references/measurement-example.md（仅上游 agent-cli-skills 专用，不是其他仓库期望值）。
21. 更新 Repository Structure：当 .claude/agents/ 增删 agent 定义、.claude/rules/ 增删规则、.claude/skills/ 增删工作流技能时，更新结构树。
22. 其他更新对象：安装方法变更、新惯例追加、Skill Anatomy 变更。
23. 更新 _/.last-update-docs：用 git log -1 --format="%H" 取 commit_hash，git log -1 --format="%s" 取 commit_subject，git log -1 --format="%cI" 取 commit_date (ISO 8601)，写入 commit_hash=...、commit_subject=...、commit_date=...。
24. 最后显示更新文件列表与变更内容。
25. 验证：执行 grep "^## Current Skills" CLAUDE.md；若 [ -d skills ] 则 find -L skills -mindepth 2 -maxdepth 2 -name SKILL.md | wc -l，否则若 [ -d .agents/skills ] 则 find -L .agents/skills -mindepth 2 -maxdepth 2 -name SKILL.md | wc -l，否则 echo 0。确认 ## Current Skills (N) 的 N 与计数一致、技能名列表反映增删、_/.last-update-docs 已更新为最新提交 hash。
26. 若更新了系统 B（B2/B3），新规执行验证，不可复用既有日志/前次结果；若存在 .claude/rules/verification.md，遵循其 5 阶段 gate；调用 Step 3 定义的同一 extract_b1/extract_b2/extract_b3，不要重复写命令。
27. B4 验证：b1=$(extract_b1 | sort -u | sed '/^$/d')；b2=$(extract_b2 | sort -u | sed '/^$/d')；b3=$(extract_b3 | sort -u | sed '/^$/d')；full=$(find -L .claude/skills .agents/skills -mindepth 1 -maxdepth 1 -type d -exec test -f '{}/SKILL.md' ';' -print 2>/dev/null | sed -E 's#.*/##' | sort -u | sed '/^$/d')；union=$(printf '%s\n%s\n%s\n' "${b1}" "${b2}" "${b3}" | sed '/^$/d' | sort -u)；b4=$(comm -23 <(printf '%s\n' "${full}" | sed '/^$/d') <(printf '%s\n' "${union}" | sed '/^$/d'))。不要重定向 stderr，WARN 要保留。
28. 排他性检查：comm -12 <(printf '%s\n' "${b1}" | sed '/^$/d') <(printf '%s\n' "${b2}" | sed '/^$/d')；comm -12 <(printf '%s\n' "${b1}" | sed '/^$/d') <(printf '%s\n' "${b3}" | sed '/^$/d')；comm -12 <(printf '%s\n' "${b2}" | sed '/^$/d') <(printf '%s\n' "${b3}" | sed '/^$/d')；三条都应为空。
29. 确认 B2 stdout 与「リポジトリ管理スキル（.claude/skills/ に配置）」节一致，B3 stdout 与「参照スキル（.claude/skills/ に配置）」节一致；B1+B2+B3+B4 等于 -L 全列挙件数；b4 非空时查看对应 WARN，且不要放入任何 CLAUDE.md 节。
30. 只有 CLAUDE.md 是更新对象；个别技能 SKILL.md、references/、自动生成文件不是。
31. 确认 _/.last-update-docs 已加入 .gitignore。
32. 全列挙必须用带 -L 的 find；find .claude/skills -maxdepth 1 -mindepth 1 -type d（无 -L）只能抽 symlink 非実目录，在 .claude/skills 自身为指向 .agents/skills 的 symlink 的父 symlink 型布局中会返回空，不能用于 B2 判定。
33. github-docs 等：在存在 skills/ 的上游布局中，.claude/skills/github-docs 物理解析与 .agents/skills/github-docs 一致时，classify_b 归 B3（参照スキル），不是 B2；应记入「参照スキル」节，不是从 CLAUDE.md 排除。消费侧布局同样一致归 B1。
34. 实目录型仓库 tiebreak：① 物理解析匹配 skills/<name>/ → 配布技能（系统 A/B1），不是管理技能；② 匹配 .agents/skills/<name>/ → 有 skills/ 则 B3，无 skills/ 则系统 A/B1；③ 有 skills-lock.json 但无 jq → 判定不能，fail-closed 为 B4 并 WARN；④ skills-lock.json 的 skills 键有该名字 → 外部导入技能未 symlink 化，误配置，用 B4 报告（update-docs 不自改结构）；⑤ 以上都不满足的实体才是 B2。
35. B3 解析验证：不能只因 .agents/skills/<name> 有实体就归 B3；必须验证 .claude/skills/<name> 的物理解析（cd -P 归一化绝对路径）与 .agents/skills/<name> 物理解析一致。父 symlink 型不要求 .claude/skills/<name> 自身是 symlink。不一致或不可达 → B4 WARN，不归 B3。B3 仅限有 skills/ 的上游布局。
36. 空输出处理：2>/dev/null 只用于允许目录不存在（如无 .agents/skills）；不要立即把空输出当 0 件，先确认目标目录是否存在。
37. 代码内注释（任意）：被要求补强注释时应用，与 CLAUDE.md 同步独立。注释写「该包/服务中对象的角色」，不是「做什么」。从调用元视角、被调用先视角、与其他文件/服务的上下文说明。
38. 注释要点：写职责/边界而非算法步骤；不重复变量名/类型自明信息；补充读者不开别文件也能把握的上下文；公开 API（导出的函数/类型/常量）必须注释；非公开符号仅复杂时注释；服务间通信/事件驱动处写明连接的事件、端点。
39. 注释详细规范参照对象仓库的 .claude/rules/code-comment-style.md；不存在则按对象仓库既有注释风格。

适用边界 · 注意事项

• 不要用于更新单个技能的 SKILL.md 或 references/；该技能只更新 CLAUDE.md。
• 不要更新自动生成文件。
• 若目标仓库没有 CLAUDE.md、_/.last-update-docs 或 .claude/skills/.agents/skills 技能布局，不要套用完整分类与同步流程。