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）文件的命名及存放路径。

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

 
Frontmatter 字段规范
 

渐进式披露（Progressive Disclosure）

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

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

官方文档：

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-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 匹配任务

官方文档：

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-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）

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

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

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

官方文档：

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

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

1. Rules 文件

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

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

特性：

• 支持 @file.md 语法导入其他文件
• 文件名可通过 context.fileName 配置项自定义
• /memory add 命令可快速添加到全局 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 ：启用技能
• /skills disable ：禁用技能
• /skills reload：刷新技能发现

终端命令：

gemini skills install 
       
           # 安装技能 gemini skills uninstall 
        
                 # 卸载技能 gemini skills enable 
         
           --scope user|workspace gemini skills disable 
           
          
         
       

Rules 文件对比

Skills 文件对比

SKILL.md Frontmatter 字段对比

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

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

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