用途
AGENTS.md Manager 是一个用于为任意项目创建、审计和维护 AGENTS.md 文件与 Codex CLI 配置的技能。它可以初始化新的 AGENTS.md、刷新已有文件、从 CLAUDE.md 迁移、生成 config.toml、创建 .rules 规则文件，以及搭建 .agents/skills/ 技能脚手架。
主要能力与工作模式
技能根据任务选择不同模式：
| 模式 | 适用场景 | 脚本 |
|---|---|---|
| Create | 新项目需要 AGENTS.md | scripts/analyze_project.py 后编写 |
| Refresh | 现有 AGENTS.md 需要审计 | scripts/validate_agents_md.py |
| Convert | 从 CLAUDE.md 迁移 | scripts/convert_claude_to_agents.py |
| Config | 生成 config.toml | scripts/generate_config_toml.py |
| Rules | 创建 .rules 文件 | 参见 references/starlark-rules-spec.md |
| Skills | 搭建 .agents/skills/ | scripts/scaffold_codex_skill.py |
项目分析
运行分析脚本可检测技术栈、现有配置和缺口：
python3 ~/.claude/skills/agents-md-manager/scripts/analyze_project.py [project_path]
输出为 JSON 报告，包含技术栈、命令、目录结构以及 Codex 产物清单（AGENTS.md、config.toml、.rules、.agents/skills/、CLAUDE.md 转换候选）。
AGENTS.md 生成
采用 WHAT/WHY/HOW 框架，仅使用纯 Markdown——不支持 @import 语法，也不使用 YAML frontmatter。推荐章节包括项目名称与简介、Commands（开发/测试/构建/检查命令）、Structure（目录说明）、Conventions（关键约定）、Boundaries（Always/Ask/Never 三类代理护栏）、Troubleshooting（常见问题与修复）。约束条件：单个文件目标 200 行以内，嵌套子目录文件 100 行以内；遵守 32 KiB 限制（project_doc_max_bytes）；必须包含 Boundaries 章节。项目类型专属模板见 references/templates.md，发现与拼接规则见 references/agents-md-spec.md。
CLAUDE.md 转换
python3 ~/.claude/skills/agents-md-manager/scripts/convert_claude_to_agents.py <claude_md_path> [output_path]
输出 AGENTS.md 和 conversion_report.json，列出所有转换和需人工复核的条目。主要转换：@import 内联或嵌套化；hooks 转为 .rules 建议；技能调用转为自然语言描述；Claude 专有命令被移除。完整字段映射见 references/conversion-mapping.md。
配置生成
生成全局 ~/.codex/config.toml 或项目级 .codex/config.toml：
python3 ~/.claude/skills/agents-md-manager/scripts/generate_config_toml.py [--global | --project <path>] [--model MODEL] [--sandbox MODE]
覆盖 model、reasoning effort、personality、sandbox mode、MCP servers、profiles、可信项目、可写根目录等。完整字段参考见 references/config-toml-reference.md。
Rules 文件
在 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。
Codex 技能脚手架
按 Codex 格式（不同于 Claude 的 .claude/skills/）创建 .agents/skills/<name>/：
python3 ~/.claude/skills/agents-md-manager/scripts/scaffold_codex_skill.py <name> [--path <dir>]
生成含 name 与 description frontmatter（Codex 两者均必需）的 SKILL.md，以及用于 UI 元数据的 agents/openai.yaml。与 Claude 技能的格式差异见 references/codex-skills-format.md。
审计清单
刷新现有 AGENTS.md 时需验证：是否小于 32 KiB？是否无 @import 语法？是否无 YAML frontmatter？记录的 commands 是否与项目配置一致？目录引用是否与实际结构匹配？是否无密钥或凭据？嵌套层级是否与根级一致？是否存在 AGENTS.override.md 冲突？是否小于 200 行（超过 200 警告，超过 400 报错）？运行自动化审计：
python3 ~/.claude/skills/agents-md-manager/scripts/validate_agents_md.py [project_path]
嵌套 AGENTS.md（单体仓库）
在单体仓库中可在多层放置 AGENTS.md，例如根目录放仓库级约定、各服务目录放各自文件，并用 AGENTS.override.md 覆盖。每个目录最多一个文件；Codex 会从根目录拼接到当前工作目录（越靠近 CWD 的文件越靠后，覆盖前面的）；同一目录下 AGENTS.override.md 优先于 AGENTS.md；嵌套文件保持聚焦且 100 行以内。
集成说明
codex-orchestrator 执行子代理时使用本技能创建的配置文件；claude-md-manager 是 Claude Code 的 CLAUDE.md 姊妹技能，可用转换模式桥接；子代理配置文件管理建议使用 codex-orchestrator。
参考文档
| 文件 | 内容 |
|---|---|
| references/agents-md-spec.md | AGENTS.md 发现、拼接、覆盖、大小限制、跨代理兼容性 |
| 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 模板 |
适用场景
适用于使用 Codex CLI 的项目进行代理配置管理，包括新项目初始化、已有文件审计、从 Claude Code 迁移、生成全局或项目级配置文件、定义命令审批规则，以及单体仓库的多层级 AGENTS.md 组织。
限制
AGENTS.md 仅支持纯 Markdown，不兼容 @import 和 YAML frontmatter；文件有 32 KiB 大小上限；.rules 文件需手动编写，无生成脚本；具体收费、价格或平台支持情况暂未提供。