用途
sync-contract 用于解决代码变更后代理契约文档(AGENTS.md 和 skills/*/SKILL.md)与代码树脱节的问题。这些文档中会引用文件路径、函数名、版本号、标志默认值、CI 步骤等事实,代码变更会使这些引用在无声中失效。该技能要求在每次代码变更后、宣布任务完成前运行,作为变更收尾的最后一步。
主要能力
-
识别变更范围:通过
git diff --name-only origin/main...HEAD或git status --short查看已修改的文件。 -
定位受影响的契约文档:在 AGENTS.md 和 skills/ 中搜索变更涉及的路径、包名、CLI 标志或导出符号,按区域检查对应文档(如包布局、CLI 子命令、CI 步骤、Makefile、go.mod、CONTRIBUTING.md 对应 AGENTS.md;特定领域如 internal/substrate、internal/guest、internal/metadata、ate-system/atenet-router 地址、E2E 设置对应 skills/substrate/SKILL.md)。
-
逐文档核对清单:确认文档中每个路径存在(用 ls 验证);每个函数/常量/标志仍以原名存在;每个数字(文件数、包数、版本)重新推导而非直接信任;每个“唯一位置”或“不存在 X”的陈述在整个代码树中重新检查;已删除的行为从文档中删除;重命名的行为更新名称;未来代理可能出错的新行为以事实加位置的形式补充;优先使用指针(如“见 go.mod”)而非复制易变的值。
-
结构快速检查:当 AGENTS.md 或 skills/ 被修改时,运行一行命令验证符号链接(CLAUDE.md、GEMINI.md)以及每个 skills/<name>/SKILL.md 是否已在 AGENTS.md 中索引。
使用方式
该技能以 diff 驱动的过程形式提供,按步骤执行:先检查变更,再搜索受影响的契约文档,然后逐文档核对清单,最后运行结构检查。具体操作包括 git diff、grep 搜索、ls 验证以及提供的 shell 一行命令。
适用场景
适用于 google/ax 项目中任何代码变更后的收尾阶段,确保 AGENTS.md 和技能文档与代码保持一致,避免后续代理基于过时信息工作。
限制
该技能针对 google/ax 项目的特定目录结构和文档约定设计,其他项目可能需要调整。资料中未提供关于安装方式、收费、平台支持或效果保证的信息。