交代 · 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.
同一句话你跟它说了十遍:测试跑这条命令、别碰那个目录、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. Don't bet on a new chat carrying yesterday's briefing back by itself — anything that must apply gets written 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 赢」概括嵌套规则;具体发现方式由各 agent 实现,Codex 本地运行按项目根到当前工作目录加载,GitHub review 才按 changed file 找最近文件。截至 2026-08-05。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 standard site summarizes nesting as 'the closest AGENTS.md to the edited file wins,' but discovery is implementation-specific: local Codex loads from project root to current working directory, while GitHub review resolves the closest file per changed file. As of 2026-08-05.这意味着你为 Codex 写的这份交代,换个工具照样管用 —— 你投的时间不绑死在一家。但「最近的赢」要看具体实现:Codex 本地会话按项目根到当前工作目录加载一条链;GitHub review 才针对每个 changed file 找最近的 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-08-05。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-08-05.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 赢」概括嵌套规则;具体发现方式由各 agent 实现,Codex 本地运行按项目根到当前工作目录加载,GitHub review 才按 changed file 找最近文件。截至 2026-08-05。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 standard site summarizes nesting as 'the closest AGENTS.md to the edited file wins,' but discovery is implementation-specific: local Codex loads from project root to current working directory, while GitHub review resolves the closest file per changed file. As of 2026-08-05. Which means the briefing you write for Codex still works if you switch tools — your time isn't locked to one vendor. But 'closest wins' depends on the implementation: a local Codex chat loads one chain from project root to the current working directory; GitHub review resolves the closest AGENTS.md for each changed file.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-08-05。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-08-05.Codex 动手前先读它,发现链是分层叠加的:全局的 ~/.codex/AGENTS.md 打底,然后从项目根往你启动 Codex 的当前目录逐层走,每个目录取一个文件、从根往下拼 —— 越靠近当前目录,越晚出现、覆盖越前面的。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-08-05。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-08-05.所以 monorepo 里根目录放全仓通用规矩,子服务放特殊规矩后,要从那个子服务目录启动 Codex,它才会进入那条链;别假设会话会按每个被改文件临时换规则。起步不用手写:CLI 里 /init 生成一份起草稿。6注 6Note 6OpenAI Codex 文档 · Best practices —— 一旦某个 prompt 模式好用,就用 AGENTS.md 固化它。CLI 里 /init 是脚手架命令,生成一份起步 AGENTS.md,再照你团队实际的构建 / 测试 / 审查 / 发布方式改。官方判断:短而准的 AGENTS.md 胜过又长又空的;「当 Codex 同一个错犯第二次,让它做个复盘并更新 AGENTS.md」;文件太大就让主文件精简、把计划 / 代码审查 / 架构等拆成任务专用的 markdown 文件来引用。截至 2026-08-05。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-08-05.Codex reads it before doing any work, and discovery layers: the global ~/.codex/AGENTS.md underneath, then from project root down to the current directory where you started Codex, one file per directory, concatenated root-down — the closer to the current directory, 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-08-05。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-08-05. So in a monorepo, after putting repo-wide rules at root and special rules under a service, start Codex from that service directory to enter that chain; don't assume the chat swaps rules dynamically for every edited file. 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-08-05。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-08-05.
一份短而准的项目交代 —— 只写它猜不到的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-08-05。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-08-05.什么时候加一行?一条好用的触发律:Codex 同一个错犯第二次,就让它做个复盘、把教训写进 AGENTS.md。6注 6Note 6OpenAI Codex 文档 · Best practices —— 一旦某个 prompt 模式好用,就用 AGENTS.md 固化它。CLI 里 /init 是脚手架命令,生成一份起步 AGENTS.md,再照你团队实际的构建 / 测试 / 审查 / 发布方式改。官方判断:短而准的 AGENTS.md 胜过又长又空的;「当 Codex 同一个错犯第二次,让它做个复盘并更新 AGENTS.md」;文件太大就让主文件精简、把计划 / 代码审查 / 架构等拆成任务专用的 markdown 文件来引用。截至 2026-08-05。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-08-05.文件长到臃肿就拆 —— 主文件保持精简,专门的细则放进子目录里更近的文件。上面那段 Review guidelines 不是摆设:第 10 章 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-08-05。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-08-05. 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-08-05。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-08-05. 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 10'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] 开关。同一台机器上的 CLI、IDE 扩展与 ChatGPT 桌面应用共用本地配置;cloud / GitHub 不读取这份用户文件。截至 2026-08-05。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 (closer to the current working directory wins) > profile files > user config > system config > built-in defaults. Commonly changed: model, approval_policy, sandbox_mode, model_reasoning_effort, personality, [features] flags. On the same host, the CLI, IDE extension, and ChatGPT desktop app share local configuration; cloud / GitHub don't read that user file. As of 2026-08-05.个人默认放 ~/.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] 开关。同一台机器上的 CLI、IDE 扩展与 ChatGPT 桌面应用共用本地配置;cloud / GitHub 不读取这份用户文件。截至 2026-08-05。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 (closer to the current working directory wins) > profile files > user config > system config > built-in defaults. Commonly changed: model, approval_policy, sandbox_mode, model_reasoning_effort, personality, [features] flags. On the same host, the CLI, IDE extension, and ChatGPT desktop app share local configuration; cloud / GitHub don't read that user file. As of 2026-08-05.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] 开关。同一台机器上的 CLI、IDE 扩展与 ChatGPT 桌面应用共用本地配置;cloud / GitHub 不读取这份用户文件。截至 2026-08-05。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 (closer to the current working directory wins) > profile files > user config > system config > built-in defaults. Commonly changed: model, approval_policy, sandbox_mode, model_reasoning_effort, personality, [features] flags. On the same host, the CLI, IDE extension, and ChatGPT desktop app share local configuration; cloud / GitHub don't read that user file. As of 2026-08-05. 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] 开关。同一台机器上的 CLI、IDE 扩展与 ChatGPT 桌面应用共用本地配置;cloud / GitHub 不读取这份用户文件。截至 2026-08-05。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 (closer to the current working directory wins) > profile files > user config > system config > built-in defaults. Commonly changed: model, approval_policy, sandbox_mode, model_reasoning_effort, personality, [features] flags. On the same host, the CLI, IDE extension, and ChatGPT desktop app share local configuration; cloud / GitHub don't read that user file. As of 2026-08-05.和第 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] 开关。同一台机器上的 CLI、IDE 扩展与 ChatGPT 桌面应用共用本地配置;cloud / GitHub 不读取这份用户文件。截至 2026-08-05。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 (closer to the current working directory wins) > profile files > user config > system config > built-in defaults. Commonly changed: model, approval_policy, sandbox_mode, model_reasoning_effort, personality, [features] flags. On the same host, the CLI, IDE extension, and ChatGPT desktop app share local configuration; cloud / GitHub don't read that user file. As of 2026-08-05.所以调它是一次性投资;但别把这句话外推到云端 / GitHub。也别把该长期钉住的默认反复在命令行里临时传 —— 标志留给一次性例外,持久偏好写进 config。Echoing chapter 2's boundary: the CLI, IDE extension, and desktop app on the same host share local configuration — the model and sandbox setting you fix in config.toml benefit all three local clients.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] 开关。同一台机器上的 CLI、IDE 扩展与 ChatGPT 桌面应用共用本地配置;cloud / GitHub 不读取这份用户文件。截至 2026-08-05。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 (closer to the current working directory wins) > profile files > user config > system config > built-in defaults. Commonly changed: model, approval_policy, sandbox_mode, model_reasoning_effort, personality, [features] flags. On the same host, the CLI, IDE extension, and ChatGPT desktop app share local configuration; cloud / GitHub don't read that user file. As of 2026-08-05. Tuning it is a one-time investment, but don't extend that sentence to cloud / GitHub. Nor 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-08-05。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-08-05.它建立在开放的 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-08-05。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-08-05.一份几百行的发版手册,平时几乎不占地方。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-08-05。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-08-05. 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-08-05。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-08-05. 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-08-05。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-08-05.位置分层,和记忆、配置一样:仓库里的 .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-08-05。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-08-05.如果你记得旧的「自定义 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-08-05。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-08-05.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-08-05。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-08-05. 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-08-05。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-08-05. 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-08-05。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-08-05.动手 · 给一个真项目铺三层交代:Hands-on · lay three layers of briefing on a real project:
01
跑 /init,再手动删到「短而准」Run /init, then hand-trim to 'short and accurate'
让它生成起草稿,然后逐行问「删掉这行它会不会犯错」—— 不会就删。顺手加一段 Review guidelines,给第 10 章用。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 10 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 confirm it in the same-host editor or desktop app; remember that cloud doesn't read this file.
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
