用途
sync-ag-shared 用于将当前仓库中 external/ag-shared/ 的变更同步到所有其他消费该子仓库的 AG 仓库（典型为 ag-charts、ag-grid 和 ag-studio 中的另外两个）。它负责完整的 yarn subrepo push / pull 周期、伴随变更以及跨仓库关联的 PR。
主要能力
- 识别源仓库与目标仓库：源仓库为技能被调用的工作目录，目标仓库为源仓库根目录的同级目录中包含 external/ag-shared/.gitrepo 的仓库。
- 分析源分支变更：通过 git diff 与 git log 汇总 ag-shared 内外的改动，并预测各目标仓库可能需要的伴随变更（如 .rulesync/ 符号链接更新、.claude/settings.json 更新、package.json 或 CI 更新、setup-prompts.sh 重跑等）。
- 展示同步计划并请求确认，用户可调整计划或跳过某些目标仓库。
- 推送源 ag-shared，并在各目标仓库创建 sync/<SOURCE_BRANCH> 分支、拉取 ag-shared 更新。
- 应用伴随变更，包括运行 setup-prompts.sh 重新生成 .claude/、更新 .rulesync/ 符号链接、运行 verify-rulesync.sh 验证、运行格式化命令等。
- 验证各仓库的 subrepo 状态、工作树是否干净以及 rulesync 验证是否通过。
- 提交、推送分支并创建互相引用的 PR；若源分支已有 PR 则复用并追加跨仓库链接。
- 同步后维护：更新各仓库 .rulesync/README.md、核对 SYNC-LOG.md 中的迁移动作、检测损坏的符号链接、输出用户摘要并提交推送。
使用方式
技能通过命令选项和参数调用。若用户提供 help 选项，技能会解释用法与前置条件后立即退出，不继续执行。
前置条件：
- Git CLI、GitHub CLI（gh）和 yarn 可用。
- 已安装 git subrepo（git subrepo --version）。
- 推送和拉取使用 yarn subrepo（不要直接用 git subrepo push/pull），其他子仓库命令（如 git subrepo status、git subrepo clean）可直接使用 git subrepo。
- 不要手动编辑 external/ag-shared/.gitrepo，只有 subrepo 命令应修改该文件。
- 应处于功能分支；若在 latest/main/master 上，技能会询问是否创建分支。
- 工作树必须干净（git status --porcelain 为空）。
- 当前仓库必须包含 external/ag-shared/.gitrepo。
可选参数：
- --skip <repo>：跳过指定目标仓库。
- --dry-run：仅分析和展示计划，不执行。
- --no-pr：同步分支但不创建 PR。
适用场景
- 在多个 AG 仓库之间传播 ag-shared 子仓库的变更。
- 当 ag-shared 远程与消费仓库不同步、上一次同步不完整或失败、或变更直接提交到 latest 需要传播时，可进行强制同步（force sync）。
- 需要为跨仓库同步创建关联 PR 并统一验证的场景。
限制与注意事项
- 工作树不干净时默认停止并报告，不会强制清理目标仓库；若目标仓库有未提交变更，默认会 stash 所有变更但需用户确认。
- subrepo pull 出现合并冲突时停止并请用户手动解决。
- 认证失败时检查 gh auth status 和 git remote -v，请用户认证。
- subrepo push/pull 失败时报告完整错误；常见原因包括历史分叉（先 pull 再 push）和缺少远程访问权限。
- 失败的 subrepo 操作可能留下 index.lock，需删除并恢复 .gitrepo 后重试。
- 在 git worktree 中调用时，功能分支已在 worktree 检出，不能在主仓库再次检出该分支；所有源仓库命令应在 worktree 工作目录执行。
- 伴随变更若修改了 external/ag-shared/ 内文件，可能触发迭代 push/pull，最多 3 轮，超过则停止询问用户。
- 创建 PR 前需审计目标分支差异，回退无关变更。
- 若分支相对 latest 无变更，技能会询问是否强制同步；用户拒绝则停止。