Mastering Codex: From AGENTS.md to Hooks – A Complete Guide

01 | AGENTS.md – How does Codex remember project rules?

When a team follows a fixed documentation convention—Chinese body text, a single top‑level heading, images stored in images/, and read‑only files in published/ —re‑stating these rules for every task is tedious and error‑prone. Codex solves this by loading an AGENTS.md file placed in the repository root, which acts as a project onboarding manual.

Creating AGENTS.md

Manually create an AGENTS.md file at the project root and write the team’s conventions, modification rules, and verification commands.

Or let Codex generate it: open the product-docs project with Cmd/Ctrl + O , then paste the following prompt:

请在当前项目根目录创建 AGENTS.md。
这是一个团队技术文档仓库。
所有正文使用中文，一篇文档只能有一个一级标题。
文件名使用小写英文和连字符，图片统一放在 `images/`。
`published/` 中的文档只读，不要直接修改。
完成修改后执行 `python3 scripts/check_docs.py` 检查标题和图片引用。

先只创建规则文件，不修改任何文档，也不执行检查命令。

Codex will output a generated AGENTS.md that you can review on the right‑hand side of the UI.

Loading rules

Codex reads the nearest AGENTS.md from the current working directory, merges rules from parent directories, and gives later files higher priority. Personal rules can be stored in ~/.codex/AGENTS.md for global preferences, while project‑specific rules live in the repository root.

02 | Skills – Where should specialized knowledge live?

Not every piece of knowledge is needed for every task. Release‑note generation, for example, is important only when preparing a new version. Codex’s Skills allow you to encapsulate such optional knowledge and load it on demand.

Creating a Skill

Codex provides a built‑in $skill-creator command. To create a release‑notes skill, run:

$skill-creator 为当前项目创建一个 release-notes Skill。

它用于根据指定的 Git Tag 到当前分支之间的真实改动生成发布说明。

先确认起始版本，再读取提交和改动文件。
过滤合并提交、纯格式调整和 CI 配置更新。
把内容分成新功能、问题修复和破坏性变更。
使用面向用户的语言，每一项都要能追溯到提交或文件证据。
只生成草稿，不创建 Tag，也不发布版本。

同时提供 Release Notes 模板和收集提交的脚本。

After creation, the skill appears under the “Skills” pane as release-notes. You can invoke it in a task with:

$release-notes 根据 v1.4.0 到当前分支之间的改动，生成 v1.5.0 的发布说明草稿。
不要创建 Tag，也不要发布 Release。

The minimal SKILL.md looks like:

---
name: release-notes

description: 准备版本发布说明时使用，根据指定 Git Tag 到当前分支之间的真实改动，生成可追溯的 Release Notes 草稿。
---

# Release Notes 流程

1. 确认用户给出的起始 Git Tag 存在
2. 运行 `scripts/collect-commits.sh <tag>` 收集提交和改动文件
3. 过滤合并提交、纯格式调整和 CI 配置更新
4. 按新功能、问题修复和破坏性变更分类
5. 使用面向用户的语言，不直接复制提交信息
6. 每一项标出可追溯的提交或文件证据
7. 按 `references/release-template.md` 生成草稿

只生成发布说明草稿，不创建 Tag，不调用发布接口。

03 | Subagents – How to turn a task into a small team?

When investigating a new logging platform, you may need to research product capabilities, Java integration, and migration risks simultaneously. A single main Agent would quickly overflow its context. Subagents let Codex split the work into independent threads, each handling a sub‑task in parallel.

Defining custom agents

请在当前项目创建三个只读的自定义 Agent。

capability_researcher 只负责调查查询、告警、权限和运维能力。
integration_researcher 只负责调查 Java、OpenTelemetry 和现有监控的接入成本。
migration_researcher 只负责调查旧查询、历史数据和迁移风险。

每个 Agent 都要区分官方资料、项目现状和自己的推断，并保留来源。

先只创建 `.codex/agents/` 下的配置文件，不开始调研。

After the agents are defined, launch a task that dispatches them:

评估当前项目是否适合采用候选日志平台。
请并行安排三个 Subagent：
1. capability_researcher 调查产品能力和限制
2. integration_researcher 调查 Java 接入方式和改造成本
3. migration_researcher 调查迁移步骤、数据风险和回退方案

等三路结果回来后合并去重，输出适用条件、主要风险和待确认问题。
只做调研，不修改当前项目。

Codex shows each Subagent’s activity in separate panels, allowing you to inspect their intermediate results before the main Agent aggregates the conclusions.

04 | MCP – How to connect external systems?

Codex can read and modify files inside the repository, but real‑world tasks often need data from cloud documents, issue trackers, databases, or CI systems. The Model Context Protocol (MCP) provides a uniform “plug‑in socket” that lets Codex discover and invoke external tools.

Installing an MCP tool (example: Google Drive)

In the Plugins pane, search for “Google Drive” and install it. After authorizing the Google account, create a test document named Codex MCP Demo with the following content:

项目：会员中心改版
上线时间：8 月 20 日
待办：
1. 确认新版页面文案
2. 补充登录异常监控
3. 完成上线前回归测试

Then run a Codex task with this prompt:

使用 Google Drive 工具查找名为「Codex MCP Demo」的文档。
读取文档内容，输出项目名称、上线时间和待办事项。
只读取和整理，不要修改或创建任何文件。

MCP lets Codex automatically select the appropriate tool, construct the required parameters, call the external service, and process the returned data—all without extra user commands.

05 | Hooks – How to run actions automatically?

While AGENTS.md and Skills describe what Codex should do, repetitive actions such as linting, testing, or security scanning are better handled automatically at specific lifecycle points. Hooks are configurable triggers that run custom handlers when a task reaches a predefined event.

Example: a Stop Hook that runs a document‑check script

请为当前项目创建一个 Stop Hook。
任务准备结束时，自动运行 `python3 scripts/check_docs.py`。
检查通过时正常结束任务。
检查失败时把摘要交给 Codex 继续处理。
请创建所需的 Hook 配置和 Handler，不修改现有文档。

The Hook configuration specifies three things: the lifecycle node (e.g., Stop), the condition under which it fires, and the handler command to execute. When the task reaches the Stop node, Codex invokes the handler, passes the working directory and event name via STDIN, and reacts based on the handler’s exit code or JSON output.

Conclusion

The five capabilities—AGENTS.md, Skills, Subagents, MCP, and Hooks—work together to make Codex a powerful, extensible AI‑assistant for software projects. AGENTS.md enforces consistent project rules, Skills encapsulate reusable knowledge, Subagents enable parallel investigation, MCP bridges external services, and Hooks automate routine actions at well‑defined points in the workflow.