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

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 开放标准

官方网站：https://agentskills.io

规范文档：https://agentskills.io/specification

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:Requiresgit,docker# 可选：环境要求allowed-tools:Bash(git:*)Read# 可选：预授权工具（实验性）metadata:# 可选：自定义元数据author:example-orgversion:"1.0"---技能指令内容...

Frontmatter 字段规范

渐进式披露（Progressive Disclosure）

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

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

一、Claude Code

官方文档：

https://code.claude.com/docs/en/settings

https://code.claude.com/docs/en/skills

1. Rules 文件

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

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

2. Skills文件

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

技能目录结构：

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

SKILL.md 格式：

---name:my-skilldescription:技能描述，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

官方文档：

https://developers.openai.com/codex/guides/agents-md

https://developers.openai.com/codex/skills/

1. Rules 文件

Codex 的规则文件叫 AGENTS.md，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 规范。技能是可复用的指令包，包含可选的脚本和资源。

技能目录结构：

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

SKILL.md 格式：

---name:skill-name# 必需：最多100字符，单行description:帮助Codex选择技能的描述# 必需：最多500字符，单行metadata:# 可选：额外元数据short-description:用户界面显示的简短描述author:your-nameversion:"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）

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

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

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

三、Gemini CLI

官方文档：

https://geminicli.com/docs/cli/skills/

https://geminicli.com/docs/get-started/configuration/

1. Rules 文件

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

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

特性：

• 支持 @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  }}

技能目录结构：

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|workspacegemini skills disable <name>

四、对比汇总表

Rules 文件对比

Skills 文件对比

SKILL.md Frontmatter 字段对比

五、技能复用

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

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

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