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.rules

2. 全局级 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 用来控制命令执行权限。项目级配置适合随仓库共享，全局级配置则面向当前用户的所有项目生效。

Codex Rules 与 Skills：项目级和全局级配置一览