Codex Rules与Skills是什么?项目级和全局级Skill配置一览

前言

适合人群：

适合正在使用 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。
• 隐式触发：例如用户输入“帮我把 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 更准确地说是“项目指令”或“项目规范”。

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

到此这篇关于Codex Rules与Skills是什么?项目级和全局级Skill配置一览的文章就介绍到这了,更多相关Codex Rules与Skills介绍内容请搜索脚本之家以前的文章或继续浏览下面的相关文章，希望大家以后多多支持脚本之家！

最新评论