AI 自由岛 · 学习中心
20 分钟入门更新于 2026-08-11

当天目标：用 AGENTS.md + Skill + Memories 把项目约定固化成文本，让 Codex 越用越懂你，而不是每次重新教。

为什么"教会它"是个工程问题，不是聊天问题 ​

Day 1 你写了 AGENTS.md 的骨架。今天把它做厚，再补两个大多数人忽略的机制：Skill（可复用的操作手册）和 Memories（它自己记的笔记）。

第一性原理还是那个：上下文质量 = 工具价值。你每多写一条约定，后面每次对话都少解释一遍，且不会因"你忘了说"而出错。

AGENTS.md：查找顺序与级联 ​

Codex 读 AGENTS.md 是级联的：

  1. 全局 ~/.codex/AGENTS.md——对所有项目生效。
  2. 仓库根 你的项目/AGENTS.md——对这个项目生效，覆盖全局同名约定。
  3. 子目录 你的项目/src/AGENTS.md——只对 src 下生效，最优先。

越靠近代码，优先级越高。所以"通用的放全局，项目特有的放仓库根，某模块特有的放子目录"。还有个 AGENTS.override.md：你想临时推翻某些约定（比如这次就想让它随便改 migrations），写在这里——它和同目录的 AGENTS.md 只取一个（override 优先），但仍会被更靠近当前目录的下层文件覆盖，不是"压过一切"。用完删掉。

长度有默认上限 project_doc_max_bytes（约 32KiB，可调高但别无限堆——太长它反而抓不住重点）。所以 AGENTS.md 写"约定"，不写"教程"。

上下文文件优先级地图

Skill：把重复操作打包成可复用手册 ​

Skill 是 Codex 的"操作手册"机制。四个作用域和对应的真实路径：

  • REPO：仓库内 .agents/skills/（从 cwd 向上扫到仓库根都能发现），团队共享，提交进 git 大家都能用。
  • USER：你个人的 $HOME/.agents/skills/，跨项目。
  • ADMIN：/etc/codex/skills/，机器/容器级，IT 管理用。
  • SYSTEM：Codex 内置（如 $skill-creator、$plan），不用管。

注意 USER 路径是 $HOME/.agents/skills，不是 ~/.codex/skills——这是最容易写错的地方。

建一个 Skill 有两条路：对话里输入 $skill-creator，它会分步问你——这个技能干嘛用、什么时机触发、要不要带脚本——然后自动生成目录和 SKILL.md；或手动建文件夹 + SKILL.md。桌面端在 Skills 面板里能看到已装技能、开关和来源，CLI 用 /skills 查看。SKILL.md 必须含 YAML frontmatter 的 name 和 description：

markdown
---
name: release-check
description: 检查版本号、变更记录、测试结果和 Git 状态，适用于准备发布或打标签前的核对。
---

# Release Check
按项目规范完成发布前检查：
1. 确认 package.json 版本号已 bump。
2. 确认 CHANGELOG 已更新。
3. 跑 `npm test`，必须全绿。
4. 跑 `git status`，确认没有遗漏的未提交改动。
  • 显式调用：CLI/IDE 里输入 $ 后跟技能名（如 $release-check），或运行 /skills 看可用技能。
  • 隐式调用：当你的任务描述和 description 匹配时，Codex 自动选它——所以 description 要写清"什么时候用、什么时候不用"，把关键触发词放前面。

坏例子：description: 处理发布相关的事 —— 太泛，Codex 分不清该不该触发，也容易和别的 Skill 撞。 好例子：description: 发布前核对——检查版本号、CHANGELOG、测试结果和 Git 状态；仅在准备打 tag 或发版前使用 —— 触发词（发布前/打 tag）和禁用场景都写清，匹配才准。

  • 同名 Skill 不合并，两个都会出现，靠 description 区分。

今天就真建一个并跑起来 ​

光懂机制不够，现在动手做出第一个能复用的 Skill：

  1. 在仓库里建文件 .agents/skills/release-check/SKILL.md，把上面的 frontmatter 和正文粘进去（REPO 作用域，提交进 git 团队都能用）。
  2. 回到 Codex 会话，输入 $release-check。它会读 SKILL.md，按四步执行：检查 package.json 版本、看 CHANGELOG、跑 npm test、看 git status。
  3. 盯它实际做了什么——它应该真的跑过 npm test 并贴结果，而不是嘴上说"已检查"。如果它没跑测试就报"通过"，说明 Skill 写歪了，回去改 description 或步骤。
  4. 想让它自动触发，就把 description 写成"发布前核对——检查版本号、CHANGELOG、测试结果和 Git 状态；仅在准备打 tag 或发版前使用"。下次你说"准备发 v1.2"，它自己会挑这个 Skill，不用你手动 $。

这一个 Skill，每周发版帮你省一次人工核对。

渐进式披露（这是 Skills 的机制，不是 MCP 的）：Codex 启动时只加载每个 Skill 的 name + description 进初始清单，预算约上下文 2% 或 8000 字符。选中后才读完整 SKILL.md。所以 description 写最关键的可检索词，别把重点埋在文件末尾。

关键坑（自我蒸馏）：OpenAI 团队成员曾分享过一招——把一段提示词丢给 Codex，它回看历史会话，把重复工作流自动打包成 Skill / Subagent / Automation。这条路听起来香，但有两个坑：

  1. 它只看"重复"，不看"对不对"。Skill 没触发、机制没转的断点被忽略。
  2. 自动生成的 Skill，一半来自"输入还没稳定时就做过两次的事"——这种 Skill 维护比重写还贵。

所以自动蒸馏出的 Skill 必须人工把关：过一遍，删掉没稳定下来的，只留真能复用的。

Memories：让它自己记笔记 ​

Memories 是 Codex 在协作中自己沉淀的笔记（你踩过的坑、项目的特殊约定），默认就是开启的（配置项 memories.generate_memories 默认为 true），下次会话会自动读进来。用 /memories 可以看它记了什么。

用法：跑完一段复杂任务，它通常会自己沉淀关键约定；你也可以明确让它"把这次的关键约定记进 Memories"。定期清理过时的 Memories，别让它记了一堆过期规则反过来误导你。存储路径因版本而异（可用 /memories 查看），别手改那个目录，让 Codex 自己管。

三个锦囊 ​

  1. AGENTS.md 今天补到"项目特有约定"层，仓库根那份写满 Build/run/Conventions/Constraints，别只留骨架。
  2. 第一个 Skill 今天就建：挑一个你每周都做的重复操作（发版、生成变更日志），用 $skill-creator 或手写一个 REPO/USER 作用域的 Skill。记得 name/description frontmatter。
  3. 自动蒸馏的 Skill 人工过一遍再留，别让"重复两次"就变成永久负担；Memories 定期清过期。

自测标尺（用命令/文件验证） ​

  • [ ] 你能说清 AGENTS.md 三级级联顺序和 AGENTS.override.md 的真实行为（同目录只取一个，不压过更靠近 cwd 的）。
  • [ ] 你建了至少一个真实 Skill，且 SKILL.md 有 name/description，你知道它属于哪个作用域、存在哪个路径（$HOME/.agents/skills/ 或 .agents/skills/）。
  • [ ] 你用过 $skill-name 或 /skills 触发过它；知道 description 决定隐式匹配。
  • [ ] 你理解"自我蒸馏"的两个坑，知道自动生成的 Skill 要人工把关；会用 /memories 看记忆。

效率日志 ​

任务手动做要几分钟Codex 做+你验收几分钟打回几次
建第一个 Skill + 写 AGENTS.md 项目层_________
本页目录 ✕