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

jarvisuni2026-04-12 17:48

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

官方文档：

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

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

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

官方文档：

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

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

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

官方文档：

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

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

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 Code CLAUDE.md ~/.claude/CLAUDE.md <project>/CLAUDE.md
Codex CLI AGENTS.md ~/.codex/AGENTS.md <project>/AGENTS.md
Gemini CLI GEMINI.md ~/.gemini/GEMINI.md <project>/GEMINI.md

Skills 文件对比

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

SKILL.md Frontmatter 字段对比

字段 Agent Skills Claude Code Codex CLI Gemini 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）会被其他平台忽略

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

相关推荐
不老刘2 小时前
编程被解决之后：Claude Code 负责人 Boris Cherny 深度访谈
ai编程·claude·anthropic·claude code
Kel2 小时前
PydanticAI 源码深潜：类型安全依赖注入与图执行引擎的双核架构解析
人工智能·python·架构
后端开发基础免费分享2 小时前
Claude Code 最全使用指南：CLAUDE.md、rules、skills、memory 一次讲清
人工智能·ai·claude·claudecode
亿坊电商2 小时前
亿坊外贸商城系统-支持B2C，B2B多模式，让企业做外贸电商更简单！
人工智能·数据挖掘·外贸商城
小王毕业啦2 小时前
2006-2023年 省级-建成区绿化覆盖率数据（xlsx）
大数据·人工智能·数据挖掘·数据分析·社科数据·实证分析·经管数据
十有八七2 小时前
OpenHarness 架构说明文档
人工智能·架构
Bruce1232 小时前
openclaw学习日常（一）openclaw在WSL中搭建
人工智能·node.js
liliangcsdn2 小时前
如何基于sentence_transformers构建向量计算工具
数据库·人工智能·全文检索
西海天际蔚蓝2 小时前
AI配合写的第一个demo系统页面
java·人工智能
热门推荐
01GitHub 镜像站点02一周AI热点速览（2026.03.31-04.06）：GPT-6曝光、谷歌开源Gemma 4、资本狂飙与模型军备竞赛03基于 Docker 部署 Hermes Agent 并接入飞书机器人的完整指南04OpenClaw 请求超时 llm request timed out 怎么解决？3 种方案实测，附完整排查流程05VMware Workstation Pro 17 虚拟机完整安装教程（2026最新）06CodeBuddy与WorkBuddy深度对比：腾讯两款AI工具差异及实操指南07实测！Gemma 4 成功跑在安卓手机上：离线 AI 助手终于来了08AI Weekly | 2026年4月第二周 · GitHub热门项目与AI发展趋势深度解析09开发者环境配置：用 Ollama 实现本地大模型部署(附下载慢的解决方案10UV安装并设置国内源