前言

适合人群：

这篇文章适合以下读者：正在使用 Codex，准备给项目编写 Skill 或规则配置，或者经常分不清项目级和全局级配置应该放在哪里的人。

核心问题：

• Skill 的项目级与全局级存放位置，到底有什么区别？
• Codex 是怎么发现、匹配并加载一个 Skill 的？
• AGENTS.md 和 .rules 各自负责什么？
• 项目级和全局级的 Codex 文件，该怎么组织才算合理？

你会学到什么：

• 搞清楚 Skill、AGENTS.md 和 Rules 各自解决什么问题；
• 掌握项目级和全局级 Skill 的目录位置与组织方式；
• 理解 Skill 的渐进式加载机制，以及显式、隐式触发方式；
• 看懂项目级和全局级 Codex 的完整文件结构。

一、Skill：告诉 Codex“某类任务具体怎么做”

Skill 本质上是一套可复用的任务工作流。

你可以把它理解成某种快捷指令。需要时直接调用名字即可。即使你不主动说出名字，Codex 也可能根据任务内容自动匹配并触发。

1. 项目级 Skill

项目级 Skill 跟着项目走，放在项目的 .agents/skills/ 目录下。例如：

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，明确告诉 Codex 要使用这个 Skill。
• 隐式触发：用户说“帮我把 Viewport Lab 更新到公司开发机”，Codex 会分析任务含义，再去匹配 Skill 的 description。

第三阶段：读取完整的 SKILL.md

只有在确定使用某个 Skill 后，Codex 才会读取该 Skill 的完整 SKILL.md。

第四阶段：按需加载配套资源

Skill 可以按下面的方式组织：

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/

/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 本质相同，区别只在存放位置与生效范围。

• 项目级 Skill：对当前项目生效。
• 全局级 Skill：对当前用户的所有项目生效。

二、Rules：项目规范与命令执行权限

Codex 项目中的长期约束，主要分为两类：

• 项目工作规范
• 命令执行规则

在官方语义里，.rules 专指命令执行权限；而 AGENTS.md 更准确地说是“项目指令”或“项目规范”。

1. 项目级 Rules

项目工作规范：AGENTS.md

项目根目录以及子模块中都可以放 AGENTS.md。Codex 在修改项目或对应子模块时，会参考其中的规范做决定。

命令执行规则：.codex/rules/

项目可以在 .codex/rules/ 中配置命令执行权限，用来控制 Codex“哪些命令能执行”。例如：

viewport-lab/
└── .codex/
└── rules/
└── default.rules

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 为例：

~/.codex/
└── rules/
└── default.rules

三、项目级 Codex 文件组织结构

下面是一个项目级 Codex 文件结构的完整示例：

viewport-lab/
├── AGENTS.md
├── .agents/
│ └── skills/
│ └── deploy-dev-machine/
│ └── SKILL.md
├── .codex/
│ ├── config.toml
│ └── rules/
│ └── default.rules
└── local-doc/

四、全局级 Codex 文件组织结构

/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 用来控制命令执行权限。

项目级配置 适合随仓库共享，全局级配置 则面向当前用户的所有项目生效。