Codex Rules 与 Skills：项目级和全局级配置一览
本文速览
一句话总结：
本文主要讲清楚 Codex Skill、AGENTS.md 与 Rules 的职责差异，以及它们在项目级和全局级的存放位置、加载方式与文件组织结构，帮助你更清晰地配置和使用 Codex。
适合人群：
适合正在使用 Codex、准备为项目编写 Skill 或规则配置，以及容易混淆项目级与全局级配置位置的开发者阅读。
核心问题：
- Skill 的项目级与全局级存放位置有什么区别？
- Codex 如何发现、匹配和加载一个 Skill？
AGENTS.md与.rules分别负责什么？- 项目级和全局级 Codex 文件应该如何组织？
你将学会：
- 理解 Skill、
AGENTS.md与 Rules 各自解决的问题； - 掌握项目级和全局级 Skill 的目录位置与组织方式；
- 理解 Skill 的渐进式加载和显式、隐式触发方式；
- 看懂项目级和全局级 Codex 的完整文件结构。
相关关键词：
Codex、Skill、SKILL.md、AGENTS.md、Rules、项目级配置、全局级配置、渐进式加载、命令权限
一、Skill：告诉 Codex"某类任务具体怎么做"
Skill 是一个可复用的任务工作流，既可以像快捷指令一样显式调用，也可以由 Codex 根据任务内容自动触发。
1. 项目级 Skill
项目级 Skill 放在项目的 .agents/skills/ 目录下。例如：
objectivec
viewport-lab/
└── .agents/
└── skills/
└── deploy-dev-machine/
└── SKILL.md项目级 Skill 的基本规则如下：
- 每个 Skill 使用一个独立子目录。
- 每个 Skill 必须包含
SKILL.md。 scripts、references、assets都是可选资源。- Skill 可以提交到 Git，供这个项目的所有开发者使用。
提示：项目级 Skill 可以随 Git 提交，更适合沉淀团队共同使用的任务工作流。
2. Skill 的渐进式加载机制
Codex 不会一开始就读取所有 Skill 的全部文件，而是采用渐进式加载。
第一阶段：收集 Skill 摘要
Codex 首先扫描 Skills 目录，并收集每个 Skill 的 name、description 和路径，供后续匹配使用。
第二阶段：判断是否调用
Skill 有两种触发方式：
- 显式触发 ：用户直接输入
$deploy-dev-machine。 - 隐式触发 ：例如用户输入"帮我把 Viewport Lab 更新到公司开发机"，Codex 会将任务含义与 Skill 的
description进行匹配。
第三阶段：读取完整的 SKILL.md
确定使用某个 Skill 后，Codex 会读取该 Skill 的完整 SKILL.md。
第四阶段：按需加载配套资源
Skill 可以按照下面的方式组织：
objectivec
deploy-dev-machine/
├── SKILL.md
├── references/
│ └── deployment.md
├── scripts/
│ └── deploy.sh
└── assets/
└── env.example这些文件通常不会在发现 Skill 时被全部加载。因此，SKILL.md 应明确说明需要读取或使用哪些资源，例如：
部署前完整阅读
references/deployment.md。执行部署时优先运行
scripts/deploy.sh。
Codex 选择 Skill 后，会根据这些指令：
- 阅读需要的
references； - 运行或修改
scripts； - 复制或使用
assets。
注意 ：没有被 SKILL.md 引用的文件，Codex 不一定会主动读取。
3. 全局级 Skill
以 MacBook 为例，个人全局 Skill 官方推荐放在
~/.agents/skills/。全局级 Skill 和项目级 Skill 本质相同，主要区别是存放位置和生效范围。
例如：/Users/xuxiao/.agents/skills/
objectivec
/Users/xuxiao/.agents/
└── skills/
├── commit-staged-changes/
│ ├── SKILL.md
│ └── scripts/
│ └── validate-staged.sh
│
├── deploy-dev-machine/
│ ├── SKILL.md
│ ├── references/
│ │ └── deployment.md
│ └── scripts/
│ └── deploy.sh
│
└── frontend-review/
├── SKILL.md
├── references/
│ └── review-checklist.md
└── assets/
└── report-template.md重点：全局级 Skill 和项目级 Skill 的本质相同，主要区别是存放位置与生效范围。
二、Rules：项目规范与命令执行权限
Codex 项目中的长期约束主要分为两类：项目工作规范和命令执行规则。
在官方语义中，.rules 专指命令执行权限；AGENTS.md 更准确地说是"项目指令"或"项目规范"。
1. 项目级 Rules
项目工作规范：AGENTS.md
项目根目录以及子模块中都可以放置 AGENTS.md。Codex 修改项目或对应子模块时，会参考其中的规范。
命令执行规则：.codex/rules/
项目可以在 .codex/rules/ 中配置命令执行权限，用来控制 Codex"哪些命令能执行"。例如：
arduino
viewport-lab/
└── .codex/
└── rules/
└── default.rules
ini
prefix_rule(
pattern = ["pnpm", "typecheck"],
decision = "allow",
justification = "项目类型检查是安全的只读验证",
)
prefix_rule(
pattern = ["pnpm", "deploy:dev-machine"],
decision = "prompt",
justification = "部署会更新公司开发机，需要用户确认",
)
prefix_rule(
pattern = ["git", "push"],
decision = "prompt",
justification = "推送会修改远端仓库",
)
prefix_rule(
pattern = ["git", "reset", "--hard"],
decision = "forbidden",
justification = "可能清除未提交修改，禁止执行",
)Rules 包含三种决策：
allow：允许在沙箱外执行，不再询问。prompt：每次执行前询问。forbidden：直接禁止。
注意：
| 自定义 Rules 的用途比较窄，目前也不是很稳定。 如果没有特殊需求，没必要一开始就写。 |
|---|
需要进一步拆分时，可以按照用途组织多个 Rules 文件：
viewport-lab/
└── .codex/
└── rules/
├── git.rules
├── pnpm.rules
├── deployment.rules
└── destructive-commands.rules2. 全局级 Rules
全局级 Rules 对所有项目生效，与项目级 Rules 的主要区别是存放路径不同。
以 MacBook 为例：
javascript
~/.codex/
└── rules/
└── default.rules三、项目级 Codex 文件组织结构
下面是一个项目级 Codex 文件结构示例：
arduino
viewport-lab/
├── AGENTS.md
├── .agents/
│ └── skills/
│ └── deploy-dev-machine/
│ └── SKILL.md
├── .codex/
│ ├── config.toml
│ └── rules/
│ └── default.rules
└── local-doc/四、全局级 Codex 文件组织结构
bash
/Users/xuxiao/
├── .codex/
│ ├── AGENTS.md # 全局工作规范
│ ├── config.toml # 全局运行配置
│ ├── rules/ # 全局命令权限规则
│ └── skills/ # 内置、已安装、旧式 Skill
│
└── .agents/
└── skills/ # 推荐：自己维护的全局 Skill全局级与项目级的一个区别是 AGENTS.md 的位置：
- 全局级
AGENTS.md是"这个用户使用 Codex 时，所有项目都遵守的习惯"，因此放在 Codex 的个人配置目录。 - 项目级
AGENTS.md是"这个仓库的开发约定"，因此直接放在仓库根目录，方便随 Git 提交并分享给团队；Codex 也会从项目根目录开始发现它。
结论：
| Skill 用来定义"某类任务具体怎么做"，AGENTS.md 用来约束项目工作方式，Rules 用来控制命令执行权限。 项目级配置适合随仓库共享，全局级配置则面向当前用户的所有项目生效。 |
|---|