交代 · AGENTS.md、config 与 SkillsBrief It · AGENTS.md, config.toml, and Skills.
同一句话你跟它说了十遍:测试用这条命令、别碰那个目录、PR 要带说明。AGENTS.md 治这个 —— 它不是 Codex 私产,是六万多个开源仓库在用的开放标准,全局、仓库根、子目录逐层叠加,离当前目录最近的赢。config.toml 管机器上的默认:模型、沙箱、审批、MCP,一份配置三个本地面共用。重复的流程再往上沉一层:存成 Skill,$名字 唤起,用到才加载正文。这一章讲三层交代怎么分工 —— 事实进 AGENTS.md,默认进 config,流程进 skill,以及为什么「它自己攒的 memories」不能替你立规矩。You've said the same thing ten times: run tests with this command, don't touch that directory, PRs need a description. AGENTS.md is the cure — and it isn't Codex-proprietary: it's an open standard used by over sixty thousand open-source repos, layering global, repo-root, and subdirectory files with the closest one winning. config.toml holds the machine's defaults: model, sandbox, approvals, MCP — one configuration shared by all three local fronts. Repeated procedures settle one layer up: saved as a Skill, summoned by $name, body loaded only on use. This chapter splits the three briefings — facts into AGENTS.md, defaults into config, procedures into skills — and why the memories it gathers on its own can't replace rules you set.
10 分钟 · 初稿 2026.0710 Min · Drafted 2026.07
同一句话你跟它说了十遍:测试跑这条命令、别碰那个目录、PR 要带说明。模型不跨会话记事,每个新对话都是一张白纸 —— 除非你把交代写下来。Codex 有三层能写:事实和规范进 AGENTS.md,机器上的默认进 config.toml,重复的流程沉成 Skill。这一章讲三层怎么分工,以及一条容易被高估的边界:它自己攒的 memories,不能替你立规矩。You've said the same thing ten times: run tests with this command, don't touch that directory, PRs need a description. Models don't remember across sessions; every new chat is a blank page — unless you write the briefing down. Codex has three places to write it: facts and standards into AGENTS.md, the machine's defaults into config.toml, repeated procedures settling into a Skill. This chapter splits the three, and one boundary that's easy to overrate: the memories it gathers on its own can't set your rules.
— I
AGENTS.md:不是 Codex 私产,是开放标准AGENTS.md: Not Codex-Proprietary, an Open Standard.
先纠正一个常见误解:AGENTS.md 不是 OpenAI 发明的私有格式。它是「一个引导编码 agent 的简单开放格式」,被六万多个开源项目使用,Cursor、Copilot、Devin、Warp、Gemini CLI 等一大票 agent 都读它。1注 1Note 1agents.md(标准站)—— 一句话定位「一个引导编码 agent 的简单开放格式」;称被六万多个开源项目使用,支持方包括 OpenAI Codex、Cursor、Jules、Devin、GitHub Copilot Coding Agent、Warp、Zed、opencode、Gemini CLI、Aider 等。规则:「离被改文件最近的 AGENTS.md 赢;显式的用户对话指令压过一切。」就是普通 Markdown,用什么标题都行。截至 2026-07-17。agents.md (the standard site) — one-liner 'a simple, open format for guiding coding agents'; says it's used by over 60k open-source projects, with support from OpenAI Codex, Cursor, Jules, Devin, GitHub Copilot Coding Agent, Warp, Zed, opencode, Gemini CLI, Aider, and more. The rule: 'The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything.' It's just standard Markdown; use any headings you like. As of 2026-07-17.这意味着你为 Codex 写的这份交代,换个工具照样管用 —— 你投的时间不绑死在一家。规则也简单:离被改文件最近的 AGENTS.md 赢,而你当场在对话里说的话压过文件里的一切。1注 1Note 1agents.md(标准站)—— 一句话定位「一个引导编码 agent 的简单开放格式」;称被六万多个开源项目使用,支持方包括 OpenAI Codex、Cursor、Jules、Devin、GitHub Copilot Coding Agent、Warp、Zed、opencode、Gemini CLI、Aider 等。规则:「离被改文件最近的 AGENTS.md 赢;显式的用户对话指令压过一切。」就是普通 Markdown,用什么标题都行。截至 2026-07-17。agents.md (the standard site) — one-liner 'a simple, open format for guiding coding agents'; says it's used by over 60k open-source projects, with support from OpenAI Codex, Cursor, Jules, Devin, GitHub Copilot Coding Agent, Warp, Zed, opencode, Gemini CLI, Aider, and more. The rule: 'The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything.' It's just standard Markdown; use any headings you like. As of 2026-07-17.First, correct a common misconception: AGENTS.md isn't an OpenAI-invented proprietary format. It's 'a simple, open format for guiding coding agents,' used by over sixty thousand open-source projects and read by a long list of agents — Cursor, Copilot, Devin, Warp, Gemini CLI, and more.1注 1Note 1agents.md(标准站)—— 一句话定位「一个引导编码 agent 的简单开放格式」;称被六万多个开源项目使用,支持方包括 OpenAI Codex、Cursor、Jules、Devin、GitHub Copilot Coding Agent、Warp、Zed、opencode、Gemini CLI、Aider 等。规则:「离被改文件最近的 AGENTS.md 赢;显式的用户对话指令压过一切。」就是普通 Markdown,用什么标题都行。截至 2026-07-17。agents.md (the standard site) — one-liner 'a simple, open format for guiding coding agents'; says it's used by over 60k open-source projects, with support from OpenAI Codex, Cursor, Jules, Devin, GitHub Copilot Coding Agent, Warp, Zed, opencode, Gemini CLI, Aider, and more. The rule: 'The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything.' It's just standard Markdown; use any headings you like. As of 2026-07-17. Which means the briefing you write for Codex still works if you switch tools — your time isn't locked to one vendor. The rule is simple too: the closest AGENTS.md to the edited file wins, and what you say live in the chat overrides everything in the files.1注 1Note 1agents.md(标准站)—— 一句话定位「一个引导编码 agent 的简单开放格式」;称被六万多个开源项目使用,支持方包括 OpenAI Codex、Cursor、Jules、Devin、GitHub Copilot Coding Agent、Warp、Zed、opencode、Gemini CLI、Aider 等。规则:「离被改文件最近的 AGENTS.md 赢;显式的用户对话指令压过一切。」就是普通 Markdown,用什么标题都行。截至 2026-07-17。agents.md (the standard site) — one-liner 'a simple, open format for guiding coding agents'; says it's used by over 60k open-source projects, with support from OpenAI Codex, Cursor, Jules, Devin, GitHub Copilot Coding Agent, Warp, Zed, opencode, Gemini CLI, Aider, and more. The rule: 'The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything.' It's just standard Markdown; use any headings you like. As of 2026-07-17.Codex 动手前先读它,发现链是分层叠加的:全局的 ~/.codex/AGENTS.md 打底,然后从项目根往当前目录逐层走,每个目录取一个文件、从根往下拼 —— 越靠近你正在改的文件,越晚出现、覆盖越前面的。2注 2Note 2OpenAI Codex 文档 · Custom instructions with AGENTS.md —— Codex 动手前先读 AGENTS.md。发现链:全局 ~/.codex/AGENTS.md(或 AGENTS.override.md)→ 项目根往当前目录逐层走,每目录取一个文件(override > AGENTS.md > 回退名),从根往下拼接,越靠近当前目录越晚出现、因此覆盖更早的。默认上限 project_doc_max_bytes 32 KiB;撞上限可抬高上限或把指令拆到嵌套目录。截至 2026-07-17。OpenAI Codex Docs · Custom instructions with AGENTS.md — Codex reads AGENTS.md before doing any work. Discovery chain: global ~/.codex/AGENTS.md (or AGENTS.override.md) → from the project root down to the current directory, one file per directory (override > AGENTS.md > fallback names), concatenated root-down, so files closer to the current directory appear later and override earlier ones. Default cap project_doc_max_bytes 32 KiB; on hitting the cap, raise the limit or split instructions across nested directories. As of 2026-07-17.所以一个 monorepo 里,根目录放全仓通用规矩,子服务目录放它自己的特殊规矩,离得近的自动赢。起步不用手写:CLI 里 /init 生成一份起草稿。6注 6Note 6OpenAI Codex 文档 · Best practices —— 一旦某个 prompt 模式好用,就用 AGENTS.md 固化它。CLI 里 /init 是脚手架命令,生成一份起步 AGENTS.md,再照你团队实际的构建 / 测试 / 审查 / 发布方式改。官方判断:短而准的 AGENTS.md 胜过又长又空的;「当 Codex 同一个错犯第二次,让它做个复盘并更新 AGENTS.md」;文件太大就让主文件精简、把计划 / 代码审查 / 架构等拆成任务专用的 markdown 文件来引用。截至 2026-07-17。OpenAI Codex Docs · Best practices — once a prompting pattern works, codify it with AGENTS.md. In the CLI, /init is the quick-start command that scaffolds a starter AGENTS.md, which you then edit to match how your team actually builds, tests, reviews, and ships. Official judgment: a short, accurate AGENTS.md beats a long, vague one; 'when Codex makes the same mistake twice, ask it for a retrospective and update AGENTS.md'; when the file gets too large, keep the main file concise and reference task-specific markdown files for planning, code review, or architecture. As of 2026-07-17.Codex reads it before doing any work, and the discovery chain layers: the global ~/.codex/AGENTS.md underneath, then from the project root down to the current directory, one file per directory, concatenated root-down — the closer to the file you're editing, the later it appears and the more it overrides.2注 2Note 2OpenAI Codex 文档 · Custom instructions with AGENTS.md —— Codex 动手前先读 AGENTS.md。发现链:全局 ~/.codex/AGENTS.md(或 AGENTS.override.md)→ 项目根往当前目录逐层走,每目录取一个文件(override > AGENTS.md > 回退名),从根往下拼接,越靠近当前目录越晚出现、因此覆盖更早的。默认上限 project_doc_max_bytes 32 KiB;撞上限可抬高上限或把指令拆到嵌套目录。截至 2026-07-17。OpenAI Codex Docs · Custom instructions with AGENTS.md — Codex reads AGENTS.md before doing any work. Discovery chain: global ~/.codex/AGENTS.md (or AGENTS.override.md) → from the project root down to the current directory, one file per directory (override > AGENTS.md > fallback names), concatenated root-down, so files closer to the current directory appear later and override earlier ones. Default cap project_doc_max_bytes 32 KiB; on hitting the cap, raise the limit or split instructions across nested directories. As of 2026-07-17. So in a monorepo, the root holds repo-wide rules and a sub-service directory holds its own, with the closer one winning automatically. Don't write the first draft by hand: /init in the CLI scaffolds one.6注 6Note 6OpenAI Codex 文档 · Best practices —— 一旦某个 prompt 模式好用,就用 AGENTS.md 固化它。CLI 里 /init 是脚手架命令,生成一份起步 AGENTS.md,再照你团队实际的构建 / 测试 / 审查 / 发布方式改。官方判断:短而准的 AGENTS.md 胜过又长又空的;「当 Codex 同一个错犯第二次,让它做个复盘并更新 AGENTS.md」;文件太大就让主文件精简、把计划 / 代码审查 / 架构等拆成任务专用的 markdown 文件来引用。截至 2026-07-17。OpenAI Codex Docs · Best practices — once a prompting pattern works, codify it with AGENTS.md. In the CLI, /init is the quick-start command that scaffolds a starter AGENTS.md, which you then edit to match how your team actually builds, tests, reviews, and ships. Official judgment: a short, accurate AGENTS.md beats a long, vague one; 'when Codex makes the same mistake twice, ask it for a retrospective and update AGENTS.md'; when the file gets too large, keep the main file concise and reference task-specific markdown files for planning, code review, or architecture. As of 2026-07-17.
一份短而准的项目交代 —— 只写它猜不到的A short, accurate project briefing — only what it can't guess
写什么、写多少,官方的判断很干脆:短而准胜过长而空 —— 只收它读代码猜不到的东西(构建 / 测试命令、和默认不同的规范、禁区、踩过的坑)。6注 6Note 6OpenAI Codex 文档 · Best practices —— 一旦某个 prompt 模式好用,就用 AGENTS.md 固化它。CLI 里 /init 是脚手架命令,生成一份起步 AGENTS.md,再照你团队实际的构建 / 测试 / 审查 / 发布方式改。官方判断:短而准的 AGENTS.md 胜过又长又空的;「当 Codex 同一个错犯第二次,让它做个复盘并更新 AGENTS.md」;文件太大就让主文件精简、把计划 / 代码审查 / 架构等拆成任务专用的 markdown 文件来引用。截至 2026-07-17。OpenAI Codex Docs · Best practices — once a prompting pattern works, codify it with AGENTS.md. In the CLI, /init is the quick-start command that scaffolds a starter AGENTS.md, which you then edit to match how your team actually builds, tests, reviews, and ships. Official judgment: a short, accurate AGENTS.md beats a long, vague one; 'when Codex makes the same mistake twice, ask it for a retrospective and update AGENTS.md'; when the file gets too large, keep the main file concise and reference task-specific markdown files for planning, code review, or architecture. As of 2026-07-17.什么时候加一行?一条好用的触发律:Codex 同一个错犯第二次,就让它做个复盘、把教训写进 AGENTS.md。6注 6Note 6OpenAI Codex 文档 · Best practices —— 一旦某个 prompt 模式好用,就用 AGENTS.md 固化它。CLI 里 /init 是脚手架命令,生成一份起步 AGENTS.md,再照你团队实际的构建 / 测试 / 审查 / 发布方式改。官方判断:短而准的 AGENTS.md 胜过又长又空的;「当 Codex 同一个错犯第二次,让它做个复盘并更新 AGENTS.md」;文件太大就让主文件精简、把计划 / 代码审查 / 架构等拆成任务专用的 markdown 文件来引用。截至 2026-07-17。OpenAI Codex Docs · Best practices — once a prompting pattern works, codify it with AGENTS.md. In the CLI, /init is the quick-start command that scaffolds a starter AGENTS.md, which you then edit to match how your team actually builds, tests, reviews, and ships. Official judgment: a short, accurate AGENTS.md beats a long, vague one; 'when Codex makes the same mistake twice, ask it for a retrospective and update AGENTS.md'; when the file gets too large, keep the main file concise and reference task-specific markdown files for planning, code review, or architecture. As of 2026-07-17.文件长到臃肿就拆 —— 主文件保持精简,专门的细则放进子目录里更近的文件。上面那段 Review guidelines 不是摆设:第 9 章 GitHub 上的自动审查,读的正是它。What to write and how much, the official judgment is crisp: short and accurate beats long and vague — include only what it can't infer from the code (build / test commands, standards that differ from defaults, off-limits areas, gotchas).6注 6Note 6OpenAI Codex 文档 · Best practices —— 一旦某个 prompt 模式好用,就用 AGENTS.md 固化它。CLI 里 /init 是脚手架命令,生成一份起步 AGENTS.md,再照你团队实际的构建 / 测试 / 审查 / 发布方式改。官方判断:短而准的 AGENTS.md 胜过又长又空的;「当 Codex 同一个错犯第二次,让它做个复盘并更新 AGENTS.md」;文件太大就让主文件精简、把计划 / 代码审查 / 架构等拆成任务专用的 markdown 文件来引用。截至 2026-07-17。OpenAI Codex Docs · Best practices — once a prompting pattern works, codify it with AGENTS.md. In the CLI, /init is the quick-start command that scaffolds a starter AGENTS.md, which you then edit to match how your team actually builds, tests, reviews, and ships. Official judgment: a short, accurate AGENTS.md beats a long, vague one; 'when Codex makes the same mistake twice, ask it for a retrospective and update AGENTS.md'; when the file gets too large, keep the main file concise and reference task-specific markdown files for planning, code review, or architecture. As of 2026-07-17. When to add a line? A useful trigger: the second time Codex makes the same mistake, have it write a retrospective and fold the lesson into AGENTS.md.6注 6Note 6OpenAI Codex 文档 · Best practices —— 一旦某个 prompt 模式好用,就用 AGENTS.md 固化它。CLI 里 /init 是脚手架命令,生成一份起步 AGENTS.md,再照你团队实际的构建 / 测试 / 审查 / 发布方式改。官方判断:短而准的 AGENTS.md 胜过又长又空的;「当 Codex 同一个错犯第二次,让它做个复盘并更新 AGENTS.md」;文件太大就让主文件精简、把计划 / 代码审查 / 架构等拆成任务专用的 markdown 文件来引用。截至 2026-07-17。OpenAI Codex Docs · Best practices — once a prompting pattern works, codify it with AGENTS.md. In the CLI, /init is the quick-start command that scaffolds a starter AGENTS.md, which you then edit to match how your team actually builds, tests, reviews, and ships. Official judgment: a short, accurate AGENTS.md beats a long, vague one; 'when Codex makes the same mistake twice, ask it for a retrospective and update AGENTS.md'; when the file gets too large, keep the main file concise and reference task-specific markdown files for planning, code review, or architecture. As of 2026-07-17. When the file bloats, split it — keep the main file lean and put specific rules in closer files in subdirectories. That Review guidelines block above isn't decoration: chapter 9's automatic review on GitHub reads exactly it.
— II
config.toml:机器上的默认config.toml: The Machine's Defaults.
AGENTS.md 管「这个项目怎么回事」,config.toml 管「这台机器上 Codex 默认怎么做」—— 模型、沙箱档、审批策略、思考力度、MCP 服务器,都在这里定死一次,省得每次开会话重设。3注 3Note 3OpenAI Codex 文档 · Config basics —— 个人默认在 ~/.codex/config.toml,项目覆盖在 .codex/config.toml(仅信任项目加载)。优先级(高到低):CLI 标志 / -c 覆盖 > 项目 config(越近越优先)> profile 文件 > 用户 config > 系统 config > 内置默认。常改项:model、approval_policy、sandbox_mode、model_reasoning_effort、personality、[features] 开关(MCP 服务器的完整字段见 config-reference)。原话:「The CLI and IDE extension share the same configuration layers.」截至 2026-07-17。OpenAI Codex Docs · Config basics — personal defaults live in ~/.codex/config.toml, project overrides in .codex/config.toml (trusted projects only). Precedence (high to low): CLI flags / -c overrides > project config (closest wins) > profile files > user config > system config > built-in defaults. Commonly changed: model, approval_policy, sandbox_mode, model_reasoning_effort, personality, [features] flags (the full MCP-server schema lives in config-reference). Verbatim: 'The CLI and IDE extension share the same configuration layers.' As of 2026-07-17.个人默认放 ~/.codex/config.toml,项目特有的行为放项目里的 .codex/config.toml(且只在你信任那个项目时才加载)。优先级从高到低是:命令行标志 → 项目 config(越近越优先)→ profile → 用户 config → 系统 config → 内置默认。3注 3Note 3OpenAI Codex 文档 · Config basics —— 个人默认在 ~/.codex/config.toml,项目覆盖在 .codex/config.toml(仅信任项目加载)。优先级(高到低):CLI 标志 / -c 覆盖 > 项目 config(越近越优先)> profile 文件 > 用户 config > 系统 config > 内置默认。常改项:model、approval_policy、sandbox_mode、model_reasoning_effort、personality、[features] 开关(MCP 服务器的完整字段见 config-reference)。原话:「The CLI and IDE extension share the same configuration layers.」截至 2026-07-17。OpenAI Codex Docs · Config basics — personal defaults live in ~/.codex/config.toml, project overrides in .codex/config.toml (trusted projects only). Precedence (high to low): CLI flags / -c overrides > project config (closest wins) > profile files > user config > system config > built-in defaults. Commonly changed: model, approval_policy, sandbox_mode, model_reasoning_effort, personality, [features] flags (the full MCP-server schema lives in config-reference). Verbatim: 'The CLI and IDE extension share the same configuration layers.' As of 2026-07-17.AGENTS.md governs 'what this project is about'; config.toml governs 'how Codex defaults on this machine' — model, sandbox setting, approval policy, reasoning effort, MCP servers, all fixed once here so you don't reset them each session.3注 3Note 3OpenAI Codex 文档 · Config basics —— 个人默认在 ~/.codex/config.toml,项目覆盖在 .codex/config.toml(仅信任项目加载)。优先级(高到低):CLI 标志 / -c 覆盖 > 项目 config(越近越优先)> profile 文件 > 用户 config > 系统 config > 内置默认。常改项:model、approval_policy、sandbox_mode、model_reasoning_effort、personality、[features] 开关(MCP 服务器的完整字段见 config-reference)。原话:「The CLI and IDE extension share the same configuration layers.」截至 2026-07-17。OpenAI Codex Docs · Config basics — personal defaults live in ~/.codex/config.toml, project overrides in .codex/config.toml (trusted projects only). Precedence (high to low): CLI flags / -c overrides > project config (closest wins) > profile files > user config > system config > built-in defaults. Commonly changed: model, approval_policy, sandbox_mode, model_reasoning_effort, personality, [features] flags (the full MCP-server schema lives in config-reference). Verbatim: 'The CLI and IDE extension share the same configuration layers.' As of 2026-07-17. Personal defaults go in ~/.codex/config.toml, project-specific behavior in the project's .codex/config.toml (loaded only when you trust that project). Precedence, high to low: command-line flags → project config (closest wins) → profiles → user config → system config → built-in defaults.3注 3Note 3OpenAI Codex 文档 · Config basics —— 个人默认在 ~/.codex/config.toml,项目覆盖在 .codex/config.toml(仅信任项目加载)。优先级(高到低):CLI 标志 / -c 覆盖 > 项目 config(越近越优先)> profile 文件 > 用户 config > 系统 config > 内置默认。常改项:model、approval_policy、sandbox_mode、model_reasoning_effort、personality、[features] 开关(MCP 服务器的完整字段见 config-reference)。原话:「The CLI and IDE extension share the same configuration layers.」截至 2026-07-17。OpenAI Codex Docs · Config basics — personal defaults live in ~/.codex/config.toml, project overrides in .codex/config.toml (trusted projects only). Precedence (high to low): CLI flags / -c overrides > project config (closest wins) > profile files > user config > system config > built-in defaults. Commonly changed: model, approval_policy, sandbox_mode, model_reasoning_effort, personality, [features] flags (the full MCP-server schema lives in config-reference). Verbatim: 'The CLI and IDE extension share the same configuration layers.' As of 2026-07-17.和第 2 章那条「一台引擎」呼应:CLI 与 IDE 扩展共用同一套配置层 —— 你在 config.toml 里定的模型和沙箱档,两个本地面同时生效。3注 3Note 3OpenAI Codex 文档 · Config basics —— 个人默认在 ~/.codex/config.toml,项目覆盖在 .codex/config.toml(仅信任项目加载)。优先级(高到低):CLI 标志 / -c 覆盖 > 项目 config(越近越优先)> profile 文件 > 用户 config > 系统 config > 内置默认。常改项:model、approval_policy、sandbox_mode、model_reasoning_effort、personality、[features] 开关(MCP 服务器的完整字段见 config-reference)。原话:「The CLI and IDE extension share the same configuration layers.」截至 2026-07-17。OpenAI Codex Docs · Config basics — personal defaults live in ~/.codex/config.toml, project overrides in .codex/config.toml (trusted projects only). Precedence (high to low): CLI flags / -c overrides > project config (closest wins) > profile files > user config > system config > built-in defaults. Commonly changed: model, approval_policy, sandbox_mode, model_reasoning_effort, personality, [features] flags (the full MCP-server schema lives in config-reference). Verbatim: 'The CLI and IDE extension share the same configuration layers.' As of 2026-07-17.所以调它是一次性投资:配一次,两端通用。别把该长期钉住的默认反复在命令行里临时传 —— 命令行标志留给一次性的例外,持久的偏好写进 config。Echoing chapter 2's 'one engine': the CLI and IDE extension share the same configuration layers — the model and sandbox setting you fix in config.toml take effect on both local fronts at once.3注 3Note 3OpenAI Codex 文档 · Config basics —— 个人默认在 ~/.codex/config.toml,项目覆盖在 .codex/config.toml(仅信任项目加载)。优先级(高到低):CLI 标志 / -c 覆盖 > 项目 config(越近越优先)> profile 文件 > 用户 config > 系统 config > 内置默认。常改项:model、approval_policy、sandbox_mode、model_reasoning_effort、personality、[features] 开关(MCP 服务器的完整字段见 config-reference)。原话:「The CLI and IDE extension share the same configuration layers.」截至 2026-07-17。OpenAI Codex Docs · Config basics — personal defaults live in ~/.codex/config.toml, project overrides in .codex/config.toml (trusted projects only). Precedence (high to low): CLI flags / -c overrides > project config (closest wins) > profile files > user config > system config > built-in defaults. Commonly changed: model, approval_policy, sandbox_mode, model_reasoning_effort, personality, [features] flags (the full MCP-server schema lives in config-reference). Verbatim: 'The CLI and IDE extension share the same configuration layers.' As of 2026-07-17. So tuning it is a one-time investment: configure once, use on both. Don't keep passing a durable default on the command line — flags are for one-off exceptions; persistent preferences go in config.
— III
Skills:把重复的流程沉成一个词Skills: Sink a Repeated Procedure into One Word.
有些交代不是一句事实,是一整套多步流程:发版的检查清单、跑一份数据管道、按团队口吻写 changelog。这些沉成 Skill:一个目录加一份 SKILL.md(必含 name 和 description),旁边可放脚本和参考。4注 4Note 4OpenAI Codex 文档 · Build skills —— 技能建立在开放的 agent skills 标准(agentskills.io)上:一个目录加一份 SKILL.md(必含 name 与 description)加可选脚本 / 参考。progressive disclosure:Codex 先只拿每个技能的名字、描述、路径(初始清单至多占 2% 上下文或 8000 字符),决定用某个技能时才读它完整的 SKILL.md。触发:$名字 显式提及或 /skills,或按描述隐式匹配。位置分仓库 .agents/skills、用户 ~/.agents/skills、admin、系统内置。旧的自定义 prompts 已弃用,改用 skills;要跨团队分发则打包成 plugin。截至 2026-07-17。OpenAI Codex Docs · Build skills — skills build on the open agent skills standard (agentskills.io): a directory plus a SKILL.md (must include name and description) plus optional scripts / references. Progressive disclosure: Codex starts with only each skill's name, description, and path (the initial list uses at most 2% of context or 8,000 characters), and reads a skill's full SKILL.md only when it decides to use it. Triggers: $name explicit mention or /skills, or implicit matching by description. Locations span repo .agents/skills, user ~/.agents/skills, admin, and system-bundled. Old custom prompts are deprecated in favor of skills; to distribute across a team, package as a plugin. As of 2026-07-17.它建立在开放的 agent skills 标准上,和 AGENTS.md 一样不绑死一家。关键在加载方式 —— progressive disclosure:Codex 平时只拿每个技能的名字和描述(初始清单至多占 2% 上下文),真决定用某个技能时才读它完整的正文。4注 4Note 4OpenAI Codex 文档 · Build skills —— 技能建立在开放的 agent skills 标准(agentskills.io)上:一个目录加一份 SKILL.md(必含 name 与 description)加可选脚本 / 参考。progressive disclosure:Codex 先只拿每个技能的名字、描述、路径(初始清单至多占 2% 上下文或 8000 字符),决定用某个技能时才读它完整的 SKILL.md。触发:$名字 显式提及或 /skills,或按描述隐式匹配。位置分仓库 .agents/skills、用户 ~/.agents/skills、admin、系统内置。旧的自定义 prompts 已弃用,改用 skills;要跨团队分发则打包成 plugin。截至 2026-07-17。OpenAI Codex Docs · Build skills — skills build on the open agent skills standard (agentskills.io): a directory plus a SKILL.md (must include name and description) plus optional scripts / references. Progressive disclosure: Codex starts with only each skill's name, description, and path (the initial list uses at most 2% of context or 8,000 characters), and reads a skill's full SKILL.md only when it decides to use it. Triggers: $name explicit mention or /skills, or implicit matching by description. Locations span repo .agents/skills, user ~/.agents/skills, admin, and system-bundled. Old custom prompts are deprecated in favor of skills; to distribute across a team, package as a plugin. As of 2026-07-17.一份几百行的发版手册,平时几乎不占地方。Some briefings aren't one fact but a whole multi-step procedure: a release checklist, running a data pipeline, writing a changelog in the team's voice. These settle into a Skill: a directory plus a SKILL.md (must include name and description), with scripts and references alongside.4注 4Note 4OpenAI Codex 文档 · Build skills —— 技能建立在开放的 agent skills 标准(agentskills.io)上:一个目录加一份 SKILL.md(必含 name 与 description)加可选脚本 / 参考。progressive disclosure:Codex 先只拿每个技能的名字、描述、路径(初始清单至多占 2% 上下文或 8000 字符),决定用某个技能时才读它完整的 SKILL.md。触发:$名字 显式提及或 /skills,或按描述隐式匹配。位置分仓库 .agents/skills、用户 ~/.agents/skills、admin、系统内置。旧的自定义 prompts 已弃用,改用 skills;要跨团队分发则打包成 plugin。截至 2026-07-17。OpenAI Codex Docs · Build skills — skills build on the open agent skills standard (agentskills.io): a directory plus a SKILL.md (must include name and description) plus optional scripts / references. Progressive disclosure: Codex starts with only each skill's name, description, and path (the initial list uses at most 2% of context or 8,000 characters), and reads a skill's full SKILL.md only when it decides to use it. Triggers: $name explicit mention or /skills, or implicit matching by description. Locations span repo .agents/skills, user ~/.agents/skills, admin, and system-bundled. Old custom prompts are deprecated in favor of skills; to distribute across a team, package as a plugin. As of 2026-07-17. It builds on the open agent skills standard, unbound to one vendor like AGENTS.md. The key is the loading — progressive disclosure: Codex normally holds only each skill's name and description (the initial list at most 2% of context), and reads a skill's full body only when it decides to use it.4注 4Note 4OpenAI Codex 文档 · Build skills —— 技能建立在开放的 agent skills 标准(agentskills.io)上:一个目录加一份 SKILL.md(必含 name 与 description)加可选脚本 / 参考。progressive disclosure:Codex 先只拿每个技能的名字、描述、路径(初始清单至多占 2% 上下文或 8000 字符),决定用某个技能时才读它完整的 SKILL.md。触发:$名字 显式提及或 /skills,或按描述隐式匹配。位置分仓库 .agents/skills、用户 ~/.agents/skills、admin、系统内置。旧的自定义 prompts 已弃用,改用 skills;要跨团队分发则打包成 plugin。截至 2026-07-17。OpenAI Codex Docs · Build skills — skills build on the open agent skills standard (agentskills.io): a directory plus a SKILL.md (must include name and description) plus optional scripts / references. Progressive disclosure: Codex starts with only each skill's name, description, and path (the initial list uses at most 2% of context or 8,000 characters), and reads a skill's full SKILL.md only when it decides to use it. Triggers: $name explicit mention or /skills, or implicit matching by description. Locations span repo .agents/skills, user ~/.agents/skills, admin, and system-bundled. Old custom prompts are deprecated in favor of skills; to distribute across a team, package as a plugin. As of 2026-07-17. A several-hundred-line release manual costs almost nothing on idle days.存好之后有两条入口:你打 $名字 显式唤起,或 Codex 按描述判定相关就隐式加载 —— 所以描述要写清「什么时候该用我」。4注 4Note 4OpenAI Codex 文档 · Build skills —— 技能建立在开放的 agent skills 标准(agentskills.io)上:一个目录加一份 SKILL.md(必含 name 与 description)加可选脚本 / 参考。progressive disclosure:Codex 先只拿每个技能的名字、描述、路径(初始清单至多占 2% 上下文或 8000 字符),决定用某个技能时才读它完整的 SKILL.md。触发:$名字 显式提及或 /skills,或按描述隐式匹配。位置分仓库 .agents/skills、用户 ~/.agents/skills、admin、系统内置。旧的自定义 prompts 已弃用,改用 skills;要跨团队分发则打包成 plugin。截至 2026-07-17。OpenAI Codex Docs · Build skills — skills build on the open agent skills standard (agentskills.io): a directory plus a SKILL.md (must include name and description) plus optional scripts / references. Progressive disclosure: Codex starts with only each skill's name, description, and path (the initial list uses at most 2% of context or 8,000 characters), and reads a skill's full SKILL.md only when it decides to use it. Triggers: $name explicit mention or /skills, or implicit matching by description. Locations span repo .agents/skills, user ~/.agents/skills, admin, and system-bundled. Old custom prompts are deprecated in favor of skills; to distribute across a team, package as a plugin. As of 2026-07-17.位置分层,和记忆、配置一样:仓库里的 .agents/skills 随版本库共享,用户级 ~/.agents/skills 跟着你走。4注 4Note 4OpenAI Codex 文档 · Build skills —— 技能建立在开放的 agent skills 标准(agentskills.io)上:一个目录加一份 SKILL.md(必含 name 与 description)加可选脚本 / 参考。progressive disclosure:Codex 先只拿每个技能的名字、描述、路径(初始清单至多占 2% 上下文或 8000 字符),决定用某个技能时才读它完整的 SKILL.md。触发:$名字 显式提及或 /skills,或按描述隐式匹配。位置分仓库 .agents/skills、用户 ~/.agents/skills、admin、系统内置。旧的自定义 prompts 已弃用,改用 skills;要跨团队分发则打包成 plugin。截至 2026-07-17。OpenAI Codex Docs · Build skills — skills build on the open agent skills standard (agentskills.io): a directory plus a SKILL.md (must include name and description) plus optional scripts / references. Progressive disclosure: Codex starts with only each skill's name, description, and path (the initial list uses at most 2% of context or 8,000 characters), and reads a skill's full SKILL.md only when it decides to use it. Triggers: $name explicit mention or /skills, or implicit matching by description. Locations span repo .agents/skills, user ~/.agents/skills, admin, and system-bundled. Old custom prompts are deprecated in favor of skills; to distribute across a team, package as a plugin. As of 2026-07-17.如果你记得旧的「自定义 prompts」:已经弃用,一律改用 skills;要跨团队分发,再往上打包成 plugin。4注 4Note 4OpenAI Codex 文档 · Build skills —— 技能建立在开放的 agent skills 标准(agentskills.io)上:一个目录加一份 SKILL.md(必含 name 与 description)加可选脚本 / 参考。progressive disclosure:Codex 先只拿每个技能的名字、描述、路径(初始清单至多占 2% 上下文或 8000 字符),决定用某个技能时才读它完整的 SKILL.md。触发:$名字 显式提及或 /skills,或按描述隐式匹配。位置分仓库 .agents/skills、用户 ~/.agents/skills、admin、系统内置。旧的自定义 prompts 已弃用,改用 skills;要跨团队分发则打包成 plugin。截至 2026-07-17。OpenAI Codex Docs · Build skills — skills build on the open agent skills standard (agentskills.io): a directory plus a SKILL.md (must include name and description) plus optional scripts / references. Progressive disclosure: Codex starts with only each skill's name, description, and path (the initial list uses at most 2% of context or 8,000 characters), and reads a skill's full SKILL.md only when it decides to use it. Triggers: $name explicit mention or /skills, or implicit matching by description. Locations span repo .agents/skills, user ~/.agents/skills, admin, and system-bundled. Old custom prompts are deprecated in favor of skills; to distribute across a team, package as a plugin. As of 2026-07-17.Once saved, two entrances: type $name to summon it explicitly, or Codex loads it implicitly when it judges the task relevant by description — so the description must say clearly 'when to use me.'4注 4Note 4OpenAI Codex 文档 · Build skills —— 技能建立在开放的 agent skills 标准(agentskills.io)上:一个目录加一份 SKILL.md(必含 name 与 description)加可选脚本 / 参考。progressive disclosure:Codex 先只拿每个技能的名字、描述、路径(初始清单至多占 2% 上下文或 8000 字符),决定用某个技能时才读它完整的 SKILL.md。触发:$名字 显式提及或 /skills,或按描述隐式匹配。位置分仓库 .agents/skills、用户 ~/.agents/skills、admin、系统内置。旧的自定义 prompts 已弃用,改用 skills;要跨团队分发则打包成 plugin。截至 2026-07-17。OpenAI Codex Docs · Build skills — skills build on the open agent skills standard (agentskills.io): a directory plus a SKILL.md (must include name and description) plus optional scripts / references. Progressive disclosure: Codex starts with only each skill's name, description, and path (the initial list uses at most 2% of context or 8,000 characters), and reads a skill's full SKILL.md only when it decides to use it. Triggers: $name explicit mention or /skills, or implicit matching by description. Locations span repo .agents/skills, user ~/.agents/skills, admin, and system-bundled. Old custom prompts are deprecated in favor of skills; to distribute across a team, package as a plugin. As of 2026-07-17. Locations layer, like memory and config: a repo's .agents/skills is shared via version control, and the user-level ~/.agents/skills follows you.4注 4Note 4OpenAI Codex 文档 · Build skills —— 技能建立在开放的 agent skills 标准(agentskills.io)上:一个目录加一份 SKILL.md(必含 name 与 description)加可选脚本 / 参考。progressive disclosure:Codex 先只拿每个技能的名字、描述、路径(初始清单至多占 2% 上下文或 8000 字符),决定用某个技能时才读它完整的 SKILL.md。触发:$名字 显式提及或 /skills,或按描述隐式匹配。位置分仓库 .agents/skills、用户 ~/.agents/skills、admin、系统内置。旧的自定义 prompts 已弃用,改用 skills;要跨团队分发则打包成 plugin。截至 2026-07-17。OpenAI Codex Docs · Build skills — skills build on the open agent skills standard (agentskills.io): a directory plus a SKILL.md (must include name and description) plus optional scripts / references. Progressive disclosure: Codex starts with only each skill's name, description, and path (the initial list uses at most 2% of context or 8,000 characters), and reads a skill's full SKILL.md only when it decides to use it. Triggers: $name explicit mention or /skills, or implicit matching by description. Locations span repo .agents/skills, user ~/.agents/skills, admin, and system-bundled. Old custom prompts are deprecated in favor of skills; to distribute across a team, package as a plugin. As of 2026-07-17. If you remember old 'custom prompts': they're deprecated in favor of skills; to distribute across a team, package a level up into a plugin.4注 4Note 4OpenAI Codex 文档 · Build skills —— 技能建立在开放的 agent skills 标准(agentskills.io)上:一个目录加一份 SKILL.md(必含 name 与 description)加可选脚本 / 参考。progressive disclosure:Codex 先只拿每个技能的名字、描述、路径(初始清单至多占 2% 上下文或 8000 字符),决定用某个技能时才读它完整的 SKILL.md。触发:$名字 显式提及或 /skills,或按描述隐式匹配。位置分仓库 .agents/skills、用户 ~/.agents/skills、admin、系统内置。旧的自定义 prompts 已弃用,改用 skills;要跨团队分发则打包成 plugin。截至 2026-07-17。OpenAI Codex Docs · Build skills — skills build on the open agent skills standard (agentskills.io): a directory plus a SKILL.md (must include name and description) plus optional scripts / references. Progressive disclosure: Codex starts with only each skill's name, description, and path (the initial list uses at most 2% of context or 8,000 characters), and reads a skill's full SKILL.md only when it decides to use it. Triggers: $name explicit mention or /skills, or implicit matching by description. Locations span repo .agents/skills, user ~/.agents/skills, admin, and system-bundled. Old custom prompts are deprecated in favor of skills; to distribute across a team, package as a plugin. As of 2026-07-17.动手 · 给一个真项目铺三层交代:Hands-on · lay three layers of briefing on a real project:
01
跑 /init,再手动删到「短而准」Run /init, then hand-trim to 'short and accurate'
让它生成起草稿,然后逐行问「删掉这行它会不会犯错」—— 不会就删。顺手加一段 Review guidelines,给第 9 章用。Have it generate a draft, then ask line by line 'would removing this cause a mistake' — if not, cut it. Add a Review guidelines section for chapter 9 while you're there.
02
把一个反复设的默认写进 config.tomlWrite one repeatedly-set default into config.toml
模型、沙箱档、思考力度,挑你每次都要调的那个,定死在 ~/.codex/config.toml。之后切到编辑器确认它也生效 —— 一台引擎。Model, sandbox setting, reasoning effort — pick the one you tune every time and fix it in ~/.codex/config.toml. Then switch to the editor to confirm it holds there too — one engine.
03
把重复第三次的流程存成第一个 skillSave your thrice-repeated procedure as a first skill
找一套你这周贴过两遍的多步流程,放进 .agents/skills/<名字>/SKILL.md,描述写清触发时机。下次 $名字 唤起。Find a multi-step procedure you pasted twice this week, put it in .agents/skills/<name>/SKILL.md, and write the trigger into the description. Summon it with $name next time.
事实进 AGENTS.md,默认进 config,
流程沉成一个词.
Facts into AGENTS.md, defaults into config,
a procedure into one word.
Aklman Library
— 讨论Discussion
讨论Discussion.
评论区初始化中…Initializing comments…
01 / 01
没有匹配结果No matches.
换个关键词，或按 Esc 回到页面Try another keyword, or press Esc to return