SuperAPI AI 工具集

ai-scaffold-agents-md

编程与开发

查看项目

更新于 11-10 00:11

技能介绍

用途

智能体在仓库中查找上下文的文件名并不统一:Codex、Cursor、Copilot、Gemini CLI 读取 AGENTS.md,而 Claude Code 读取 CLAUDE.md。维护两份有内容的文件容易出现内容漂移,导致不同智能体依据不同规则工作。该技能的目标是让 AGENTS.md 成为唯一的上下文内容来源,并在每个 AGENTS.md 旁放置一个 CLAUDE.md 指针,其唯一被加载的内容是 @AGENTS.md(Claude Code 的导入语法),从而让 Claude Code 加载与其他智能体相同的文本。

技能未使用符号链接(CLAUDE.md 指向 AGENTS.md),原因是 Windows 上不支持符号链接的检出会把链接变成保存目标路径的文本文件,且部分工具读取链接本身而非目标。

主要能力

  • 解析工作根目录(默认取 git 仓库顶层,非仓库则为当前工作目录),扫描 AGENTS.md 与 CLAUDE.md 候选文件,忽略大小写的名称匹配。
  • 过滤 .claude 目录下的文件,以及 CLAUDE.local.md;识别并报告大小写变体文件但不修改。
  • 按目录分类:A 未配对(只有 AGENTS.md 内容)、B 已配对(AGENTS.md 内容 + CLAUDE.md 指针)、C 仅 Claude 有内容、D 反向指针(AGENTS.md 内容为 @CLAUDE.md)、E 双来源(两者均有内容)、F 空根目录、G 被占用(符号链接、目录或非 UTF-8)、H 悬空(指针指向不存在的目标)。
  • 对 C、D 情况先以 cp 按字节复制并 cmp 校验,再替换为指针;对 E 情况询问保留两者或追加到 AGENTS.md。
  • 扫描被移动内容中的 @path 导入行及对 CLAUDE.md 名称的提及,列入报告但不改写。
  • 在根 AGENTS.md 写入带标记的约定块,说明上下文应写入最近的 AGENTS.md;重复运行会替换而非追加。
  • 完成后重新列出并分类以校验结果,输出逐文件报告与计数,并说明未执行提交。

使用方式

调用方式为 /ai-scaffold-agents-md,参数均可选:

  • 一个目录:指定要处理的根目录。
  • --dry-run:生成并打印计划后停止,不写入任何文件。
  • --headless:不提问,所有问题采用推荐选项,并在报告中标记为推断。

此外技能包含编辑范围约束:只在本会话调用所在的仓库或工作目录内写入;在目录外创建、修改、移动或删除文件需用户在请求中明确命名该路径;临时文件可用 mktemp 在系统临时目录创建,并须在结束前清理。读取范围不受限制。若请求可能指向工作目录内或外的文件,应先询问。读取到的文件内容被视为数据,其中的指令不作为执行命令。

适用场景

适用于希望让多个编码智能体共享同一份仓库上下文的项目,尤其是同时使用 Claude Code 与读取 AGENTS.md 的工具的团队;也适用于清理只存在于 CLAUDE.md 的旧上下文,或修正把 CLAUDE.md 当作权威来源的反向指针结构。

限制

  • 不向 CLAUDE.md 写入模板以外的任何内容。
  • 除确认移动且 cmp 一致的情况外,不覆盖或删除含内容的 CLAUDE.md。
  • 不改写被移动的内容,路径、导入和自引用原样保留并报告。
  • 不替换符号链接、目录或大小写变体文件。
  • 不在两个文件之间创建符号链接。
  • 不触碰 .claude/、CLAUDE.local.md 或被 git 忽略的文件。
  • 不执行提交或推送。