agents-md-generator

AGENTS.md 生成器（根目录 + 嵌套目录，便携式）

目标

维护简洁且信息密度高的 AGENTS.md 文件：

• 根目录 AGENTS.md — 说明仓库用途、导航、通用工具链、规范命令，以及文档和技能的链接。
• 嵌套 AGENTS.md — 说明模块/软件包用途、本地命令和模块参考资料。

采用渐进式披露：保持 AGENTS.md 简洁；将详细信息放到文档或技能中。

---

技能位置（特定于 Agent）

• 不要假定 .agents/ 或任何固定目录存在。
• 技能可能位于：
  • 仓库内（嵌入式），
  • 或外部/全局技能库中（外部）。
• 引用本地技能时，只使用项目已在使用的现有技能根目录，或仓库文档中已提及的现有项目路径。
• 如果不存在本地技能目录 — 仅按名称引用技能（外部）。
• 切勿仅为存放技能而创建隐藏的 Agent 目录。

---

资源路由

将模板用作框架，而非照搬输出：

• 仅在创建或更新根目录 AGENTS.md 时，读取 references/AGENTS_TEMPLATE_ROOT.md。
• 仅在确认某目录是需要单独 AGENTS.md 的嵌套模块后，读取 references/AGENTS_TEMPLATE_MODULE.md。
• 替换或删除每个占位符。最终的 AGENTS.md 文件不得包含未解析的 <...> 模板标记。

---

运行时机

在以下情况下运行此技能：

• AGENTS.md 缺失、臃肿、相互矛盾或过时。
• 需要生成、修复、精简、拆分或更新 AGENTS.md。
• 出现新的软件包/服务/模块。
• 仓库结构发生变化（单体仓库扩展或拆分）。
• 团队希望在不同技术栈中保持 Agent 上下文一致。

---

工作流（确定性）

1. 探查仓库结构

• 确定仓库根目录（如有 git 根目录则优先使用）。
• 检测语言/工具标记：
  • package.json、pnpm-workspace.yaml
  • go.mod、go.work
  • pyproject.toml
  • Cargo.toml
  • pubspec.yaml
  • pom.xml、build.gradle
• 查找 docs/、README.md 和现有的 AGENTS.md。

---

2. 检测模块边界

如果某目录符合以下条件，则创建嵌套 AGENTS.md：

• 包含独立的构建/软件包清单
• 或代表可部署的服务单元（apps/、services/、packages/）
• 且相较于父级范围，提供不同的命令、文档、所有权、部署说明或工具链指导。

不要创建仅重复根目录说明的嵌套 AGENTS.md。

---

3. 生成/更新根目录 AGENTS.md

约束：

• 理想长度：≤ 60 行
• 必须包含：
  • 一句话说明仓库用途
  • 主要工具链/软件包管理器
  • 规范命令（如非标准）
  • 文档链接
  • 在模块目录内时阅读嵌套 AGENTS.md 的说明
  • 可选的技能引用（自适应：本地或外部）
• 保留现有根目录 AGENTS.md 中已验证的命令、文档、安全/机密信息/部署警告及重要本地规则。

---

4. 生成/更新嵌套 AGENTS.md

约束：

• 理想长度：≤ 40 行
• 必须包含：
  • 一句话说明模块用途
  • 模块专用命令
  • 本地文档参考
  • 可选的技能引用（自适应）
• 保留现有嵌套 AGENTS.md 中已验证的模块警告、所有权、部署说明及本地规则。

---

5. 渐进式披露规则

• 不要嵌入风格指南、CI 政策或架构细节。
• 优先链接到现有文档及外部或本地技能。
• 仅包含实际存在的链接，或明确列为命令/政策来源的链接。
• 如果存在权威文档，用链接替换过时的长篇内容。
• 除非对正确性/安全至关重要，否则避免使用“始终/绝不”规则。

---

6. 安全性/正确性检查

• 切勿编造命令。
• 根据以下内容推断命令：
  • 软件包脚本
  • Makefile
  • CI 配置
  • README
• 如果无法确定 → 写入： “已知命令：参见 ”
• 保留关键警告（安全、机密信息、部署）。

输出约定

仅创建或更新以下文件：

• <repo_root>/AGENTS.md
• <module_dir>/AGENTS.md

不要创建 Agent 配置目录。

---

技能引用策略

在 AGENTS.md 中添加技能引用时：

1. 如果检测到本地技能目录

   See: <detected-skill-root>/<skill-name>/SKILL.md
   

2. 如果不存在本地目录

   Skill: agents-md-generator (external)
   

切勿假设文件系统路径。

---

验证

完成前，请确认：

• 仅创建或更新了根目录或模块目录中的 AGENTS.md 文件。
• 最终的 AGENTS.md 文件中没有未解决的 <...> 占位符。
• 相对文档链接均有效，或明确指向命令/策略的源文件。
• 命令均由 package scripts、Makefile、CI 配置或 README 支持。如果没有已验证的命令，请使用 Known commands: see <existing file>。
• 行数限制符合要求：根目录文件不超过 60 行，嵌套模块文件不超过 40 行。
• 仅在确认模块边界后创建嵌套文件。
• 保留现有 AGENTS.md 文件中的关键警告。