agents-md-manager

AGENTS.md 管理器

为任意项目创建和维护 AGENTS.md 文件及 Codex CLI 配置。

核心工作流

确定模式：

模式	使用场景	脚本
创建	新项目需要 AGENTS.md	scripts/analyze_project.py 然后编写
刷新	现有 AGENTS.md 需要审查	scripts/validate_agents_md.py
转换	从 CLAUDE.md 迁移	scripts/convert_claude_to_agents.py
配置	生成 config.toml	scripts/generate_config_toml.py
规则	创建 .rules 文件	参见 references/starlark-rules-spec.md
技能	搭建 .agents/skills/	scripts/scaffold_codex_skill.py

1. 项目分析

运行分析以检测技术栈、现有配置和缺失项：

python3 ~/.claude/skills/agents-md-manager/scripts/analyze_project.py [project_path]

输出：JSON 报告，包含技术栈、命令、目录结构和 Codex 产物清单（AGENTS.md、config.toml、.rules、.agents/skills/、可转换的 CLAUDE.md）。

2. 生成 AGENTS.md

仅使用纯 Markdown 应用 WHAT/WHY/HOW 框架——不得使用 @import 语法或 YAML frontmatter。

推荐章节

# Project Name

Brief description.

## Commands
- Dev: `pnpm dev`
- Test: `pnpm test`
- Build: `pnpm build`
- Lint: `pnpm lint`

## Structure
- `/src` — Application source
- `/tests` — Test suites

## Conventions
- [Critical convention 1]
- [Critical convention 2]

## Boundaries
- Always: Run tests before committing
- Ask: Before adding production dependencies
- Never: Modify migration files directly

## Troubleshooting
- [Common issue and fix]

约束

• 每个文件控制在 200 行以内，嵌套子目录文件控制在 100 行以内
• 遵守 32 KiB 限制（project_doc_max_bytes）
• 仅使用纯 Markdown——不得使用 @import 或 YAML frontmatter
• 包含“边界”章节（始终/询问/绝不），为 Agent 设定防护规则
• 项目类型专用模板请参见 references/templates.md
• 发现和拼接规则请参见 references/agents-md-spec.md

3. 转换 CLAUDE.md

将现有 CLAUDE.md 转换为 AGENTS.md 格式：

python3 ~/.claude/skills/agents-md-manager/scripts/convert_claude_to_agents.py <claude_md_path> [output_path]

输出 AGENTS.md 和 conversion_report.json，列出转换内容和需要人工审查的项目。

主要转换：内联或嵌套 @import；将钩子转换为 .rules 建议；将技能调用转换为说明文字；移除 Claude 专属命令。

完整的逐字段映射请参见 references/conversion-mapping.md。

4. 生成配置

生成 ~/.codex/config.toml（全局）或 .codex/config.toml（项目级）：

python3 ~/.claude/skills/agents-md-manager/scripts/generate_config_toml.py [--global | --project <path>] [--model MODEL] [--sandbox MODE]

涵盖：模型、推理力度、个性、沙盒模式、MCP 服务、配置档案、可信项目、可写入根目录。

完整字段参考请参见 references/config-toml-reference.md。

5. 规则文件

使用 Starlark 创建用于命令审批的 .rules 文件。位置：~/.codex/rules/（全局）或 .codex/rules/（项目级）。规则文件需手动编写——此格式没有生成脚本。目录中的所有 .rules 文件都会加载并合并。

常见模式：

• 允许包管理器命令（npm、pip、cargo）
• 阻止破坏性操作（rm -rf、git push --force）
• 对敏感命令请求审查（git commit、gh pr create）

语法和示例请参见 references/starlark-rules-spec.md。

6. Codex 技能

以 Codex 格式搭建 .agents/skills/<name>/（不同于 Claude 的 .claude/skills/）：

python3 ~/.claude/skills/agents-md-manager/scripts/scaffold_codex_skill.py <name> [--path <dir>]

创建包含 name 和 description frontmatter 的 SKILL.md（Codex 要求两者都必须提供），并创建用于 UI 元数据的 agents/openai.yaml。

与 Claude 技能的格式差异请参见 references/codex-skills-format.md。

7. 审查清单

刷新现有 AGENTS.md 时，验证以下内容：

• 是否小于 32 KiB？（project_doc_max_bytes 限制）
• 是否未使用 @import 语法？（AGENTS.md 不支持）
• 是否没有 YAML frontmatter？（AGENTS.md 不使用）
• 所有文档中列出的命令是否都已根据项目配置验证？
• 目录引用是否与实际结构相符？
• 是否没有秘密信息或凭据？
• 嵌套层级是否与根目录一致？
• 是否没有与 AGENTS.override.md 冲突？
• 是否小于 200 行？（超过 200 行时警告，超过 400 行时报错）

运行自动化审查：

python3 ~/.claude/skills/agents-md-manager/scripts/validate_agents_md.py [project_path]

8. 嵌套 AGENTS.md（Monorepo）

对于 Monorepo，请在多个层级放置 AGENTS.md：

/AGENTS.md              # Repo-wide conventions
/services/
  payments/
    AGENTS.override.md  # Payments-specific overrides
  search/
    AGENTS.md           # Search service conventions

• 每个目录最多放置一个文件
• Codex 会从根目录串联到当前工作目录（越靠近当前工作目录的文件越靠后，优先级越高）
• 同一目录中的 AGENTS.override.md 优先于 AGENTS.md
• 每个嵌套文件应聚焦于特定内容，且不超过 100 行

集成说明

• codex-orchestrator：此技能会创建配置文件；codex-orchestrator 使用这些文件执行子 Agent
• claude-md-manager：面向 Claude Code 的 CLAUDE.md 的配套技能；使用转换模式进行衔接
• 如需管理子 Agent 配置，请使用 codex-orchestrator

参考文档

文件	内容
references/agents-md-spec.md	AGENTS.md 的查找、串联、覆盖、大小限制及跨 Agent 兼容性
references/config-toml-reference.md	完整的 config.toml 字段参考
references/starlark-rules-spec.md	.rules 文件语法、prefix_rule()、决策类型
references/codex-skills-format.md	.agents/skills/ 格式、openai.yaml、Claude 技能的差异
references/conversion-mapping.md	CLAUDE.md 到 AGENTS.md 的逐字段映射
references/templates.md	按项目类型划分的 AGENTS.md 模板