Codex vs Claude Code Skills：设置、配置与跨工具共享技能指南

Name

Soren Atelier

Updated on 2026/2/10

"Skills"（技能）正在迅速成为 AI 编程 Agent 中可复用的标准化单元。一个 Skill 就是一个文件夹，其中包含指令、可选的脚本和参考文件，让 Agent 可以可靠地发现和应用它。如果你同时使用多个 AI 编程工具，你可能已经感受到了为每个工具分别维护配置带来的摩擦。

OpenAI Codex 和 Anthropic Claude Code 都支持 Skills，并且都基于 Agent Skills 开放标准构建。Codex 明确表示其 Skills 基于该标准，并使用"渐进式披露"来高效管理上下文。Claude Code 同样遵循 Agent Skills 标准，同时增加了自己的扩展功能，如调用控制、子 Agent 和动态上下文注入。

这个共享的基础使得"编写一次，两个工具都能用"的工作流成为可能——前提是你需要注意技能存放的位置、配置格式的差异以及哪些 frontmatter 字段是可移植的。本指南将详细介绍每个实际差异，并展示如何在两个 Agent 之间共享同一个 Skill。

快速对比：Codex Skills vs Claude Code Skills

思维模型：相同的 SKILL.md，不同的生态系统

两个工具共享核心理念：一个包含 SKILL.md 文件的目录，其中包含 YAML frontmatter（name、description）和 Markdown 指令。Agent 读取元数据来决定何时使用该 Skill，并在激活时加载完整指令。差异在于发现路径、配置格式和高级功能。

Codex 中的"Skills"是什么

Codex Skills 是包含必需的 SKILL.md 和可选的 scripts/、references/、assets/ 的目录，还可以包含用于 UI 元数据和依赖声明（如 MCP 服务器）的 agents/openai.yaml。

Codex 先加载 Skill 的元数据，只有在决定使用该 Skill 时才加载完整指令。这被称为渐进式披露——它通过只注入 Agent 实际需要的内容来保持上下文窗口的精简。

Claude Code 中的"Skills"是什么

Claude Code 的 Skills 同样基于 SKILL.md，并作为可复用的斜杠命令使用。Claude 可以在相关时自动调用它们，你也可以通过 /skill-name 直接运行。

Claude Code 将自定义斜杠命令与 Skills 进行了合并：

• .claude/commands/review.md 和 .claude/skills/review/SKILL.md 都会创建 /review
• Skills 增加了支持文件、调用控制和相关时自动加载的功能

如何在 Codex 中创建和安装 Skill

1. Skill 目录结构

Codex Skill 最低要求：

my-skill/
  SKILL.md

功能完整的 Skill 可以包含：

my-skill/
  SKILL.md
  scripts/
    run-check.sh
  references/
    CHECKLIST.md
  assets/
    diagram.png
  agents/
    openai.yaml

SKILL.md 必须在 YAML frontmatter 中包含 name 和 description。

2. Codex 发现 Skills 的位置

Codex 会按照定义的优先级扫描多个位置：

Codex 还明确支持 symlink 链接的 Skill 文件夹，并在扫描时跟踪 symlink 目标。

3. 使用内置 Skill 工具

Codex 提供两个内置助手：

• $skill-creator — 使用正确的结构搭建新的 Skill 目录
• $skill-installer — 从外部源拉取并安装 Skills

4. 启用或禁用 Skills

Codex 可以在不删除 Skill 的情况下禁用它，只需在 TOML 配置中的 [[skills.config]] 下添加条目：

# ~/.codex/config.toml
[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

修改配置后需要重启 Codex。

5. Codex 配置格式

Codex 配置存储在 TOML 文件中，有明确的优先级顺序：

CLI 参数 > profiles > 项目配置（.codex/config.toml）> 用户配置（~/.codex/config.toml）> 系统配置 > 默认值

Skills 可以通过这些设置进行控制，并且这些设置可以按项目进行作用域划分。

如何在 Claude Code 中创建和安装 Skill

1. Skill 目录结构

Claude Code Skills 是以 SKILL.md 作为入口的目录。其他文件是可选的：

my-skill/
  SKILL.md
  template.md
  examples/
    sample.md
  scripts/
    validate.sh

在 SKILL.md 中引用支持文件，让 Claude 知道它们的内容和何时加载。

2. Claude Code 发现 Skills 的位置

Claude Code 有多个范围，按优先级排列：

Claude Code 还支持 monorepo 中的嵌套发现：如果你正在编辑 packages/frontend/...，它也会查找 packages/frontend/.claude/skills/。

3. SKILL.md 格式：YAML + Markdown

Claude Code Skills 由两部分组成——YAML frontmatter 和 Markdown 指令：

---
name: explain-code
description: Explains code with visual diagrams and analogies.
---
 
When explaining code:
1) Start with an analogy
2) Draw an ASCII diagram
3) Walk step-by-step
4) Highlight a gotcha

name 会成为 /slash-command，description 帮助 Claude 决定何时自动加载该 Skill。

4. Claude Code 的扩展 Skill 功能

Claude Code 在标准基础上扩展了 Codex 中没有的功能：

这是最大的实际差异：Claude Skills 可以像带有预处理和子 Agent 的迷你工作流一样运行，而 Codex Skills 更强调打包指令、资源和脚本，配合渐进式加载。

5. Claude Code 配置格式

Claude Code 的设置为 JSON 格式，按托管/用户/项目/本地分层，可通过交互式 REPL 中的 /config 编辑：

• 用户级：~/.claude/settings.json
• 项目级：.claude/settings.json
• 本地覆盖：.claude/settings.local.json

核心差异：逐项对比

发现路径

Codex:        .agents/skills/  →  $HOME/.agents/skills/  →  /etc/codex/skills/
Claude Code:  .claude/skills/  →  ~/.claude/skills/       →  enterprise managed

这是共享 Skills 需要 symlink 或共享仓库的主要原因。

配置格式

激活体验

• Codex：/skills 列表和 CLI/IDE 中的 $ 引用；根据 description 隐式选择
• Claude Code：/skill-name 调用；根据 description 自动加载

工具特定扩展

• Codex：可选的 agents/openai.yaml，用于 UI 元数据和依赖声明（如 MCP 服务器）
• Claude Code：frontmatter 字段如 disable-model-invocation、context: fork、命令预处理（!`…`）、参数传递

共享核心：Agent Skills 开放标准

如果你希望一个 Skill 能同时在 Codex 和 Claude Code 中工作，请以 Agent Skills 规范为基础。以下是规范的要求：

必需的 Frontmatter 字段

Codex 要求这两个字段。Claude Code 更宽松（它可以将 name 默认为目录名），但为了跨 Agent 复用，请将两者都视为必填。

文件引用

规范建议使用相对于 Skill 根目录的相对路径引用文件：

See [the reference guide](references/REFERENCE.md) for details.
 
Run the extraction script:
scripts/extract.py

保持引用层级不超过一层，以避免复杂的嵌套链。

如何通过 Symlink 在两个 Agent 之间共享同一个 Skill

最简洁的方式是在两个工具中使用同一个 Skill：

1. 维护一个单一的规范 Skills 仓库或文件夹
2. 将这些 Skill 文件夹 symlink 到每个 Agent 的发现路径中

分步设置

假设你将共享 Skills 存放在 ~/shared-agent-skills/：

~/shared-agent-skills/
  code-review/
    SKILL.md
    references/
      REVIEW_CHECKLIST.md
  test-writer/
    SKILL.md
    scripts/
      run-tests.sh

为 Codex 链接到项目中：

mkdir -p .agents/skills
ln -s ~/shared-agent-skills/code-review .agents/skills/code-review
ln -s ~/shared-agent-skills/test-writer .agents/skills/test-writer

为 Claude Code 链接到同一个项目中：

mkdir -p .claude/skills
ln -s ~/shared-agent-skills/code-review .claude/skills/code-review
ln -s ~/shared-agent-skills/test-writer .claude/skills/test-writer

或者在用户级别链接，适用于所有项目：

# Codex（用户范围）
ln -s ~/shared-agent-skills/code-review $HOME/.agents/skills/code-review
 
# Claude Code（用户范围）
ln -s ~/shared-agent-skills/code-review ~/.claude/skills/code-review

Symlink 兼容性说明

如果 Claude Code 的 /skills 列表没有显示你通过 symlink 链接的 Skill，你仍然可以直接通过名称调用它。

可移植的 SKILL.md 模板

以下是一个符合规范的模板，可在两个 Agent 中使用：

---
name: code-review
description: >
  Perform a structured code review for correctness, security,
  performance, and readability. Use when asked to review a
  diff, PR, or when preparing changes for merge.
license: MIT
compatibility: >
  Intended for coding agents (Codex, Claude Code) in Git repos.
  Requires read access to the repo.
metadata:
  owner: platform-team
  version: "1.0.0"
---
 
# Code Review Skill
 
## Inputs
- A diff, PR link, or list of changed files.
- The relevant module/service context.
 
## Process
1. Identify the goal of the change and expected behavior.
2. Review for correctness (edge cases, error handling).
3. Review for security (authz/authn, injection risks, secrets).
4. Review for performance (N+1 queries, hot paths, allocations).
5. Review for maintainability (naming, structure, tests).
6. Summarize findings with:
   - Must-fix items
   - Suggestions
   - Positive notes
 
## Reference checklist
See [our checklist](references/REVIEW_CHECKLIST.md) for the full list.

添加 Codex 特定元数据（可选）

添加 agents/openai.yaml 用于 Codex UI 元数据和依赖声明。其他工具会忽略它：

# agents/openai.yaml
display_name: "Code Review"
icon: "🔍"
dependencies:
  mcp_servers:
    - github

添加 Claude Code 特定功能（可选）

对于 Claude 专属的工作流，你可以在单独的 Claude 范围 Skill 或 .claude/ 特定的覆盖文件中添加扩展 frontmatter：

---
name: code-review
description: Structured code review with security focus.
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash(git diff*)
context: fork
---

跨 Agent Skills 最佳实践

1. 将可移植内容放在共享文件夹中

坚持使用 Agent Skills 规范字段（name、description），并使用 references/ 配合相对链接来放置长文档和检查清单。这确保两个 Agent 都能解析和使用该 Skill。

2. 隔离工具特定的高级功能

• Claude Code 的 context: fork、! 命令预处理和 allowed-tools 功能强大但仅限 Claude
• Codex 的 agents/openai.yaml 仅限 Codex，但被整洁地分离到独立文件中

两个工具都不会因为未知字段而出错——它们只是忽略这些字段。但为了清晰起见，将工具特定的功能放在工具特定的文件或覆盖中是更好的实践。

3. 使用共享 Git 仓库管理 Skills

shared-agent-skills/          # Git 仓库
├── code-review/
│   ├── SKILL.md
│   └── references/
├── test-writer/
│   ├── SKILL.md
│   └── scripts/
├── setup-links.sh            # Symlink 安装脚本
└── README.md

一个简单的 setup-links.sh 可以自动化 symlink 过程：

#!/bin/bash
SKILL_DIR="$(cd "$(dirname "$0")" && pwd)"
 
# 链接到 Codex 用户范围
mkdir -p "$HOME/.agents/skills"
for skill in "$SKILL_DIR"/*/; do
  name=$(basename "$skill")
  [ "$name" = "scripts" ] && continue
  ln -sfn "$skill" "$HOME/.agents/skills/$name"
done
 
# 链接到 Claude Code 用户范围
mkdir -p "$HOME/.claude/skills"
for skill in "$SKILL_DIR"/*/; do
  name=$(basename "$skill")
  [ "$name" = "scripts" ] && continue
  ln -sfn "$skill" "$HOME/.claude/skills/$name"
done
 
echo "Skills linked for both Codex and Claude Code."

4. 为你的 Skills 做版本管理

在 metadata 中包含 version 字段，并在共享 Skills 仓库中打标签发布。当 Skill 的行为发生变化时，版本号的变更有助于团队追踪变更内容和时间。

如果你使用 Codex 或 Claude Code 等 AI 编程 Agent 进行数据分析工作流，PyGWalker (opens in a new tab) 可以将你的 DataFrame 转换为交互式可视化——你可以构建一个集成 PyGWalker 的 Skill，让你的 Agent 随时进行数据探索。

常见问题

什么是 Agent Skills 开放标准？

Agent Skills 开放标准是一个规范，定义了 AI 编程 Agent 如何发现和使用可复用的 Skill 包。它建立了一种通用格式——包含 SKILL.md 文件的目录，文件中有 YAML frontmatter 和 Markdown 指令——使得 Skills 可以在不同的 Agent 工具之间移植。

我可以在 Codex 和 Claude Code 中使用同一个 SKILL.md 吗？

可以。两个 Agent 都基于 Agent Skills 标准构建，并识别包含 name 和 description frontmatter 的 SKILL.md 文件。关键要求是将 Skill 放在每个 Agent 的发现路径中（Codex 使用 .agents/skills/，Claude Code 使用 .claude/skills/），你可以通过从单一规范位置创建 symlink 来实现。

Codex Skills 和 Claude Code Skills 的主要区别是什么？

核心差异在于发现路径（.agents/skills/ vs .claude/skills/）、配置格式（TOML vs JSON）和扩展功能。Claude Code 增加了子 Agent 上下文分叉、shell 命令预处理和工具访问控制。Codex 增加了 agents/openai.yaml 用于 UI 元数据和 MCP 服务器依赖。基础的 SKILL.md 格式在两者之间是兼容的。

Symlink 能否用于在 Agent 之间共享 Skills？

Codex 明确支持 symlink 链接的 Skill 文件夹并跟踪目标。Claude Code 的 symlink 在调用时也能正常工作，不过 /skills 列表命令在某些版本中可能无法检测到 symlink 的 Skills。即使它们没有出现在列表中，你仍然可以通过名称调用 symlink 的 Skills。

可移植 Skills 需要哪些 frontmatter 字段？

Agent Skills 规范要求 name（必须与父目录匹配，小写字母加连字符，1-64 个字符）和 description（帮助 Agent 决定何时使用该 Skill）。Codex 和 Claude Code 都支持这些字段。license、compatibility 和 metadata 等附加字段是可选的但建议填写。

我应该把 Skills 放在哪里以实现用户级别的全局访问？

对于 Codex，将 Skills 放在 $HOME/.agents/skills/。对于 Claude Code，使用 ~/.claude/skills/。这两个位置都能让 Skills 在所有项目中可用，无需按仓库单独设置。

总结

Codex 和 Claude Code 的 Skills 共享的基因比它们不同的生态系统所暗示的要多。两者都基于 Agent Skills 开放标准构建，都使用 SKILL.md 作为入口，都支持基于 Skill 描述的渐进式加载。实际差异——发现路径、配置格式和扩展功能——确实存在但完全可以管理。

最佳策略是为你的 Skills 维护一个单一的事实来源，在可移植的核心部分坚持使用规范要求的 name 和 description 字段，并使用 symlink 让每个 Agent 看到相同的 Skill 文件夹。将工具特定的高级功能（Claude 的子 Agent 分叉、Codex 的 YAML 元数据）放在各自的扩展文件中。这样，你既能获得可移植性，又不会牺牲任何一个工具的高级能力。