文章目录Codex Rules 与 Skills项目级和全局级配置一览一、Skill告诉 Codex“某类任务具体怎么做”1. 项目级 Skill2. Skill 的渐进式加载机制第一阶段收集 Skill 摘要第二阶段判断是否调用第三阶段读取完整的 SKILL.md第四阶段按需加载配套资源3. 全局级 Skill二、Rules项目规范与命令执行权限1. 项目级 Rules项目工作规范AGENTS.md命令执行规则.codex/rules/2. 全局级 Rules三、项目级 Codex 文件组织结构四、全局级 Codex 文件组织结构Codex Rules 与 Skills项目级和全局级配置一览本文速览一句话总结本文主要讲清楚 Codex Skill、AGENTS.md 与 Rules 的职责差异以及它们在项目级和全局级的存放位置、加载方式与文件组织结构帮助你更清晰地配置和使用 Codex。适合人群适合正在使用 Codex、准备为项目编写 Skill 或规则配置以及容易混淆项目级与全局级配置位置的开发者阅读。核心问题Skill 的项目级与全局级存放位置有什么区别Codex 如何发现、匹配和加载一个 SkillAGENTS.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/目录下。例如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 摘要匹配 description读取 SKILL.md按需加载资源references / scripts / assets执行工作流第一阶段收集 Skill 摘要Codex 首先扫描 Skills 目录并收集每个 Skill 的name、description和路径供后续匹配使用。第二阶段判断是否调用Skill 有两种触发方式显式触发用户直接输入$deploy-dev-machine。隐式触发例如用户输入“帮我把 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 的本质相同主要区别是存放位置与生效范围。二、Rules项目规范与命令执行权限Codex 项目中的长期约束主要分为两类项目工作规范和命令执行规则。在官方语义中.rules专指命令执行权限AGENTS.md更准确地说是“项目指令”或“项目规范”。Skill定义任务怎么做AGENTS.md定义工作规范Rules控制命令权限生效范围项目级全局级1. 项目级 Rules项目工作规范AGENTS.md项目根目录以及子模块中都可以放置AGENTS.md。Codex 修改项目或对应子模块时会参考其中的规范。命令执行规则.codex/rules/项目可以在.codex/rules/中配置命令执行权限用来控制 Codex“哪些命令能执行”。例如viewport-lab/ └── .codex/ └── rules/ └── default.rulesprefix_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 为例~/.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 用来控制命令执行权限。项目级配置适合随仓库共享全局级配置则面向当前用户的所有项目生效。