AGENTS.md 和 Skill 都能影响 Codex 的行为，但它们处在不同层次：AGENTS.md 提供进入工作区后始终有效的上下文、偏好和授权边界，Skill 提供某一类任务需要时才加载的专业工作流。
一个常驻，一个按需
| 维度 | AGENTS.md |
Skill |
|---|---|---|
| 主要问题 | 在这个环境中始终遵守什么 | 遇到这类任务时具体怎样完成 |
| 发现方式 | 启动任务时按目录层级读取 | 根据描述隐式匹配，或由用户显式调用 |
| 上下文成本 | 规则会进入对应工作区任务的指令链 | 默认只暴露名称和描述，选中后再读完整说明 |
| 适合内容 | 仓库约定、安全边界、必须触发的检查 | 验证流程、编辑方法、脚本、模板和专项参考 |
| 不适合内容 | 大段只在少数任务使用的操作手册 | 希望每次任务都无条件生效的基础约束 |
OpenAI Docs 说明，Codex 在开始工作前读取 AGENTS.md，并按全局、仓库和当前目录逐层组合指令；更靠近当前目录的规则出现在后面，因此可以覆盖更宽泛的上层指导：Custom instructions with AGENTS.md。
规则发现有一个容易遗漏的边界：若没有找到项目根目录，Codex 只检查当前目录，不保证自动读取父目录。多个独立子项目共用约定时，可以在各子项目的 AGENTS.md 中要求先读取共享约定。标准文件名是复数 AGENTS.md；AGENT.md 不在默认发现名单中，除非另行配置后备文件名。新会话重新加载文件规则，并不等于继承旧聊天全文；需要跨会话保留的工具能力、决策和项目状态应写入规则或项目文档。该发现边界于 2026-10-24 对照同一份官方文档核验。
Skill 使用渐进式加载：Codex 先看到每个 Skill 的名称和描述，任务匹配后才读取完整 SKILL.md。Skill 既可以由用户显式调用，也可以根据 description 隐式选择：Build skills。
为什么两者经常需要配合
假设所有仓库都要维护一个个人知识库：
全局 AGENTS.md
└─ 声明知识库位置、自动积累偏好、隐私和 Git 边界
↓
dev-knowledge Skill
└─ 验证知识、查重，并选择速记知识或专题文档如果只使用 AGENTS.md，完整编辑手册会进入每一个任务的上下文，即使当前任务完全不会产生可复用知识。如果只使用 Skill，Codex 可能缺少“跨项目都应该评估知识价值”这一常驻约定，也可能不知道敏感信息和 Git 状态的全局边界。
合理分层是：
AGENTS.md保持短小，声明目标、触发条件、权限和不可违反的边界。- Skill 承担真正需要展开的判断流程、质量标准和验证步骤。
- 项目自身的写作规范负责内容类型、页面结构和站点约定，避免在全局配置与 Skill 中重复维护所有细节。
跨项目知识库适合四层分工
知识库既会从其他仓库触发维护，又有自己的目录、导航和构建规则，因此只放一个全局 AGENTS.md 容易出现两种问题：要么全局文件塞入过多仓库细节，要么缺少足够具体的信息架构约束。
| 层级 | 应保存什么 | 不应保存什么 |
|---|---|---|
~/.codex/AGENTS.md |
跨项目触发条件、知识库位置、持续授权、隐私与 Git 边界 | 具体目录清单和长篇编辑手册 |
知识库根目录 AGENTS.md |
领域分类、页面归位、导航维护和项目验收命令 | 其他仓库也必须承担的通用触发逻辑 |
dev-knowledge Skill |
查重、核验、选择速记或专题、迁移与交付流程 | 每次任务都无条件生效的全局规则 |
writing-guide.md |
面向维护者的完整内容规范和页面示例 | Codex 的发现与触发机制 |
官方文档说明 Codex 会先加载全局指令，再沿项目目录逐级加载更靠近当前工作的 AGENTS.md；因此仓库专属的信息架构和检查命令放在知识库根目录，比继续膨胀全局规则更合适：使用 AGENTS.md 自定义指令。
但跨项目维护还有一个边界：当当前工作目录在别的仓库时，知识库根目录的 AGENTS.md 不会自然进入那次任务的指令链。因此全局规则仍要负责触发 Skill，而 Skill 必须主动读取知识库的写作规范和分类入口。四层需要职责互补，不能假设只要创建了仓库级 AGENTS.md，跨项目任务就一定会自动看到它。
触发条件、授权和结果需要分开
这是自动化配置中最容易写错的地方。
AGENTS.md 可以同时表达触发条件和用户的持续偏好。例如个人知识库规则可以明确：用户问到通用技术知识时调用 Skill，并授权在本地知识库中自动积累。Skill 被加载后仍然需要核验、查重和脱敏，但不再要求每个知识点达到长文章的门槛。
用户问到或任务产生技术知识
↓
加载 dev-knowledge 工作流
↓
核验、查重并判断内容层级
↓
速记知识 / 专题文章 / 已覆盖所以不改把“触发工作流”“用户授权”和“最终结果”分开，有两个好处：
- 用户可以授权自动积累，同时由 Skill 保证写入的是验证后的知识，而不是聊天原文。
- 已有重复、证据不足或包含敏感信息时，Skill 仍能安全地不写或只保存可泛化部分。
如何决定内容放在哪里
适合放进 AGENTS.md：
- 所有任务都要遵守的 Git 暂存边界。
- 公司代码、凭据和内部数据不得进入个人知识库。
- 某类任务必须调用专项 Skill 处理。
- 当前仓库统一使用的测试或格式化命令。
适合放进 Skill：
- 如何核验知识并选择速记或专题形式。
- 如何在已有页面中查重、合并和选择信息架构。
- 不同文档类型的编辑流程。
- 只在该工作流中使用的验证脚本、模板或参考资料。
一个简单判断方法是：如果删除这条指令会让所有任务都变得不安全或不一致，它更可能属于 AGENTS.md；如果它只在特定任务命中后才有价值，它更可能属于 Skill。
怎样筛选适合公开传播的 Skill
个人流程中反复出现的做法，不一定都适合发布成 Skill。公开 Skill 更值得优先选择同时满足以下条件的工作流：
- 任务边界清楚：可以用一句话说明在什么请求下触发、最终交付什么结果，而不是收录一组互不相关的个人偏好。
- 能改变执行质量：包含普通提示词不容易稳定复现的判断标准、验证方法、脚本或模板，而不只是“认真检查”“遵循最佳实践”。
- 跨环境仍然成立：核心能力不依赖私有仓库、内部服务或作者本人的目录结构；必要的环境差异可以在运行时发现。
- 结果可以验证：能通过测试、差异、引用、生成文件或明确的检查项判断是否完成，而不是只产生一段看似合理的描述。
- 采用成本低：默认不要求额外账号、付费连接器或大段初始化配置；安装后可以用一个真实请求立即看到价值。
OpenAI 的 Skill 文档建议每个 Skill 聚焦一个工作，默认优先使用指令，只在需要确定性行为或外部工具时加入脚本；还应使用真实请求测试 description 的触发范围。由于 Codex 会先看到名称和描述，再决定是否加载完整 SKILL.md，面向多人分发时，清楚、可区分的描述本身就是产品接口：Build skills。
对于只想在一个仓库中共享的流程，可以放在仓库的 .agents/skills；需要跨仓库或面向更多用户分发时，官方建议将可复用 Skill 打包为 Plugin。发布前先用独立、低风险的真实请求验证“该触发时触发、不该触发时不触发”，比堆叠更多说明更重要。
验证配置是否真正生效
修改 AGENTS.md 后，应从目标目录启动一个新任务，让 Codex 列出当前加载的指令来源，确认全局、仓库和子目录规则的顺序。官方文档指出指令链会在每次 run 或 TUI 会话开始时重建，因此已有会话不会自动重新加载刚修改的全局规则。
修改 Skill 后，可以用一个真实但低风险的请求验证四个行为：
- 描述匹配时能否正确选择 Skill。
- 基础命令或短概念能否进入分类速记页，而不是被错误地拒绝或扩写成长文。
- 已有重复、证据不足或敏感内容出现时，是否能正确跳过或泛化。
- 多个相关速记成熟后，是否能整理成专题文章并避免维护两份全文。
测试重点应是可观察的决策和产物，而不是只搜索某个固定句子是否出现在输出中。