Codex、Antigravity、Claude Code 的 Skills 怎么配？一篇讲清目录、写法与复用

如果你同时在用 Codex、Claude Code、Antigravity，很快就会发现一个现实问题：它们都支持“给 Agent 加能力”，但配置方法并不是一套语法走天下。

现在三者都已经能接住 SKILL.md 这套思路了。真正麻烦的地方不在“支不支持 skills”，而在于目录放哪、元数据怎么写、哪些字段只在某一个产品里生效。

这篇文章不讲空话，就讲三件事：

它们各自的原生配置方式是什么
目录应该放哪里，项目级和全局级怎么分
如果团队三种工具混着用，怎样搭一套不容易失控的结构

文中路径以我在 2026 年 3 月手头的版本和当前实际环境为例。产品更新很快，具体菜单可能会变，但目录职责和拆分思路基本不会变。

先提醒一个最容易踩坑的地方：Codex 的官方技能文档和 Antigravity 当前的 Skills 文档，都已经明确使用 .agents/... 这套复数目录。Antigravity 的一些旧材料里还能看到 .agent/... 单数写法，但如果你现在是新配，直接统一到 .agents/... 最省心。

先看结论

工具	原生机制	全局目录	推荐项目目录	适合放什么
Codex	Skills	`$HOME/.agents/skills/`	`.agents/skills/`	可复用操作手册、项目知识、脚本型技能
Claude Code	Skills	`~/.claude/skills/`	`.claude/skills/`	可自动触发或手动调用的 `SKILL.md` 技能
Antigravity	Skills	`~/.gemini/antigravity/skills/`	`.agents/skills/`	可复用技能、项目知识、固定操作套路

一句话概括：

三者现在都支持 Skills
Codex 和 Antigravity 更偏向 .agents/skills/
Claude Code 还是 .claude/skills/
真想跨工具复用，别硬抹平成一个目录名，而是把“共享知识”和“工具专属配置”分开

Codex：官方已经明确用 `.agents/skills/`

Codex 现在已经把 skills 当成一等公民来看待了，而且官方文档写得比前阵子清楚多了：同一个 skill 可以在 App、CLI、IDE 扩展里复用，也可以直接跟着仓库一起走。

按当前 Codex 官方文档，最关键的两条是：

个人技能放到 $HOME/.agents/skills/<skill-name>/SKILL.md
仓库技能放到 .agents/skills/<skill-name>/SKILL.md

这里有个细节很容易搞混：Codex 的 skills 目录 现在是 $HOME/.agents/skills/，但它的 配置文件 仍然是 ~/.codex/config.toml。也就是说，别把“技能放哪里”和“怎么开关某个技能”混成一件事。

如果你是一个人用，优先放用户目录；如果是团队共用，直接提交到仓库里的 .agents/skills/，最省事。

Codex 推荐目录结构

.agents/
  skills/
    pr-review/
      SKILL.md
      references/
        checklist.md
    release-note/
      SKILL.md
      scripts/
        collect_changes.sh

Codex 的 `SKILL.md` 最稳妥写法

---
name: pr-review
description: 审查当前分支或 Pull Request 的改动，输出风险、回归点和测试缺口。适用于代码评审、提测前检查和合并前自查。
---

# PR Review

执行代码评审时：

1. 先读取变更文件和 diff
2. 按功能正确性、回归风险、异常处理、测试覆盖四个维度检查
3. 如果仓库里存在 `references/checklist.md`，优先按其中清单逐项核对
4. 结论按“必须修”“建议修”“可接受风险”三段输出

这里有两个要点特别重要：

description 不是装饰品，它决定了技能会不会被模型自动想到
长文档不要全塞进 SKILL.md，把细节拆到 references/ 或 scripts/ 里更稳

Codex 特有的一层：`agents/openai.yaml`

如果你想在 Codex App 里把一个 skill 配得更完整，光有 SKILL.md 还不够。Codex 额外支持在技能目录里放一个 agents/openai.yaml，用来配置界面显示、隐式调用策略，以及依赖哪些工具。

例如：

interface:
  display_name: "PR Review"
  short_description: "审查 diff，重点找 bug 和漏测"

policy:
  allow_implicit_invocation: false

这层配置的意义很实际：

SKILL.md 负责“这个 skill 是什么、什么时候该用”
agents/openai.yaml 负责“Codex App 里怎么展示、允不允许自动触发”

如果你不想让 Codex 自动触发某个高副作用 skill，优先在这里把 allow_implicit_invocation 关掉，比只靠正文描述更稳。

Codex 还有一个容易忽略的点

Codex 还支持在 ~/.codex/config.toml 里，通过 [[skills.config]] 临时禁用某个 skill，而不是把目录删掉。这个能力很适合做灰度试用：先把 skill 分发给团队，再按人或按环境逐步打开。

我自己的经验是，Codex 很适合放这三类东西：

稳定重复的工作流，比如发版说明、代码评审、日志排查
团队约定，比如目录规范、接口风格、提交要求
需要脚本配合的动作，比如生成周报、抽取变更、转文档格式

如果一个 skill 会直接部署、发消息、改线上配置，那就不要让它“全自动触发”。这种高副作用动作最好显式点名调用。

Claude Code：技能体系最完整，前置开关也最多

Claude Code 现在对 skills 的支持已经很成熟了，而且官方文档写得很细。它不仅支持标准的 SKILL.md，还提供了不少额外控制项，比如：

disable-model-invocation
allowed-tools
user-invocable
context: fork
agent

简单说，Claude Code 比较像“技能系统的完整版”。

Claude Code 放哪里

全局技能：~/.claude/skills/<skill-name>/SKILL.md
项目技能：.claude/skills/<skill-name>/SKILL.md

另外，老的 .claude/commands/*.md 还可以继续用，但官方已经把命令和 skills 基本并到一套机制里了。新配置我更建议直接写 skill。

一个更实战的 Claude Code skill

---
name: pr-review
description: Review the current branch or pull request for bugs, regression risk, and missing tests.
disable-model-invocation: true
allowed-tools: Read, Grep, Glob, Bash(git diff *), Bash(gh pr view *)
context: fork
agent: Explore
---

Review $ARGUMENTS using this process:

1. Read the changed files and diff first
2. Identify correctness issues before style issues
3. Call out missing tests explicitly
4. Return findings ordered by severity
5. Do not rewrite code unless the user asks for fixes

这一段配置比 Codex 那版多了几个关键控制：

disable-model-invocation: true 这代表它不会自己乱触发，只有你手动用 /pr-review 时才跑
allowed-tools 这代表 skill 激活后，Claude 能直接用哪些工具
context: fork 这代表任务丢进独立上下文或子代理里跑，不污染当前主对话
agent: Explore 这代表你可以把这个 skill 交给更适合探索代码库的子代理

如果你希望一个 skill 是“背景知识”，而不是给人手动点的命令，可以反过来这样配：

---
name: api-conventions
description: 项目的 API 设计约定、错误格式和字段命名规范
user-invocable: false
---

这类技能更像是“脑内知识包”，适合放规范、术语、遗留系统说明。

Claude Code 适合怎么拆

会改文件、会执行动作的，做成手动触发 skill
会影响整体判断但不需要用户点名的，做成自动触发的背景 skill
需要大量上下文或读多文件的，优先考虑 context: fork

这一套拆法比“一个超长 SKILL.md 包办全部”靠谱得多。

Antigravity：重点先看 Skills 目录和写法

全局 skills：~/.gemini/antigravity/skills/
工作区 skills：.agents/skills/

这里还有一个容易把人搞晕的历史包袱：你在一些旧 Codelab 或旧文章里，可能还会看到 .agent/... 的单数目录写法。就 skills 而言，当前应该优先按 .agents/skills/ 来理解。

如果你是从零开始配，我的建议很简单：直接把仓库里的技能目录统一成 .agents/skills/，后面和 Codex 共用也更顺手。

一个适合放在 `Skills` 里的例子

文件：.agents/skills/pr-review/SKILL.md

---
name: pr-review
description: 审查当前分支或 Pull Request 的改动，重点检查 bug、回归风险和缺失测试。
---

# PR Review

执行代码评审时：

1. 先读取最近变更和受影响文件
2. 优先找功能正确性问题，再看风格问题
3. 明确指出缺失测试
4. 输出时按严重程度排序

三种工具一起用时，我推荐的目录方案

如果你只用一种工具，就老老实实跟着原生目录走。
但如果你们团队里有人用 Codex，有人用 Claude Code，还有人用 Antigravity，我更推荐下面这套分层：

repo/
├── .agents/
│   ├── skills/
│   │   ├── pr-review/
│   │   │   └── SKILL.md
│   │   └── release-note/
│   │       ├── SKILL.md
│   │       └── scripts/
│   │           └── collect_changes.sh
└── .claude/
    └── skills/
        ├── pr-review/
        │   └── SKILL.md
        └── release-note/
            └── SKILL.md

这套结构背后的思路是：

.agents/skills/ 放跨工具尽量通用的技能内容，可同时服务 Codex 和 Antigravity，也符合两边现在更主流的目录约定
.claude/skills/ 放 Claude Code 专属增强版，主要是那些要用 allowed-tools、context: fork、agent 的技能

这样拆的好处很直接：

通用知识和工具特性不会糊成一团
不同客户端更新时，迁移成本更低
团队能一眼看出哪些是“长期规则”，哪些是“可调用动作”

配置时最容易踩的 5 个坑

1. 把所有东西都塞进一个技能

这几乎是最常见的问题。一个 SKILL.md 又写规范、又写流程、又写边界条件、又写十几个示例，最后谁都不爱读，模型也不一定触发得准。

更好的拆法是：

背景知识一个 skill
具体动作一个 skill
长参考文档单独放 references/

2. `description` 写得像标题，不像触发条件

比如你写：

description: 代码评审

这基本等于没写。更好的写法是直接告诉模型“什么时候该用它”：

description: 审查当前分支或 Pull Request 的改动，重点检查 Bug、回归风险和缺失测试。

短一点没问题，别空。

3. 有副作用的动作还允许自动触发

部署、发消息、改数据库、推 Git、发工单，这些事情不要图省事开自动。

我的习惯是：

Codex 中这类动作都要求显式点名
Claude Code 中给这类 skill 加 disable-model-invocation: true
Antigravity 中也尽量别让高副作用 skill 自动触发

4. 团队技能和个人技能混放

一个很实用的原则：

仓库里的，只放团队共识
home目录里的，只放个人偏好和私人实验

这样就不会出现“我机器上很好用，你拉下来怎么没有”的尴尬局面。

5. 想做跨工具复用，却要求三个客户端完全同构

这也是个常见误区。
别追求所有工具都读同一份目录、同一套字段、同一种触发方式。现实一点：

把共享知识抽出来
把工具专属控制留给各自目录
让内容复用，而不是强行让目录名一模一样

这样反而最稳。

我自己的建议

如果你现在正准备开配，我建议按这个顺序来：

先把团队长期有效的共识写成一个最基础的共享 skill
再挑两三个高频动作，做成 .agents/skills/ 下的共享 skill
最后再处理高风险 skill 的触发策略和开关

别一上来就造十几个技能库。
先把最常用、最稳定、最容易复用的那几件事做顺，收益已经很大了。

如果你只想记住一句话，那就是：

Codex 和 Antigravity 现在都更偏向 .agents/skills；Claude Code 还是 .claude/skills。

再补一句：

Codex 用 SKILL.md + agents/openai.yaml；Claude Code 用 SKILL.md frontmatter；Antigravity 重点先把 skills 目录理顺。

把这两个差别记住，后面的目录设计就顺了。

参考资料

如果你准备长期维护这套配置，建议把下面这些官方或标准文档一起收藏：

如果后面某个路径、字段名、菜单入口变了，优先看这些文档的最新版本，不要死磕旧截图。

关于

关注我获取更多资讯

📢 公众号

💬 个人号