三大编程智能体的RULES和SKILLS规范！

甲维斯
303 阅读8分钟

RULES 和 SKILL 是编程智能体的两个重要概念，用好了可以大幅节省 tokens 和时间，关键是可以大幅提升效率，降低出错的概率。

目前几乎所有的主流编程工具，比如 Claude Code 和 Codex 都已经支持 Rules 和 Skills。

但是，各家的命名和规范五花八门。

Rules 这里主要用来表达项目规范，或者说项目上下文。在 Claude Code 一般叫 CLAUDE.md，在 Codex 中叫 AGENTS.md。

Skills 虽然基本的规则相同，但是不同智能体中放置的路径是完全不同的。

如果你同时用很多编程工具，很容易搞混。项目一多完全就搞不清楚，哪些规则哪些技能在哪些项目里有效了。

我今天就做一个汇总，方便自己，也方便大家。

接下来我会汇总了 Claude Code、OpenAI Codex CLI、Gemini CLI 三大终端智能体的规则（Rules）和技能（Skills）文件的命名及存放路径。

〇、Agent Skills 开放标准

官方网站：agentskills.io

规范文档：agentskills.io/specificati…

Agent Skills 是一个开放标准格式，由 Anthropic 发起并维护，用于给 AI 代理添加新能力和专业知识。该标准已被多个平台采用，包括 Claude Code、OpenAI Codex CLI、Gemini CLI、Cursor、VS Code、GitHub Copilot 等。

核心规范

目录结构：

skill-name/
├── SKILL.md           # 必需：指令和元数据
├── scripts/           # 可选：可执行脚本
├── references/        # 可选：参考文档
└── assets/            # 可选：模板和资源

SKILL.md 格式（YAML frontmatter + Markdown）：

---
name: skill-name                    # 必需：1-64字符，小写字母、数字、连字符
description: 技能描述和使用场景      # 必需：1-1024字符
license: Apache-2.0                 # 可选：许可证
compatibility: Requires git, docker # 可选：环境要求
allowed-tools: Bash(git:*) Read     # 可选：预授权工具（实验性）
metadata:                           # 可选：自定义元数据
  author: example-org
  version: "1.0"
---
​
技能指令内容...

Frontmatter 字段规范

字段必需约束
name是最多64字符，仅小写字母、数字、连字符，不能以连字符开头或结尾
description是最多1024字符，描述技能功能和使用场景
license否许可证名称或引用
compatibility否最多500字符，环境要求说明
metadata否任意键值对，用于额外元数据
allowed-tools否空格分隔的预授权工具列表（实验性）

渐进式披露（Progressive Disclosure）

技能采用三层加载策略以优化上下文使用：

  1. 元数据（~100 tokens）：启动时仅加载 name 和 description
  2. 指令（建议 <5000 tokens）：激活时加载完整 SKILL.md 内容
  3. 资源（按需）：scripts/、references/、assets/ 仅在需要时加载

一、Claude Code

官方文档：

code.claude.com/docs/en/set…

code.claude.com/docs/en/ski…

1. Rules 文件

Claude Code 中的规则文件叫 CLAUDE.md，用于向 Claude 提供指令、上下文和项目约定。

级别路径说明
用户级（全局）~/.claude/CLAUDE.md适用于所有项目的个人指令
项目级<project-root>/CLAUDE.md团队共享的项目指令（建议提交到 Git）
项目级（子目录）<project-root>/.claude/CLAUDE.md放在 .claude 子目录中的替代方案
本地覆盖<project-root>/CLAUDE.local.md个人项目偏好（应加入 .gitignore）
嵌套目录<subdir>/CLAUDE.md子目录特定指令，处理该目录文件时自动加载

加载顺序：从全局到本地逐层叠加，更具体的层级在冲突时覆盖上层。

2. Skills文件

技能是可扩展的指令集，可通过 /skill-name 调用。Claude Code 遵循 Agent Skills 开放标准，并扩展了额外功能。

级别路径说明
用户级~/.claude/skills/<skill-name>/SKILL.md适用于所有项目
项目级<project-root>/.claude/skills/<skill-name>/SKILL.md仅限当前项目
插件级<plugin>/skills/<skill-name>/SKILL.md插件提供的技能
企业级托管设置中配置组织范围内强制

技能目录结构：

my-skill/
├── SKILL.md           # 主指令文件（必需）
├── template.md        # 模板文件（可选）
├── examples/          # 示例目录（可选）
├── references/        # 参考文档（可选）
├── assets/            # 资源文件（可选）
└── scripts/           # 脚本目录（可选）

SKILL.md 格式：

---
name: my-skill
description: 技能描述，Claude 用于判断何时使用
argument-hint: "[filename] [format]"  # 自动补全提示
disable-model-invocation: false       # true 则仅用户可调用
user-invocable: true                  # false 则不显示在 / 菜单
allowed-tools: Read, Grep             # 限制可用工具
model: sonnet                         # 指定使用的模型
context: fork                         # 在独立子代理中运行
agent: Explore                        # 子代理类型
hooks:                                # 技能生命周期钩子
  pre-invoke: "./scripts/setup.sh"
---
​
技能指令内容...
​
支持变量替换：
- $ARGUMENTS：调用时传入的参数
- ${CLAUDE_SESSION_ID}：当前会话 ID

调用方式：

  • 用户调用：/skill-name [arguments]
  • 模型自动调用：根据 description 匹配任务

二、OpenAI Codex CLI

官方文档：

developers.openai.com/codex/guide…

developers.openai.com/codex/skill…

1. Rules 文件

Codex 的规则文件叫 AGENTS.md，AGENTS.md 是一个开放标准格式，用于指导编码代理。这个名字还是非常标准的。

级别路径说明
用户级（全局）~/.codex/AGENTS.md全局默认指令
用户级覆盖~/.codex/AGENTS.override.md临时全局覆盖（优先级更高）
项目级<git-root>/AGENTS.md项目根目录指令
项目级覆盖<git-root>/AGENTS.override.md项目临时覆盖
子目录级<subdir>/AGENTS.md子目录特定指令（离当前目录越近优先级越高）

加载顺序：

  1. 首先检查 ~/.codex/（先查 .override.md，再查 .md）
  2. 从项目根目录逐层向下到当前目录，每层只取一个文件
  3. 文件从根向下拼接，越靠近当前目录的优先级越高

配置选项（在 ~/.codex/config.toml 中）：

project_doc_max_bytes = 32768                           # 最大读取字节数
project_doc_fallback_filenames = ["TEAM_GUIDE.md"]      # 备选文件名

2. Skills 文件

Codex CLI 于 2025 年 12 月正式支持 Agent Skills 规范。技能是可复用的指令包，包含可选的脚本和资源。

级别路径优先级
仓库级（当前目录）$CWD/.codex/skills/<skill-name>/最高
仓库级（嵌套目录）$CWD/../.codex/skills/<skill-name>/高
仓库级（仓库根）$REPO_ROOT/.codex/skills/<skill-name>/中
用户级~/.codex/skills/<skill-name>/低
管理员级/etc/codex/skills/<skill-name>/较低
系统级内置技能最低

技能目录结构：

my-skill/
├── SKILL.md           # 必需：指令和元数据
├── scripts/           # 可选：可执行脚本
├── references/        # 可选：参考文档
└── assets/            # 可选：模板和资源

SKILL.md 格式：

---
name: skill-name                           # 必需：最多100字符，单行
description: 帮助 Codex 选择技能的描述      # 必需：最多500字符，单行
metadata:                                  # 可选：额外元数据
  short-description: 用户界面显示的简短描述
  author: your-name
  version: "1.0"
---
​
技能指令内容...
​
Codex 将遵循这些指令完成任务。

调用方式：

  • 显式调用：输入 $skill-name（如 $skill-installer）
  • 隐式调用：Codex 根据任务描述自动选择匹配的技能

内置技能：

  • $skill-creator：创建新技能的引导工具
  • $skill-installer：安装策划或实验性技能
  • $create-plan：创建执行计划（实验性）

禁用技能（在 ~/.codex/config.toml 中）：

[[skills.config]]
path = "/path/to/skill"
enabled = false

技能工作原理：

  • Codex 仅将技能的 name、description 和文件路径注入运行时上下文
  • 完整指令内容仅在技能被显式或隐式调用时才加载
  • 支持符号链接的技能文件夹

3. Rules 权限文件（.rules）

用于控制沙箱外可执行的命令（实验性功能）。

级别路径
用户级~/.codex/rules/*.rules

文件格式（使用 Starlark 语法）：

prefix_rule(
    pattern = ["gh", "pr", ["view", "list"]],
    decision = "allow",  # allow / prompt / forbidden
    justification = "允许查看 GitHub PR"
)

三、Gemini CLI

官方文档：

geminicli.com/docs/cli/sk…

geminicli.com/docs/get-st…

1. Rules 文件

谷歌的规则文件叫 GEMINI.md，为 Gemini 模型提供指令上下文。

级别路径说明
用户级（全局）~/.gemini/GEMINI.md适用于所有项目的默认指令
项目级<project-root>/GEMINI.md项目根目录指令
祖先目录从当前目录向上到项目根（.git 标识）逐层搜索
子目录级<subdir>/GEMINI.md特定模块/组件的指令

加载顺序：全局 → 项目祖先目录（向上搜索）→ 子目录（向下扫描）

特性：

  • 支持 @file.md 语法导入其他文件
  • 文件名可通过 context.fileName 配置项自定义
  • /memory add <text> 命令可快速添加到全局 GEMINI.md

3. Skills 文件

Gemini CLI 支持 Agent Skills 开放标准（实验性功能，需手动启用）。与 Claude Code Skills 完全兼容。

启用方式：

  1. 交互式 UI：运行 /settings 并开启 "Agent Skills"

  2. 手动配置：在 ~/.gemini/settings.json 中添加：

    {
  "experimental": {
    "skills": true
  }
}
级别路径优先级
工作区级<project>/.gemini/skills/<skill-name>/SKILL.md最高
用户级~/.gemini/skills/<skill-name>/SKILL.md中
扩展级<extension>/skills/<skill-name>/SKILL.md最低

技能目录结构：

my-skill/
├── SKILL.md           # 必需：指令和元数据
├── scripts/           # 可选：可执行脚本
├── references/        # 可选：参考文档
└── assets/            # 可选：资源文件

SKILL.md 格式：

---
name: api-auditor                    # 必需：小写字母、数字、连字符
description: "API 端点审计专家。当用户要求 '检查'、'测试' 或 '审计' URL 或 API 时使用。"
---
​
技能指令内容...
​
代理将遵循这些指令完成任务。

激活流程（渐进式披露）：

  1. 发现：仅加载 name 和 description 到上下文
  2. 激活：Gemini 调用 activate_skill 工具，用户确认后加载完整指令
  3. 执行：技能目录被添加到允许的文件路径，可访问脚本和资源

管理命令：

  • /skills list：查看所有已发现的技能
  • /skills enable <name>：启用技能
  • /skills disable <name>：禁用技能
  • /skills reload：刷新技能发现

终端命令：

gemini skills install <path-or-url>   # 安装技能
gemini skills uninstall <name>        # 卸载技能
gemini skills enable <name> --scope user|workspace
gemini skills disable <name>

四、对比汇总表

Rules 文件对比

智能体文件名用户级路径项目级路径
Claude CodeCLAUDE.md~/.claude/CLAUDE.md<project>/CLAUDE.md
Codex CLIAGENTS.md~/.codex/AGENTS.md<project>/AGENTS.md
Gemini CLIGEMINI.md~/.gemini/GEMINI.md<project>/GEMINI.md

Skills 文件对比

智能体文件名用户级路径项目级路径状态
Claude CodeSKILL.md~/.claude/skills/<name>/.claude/skills/<name>/正式支持
Codex CLISKILL.md~/.codex/skills/<name>/.codex/skills/<name>/正式支持
Gemini CLISKILL.md~/.gemini/skills/<name>/.gemini/skills/<name>/实验性

SKILL.md Frontmatter 字段对比

字段Agent SkillsClaude CodeCodex CLIGemini CLI
name必需必需必需必需
description必需必需必需必需
license可选---
compatibility可选---
metadata可选-可选-
allowed-tools可选（实验性）可选--
disable-model-invocation-可选--
user-invocable-可选--
context-可选--
agent-可选--
argument-hint-可选--
model-可选--
hooks-可选--

五、技能复用

由于三者都支持 Agent Skills 开放标准，技能可以跨平台复用：

  1. 使用标准的目录结构（SKILL.md + 可选的 scripts/、references/、assets/）
  2. 仅使用标准字段（name、description）确保最大兼容性
  3. 平台特有字段（如 Claude Code 的 context: fork）会被其他平台忽略

有了这个文件之后，就可以很好的管理不同智能体的规则和技能了。当然也可以这些内容做成一个技能。需要创建和放置这些文件的时候，调用技能，输入平台，影响范围，就可以自动生成了。

avatar
文章
阅读
粉丝