Claude Code、Codex 和 OpenCode 加载 skill 的格式是同一种:一个文件夹,里面放一个 SKILL.md 文件。这个格式就是开放的 Agent Skills 标准,由 Anthropic 提出,2026 年 11 月 4 日成为 Linux Foundation 旗下的项目。所以同一个 skill 可以在三个工具里用。麻烦在于每个工具去不同的文件夹找 skill,而且有些字段只有 Claude Code 认。这篇讲清楚每个工具去哪里找、怎么只留一份让三个都能加载、哪些东西带不过去,以及 Orkas 怎么把同一套 skill 交给它运行的每个编程 agent。
简单说:把每个 skill 文件夹放在 ~/.agents/skills。Codex 和 OpenCode 本来就读这个文件夹。Claude Code 不读,所以在 ~/.claude/skills 里给每个 skill 建一个链接。frontmatter 只写 name 和 description,skill 的名字和它的文件夹名保持一致。以上在 2026 年 11 月 8 日按 Claude Code 2.1.319、Codex 0.167.0 和 OpenCode 2.2.6 核对过。
Claude Code、Codex 和 OpenCode 去哪里找 skill
| 文件夹 | Claude Code | Codex | OpenCode |
|---|---|---|---|
~/.agents/skills | 否 | 是 | 是 |
项目里的 .agents/skills | 否 | 是 | 是 |
~/.claude/skills | 是 | 否 | 是 |
项目里的 .claude/skills | 是 | 否 | 是 |
~/.codex/skills | 否 | 是,但已弃用 | 否 |
~/.config/opencode/skills、.opencode/skills | 否 | 否 | 是 |
| 怎么调用 skill | /skill-name | $skill-name 或 /skills | @skill-name |
你的请求和某个 skill 的描述对得上时,三个工具也都会自己选用它。项目里的文件夹,每个工具都会从你启动它的那个文件夹开始,一路往上查到仓库根目录。
- 只有 Claude Code 找不到
.agents/skills。它的 skill 文档只列了.claude下的文件夹,记忆文档也写明它不读“.agents/目录下的任何内容”。要求改这一点的 issue #31005 还开着,点赞已经超过 450。 - Codex 改用了
.agents/skills。它的文档列出的是项目里的.agents/skills、个人的~/.agents/skills和管理员用的/etc/codex/skills。旧的~/.codex/skills在源码里标成了弃用,但仍然会加载。Codex 不读任何.claude文件夹。 - OpenCode 全都读。它的文档除了自己的文件夹,还列了
.claude/skills和.agents/skills,个人和项目两级都读。2.2 版本线是这样,仍在发版的 1.19 版本线也是这样。
建一个共用文件夹
把 ~/.agents/skills 当作唯一的真实副本。Codex 和 OpenCode 不用任何设置就会读它,npx skills 和 Codex 的导入功能也都往这里写。再给 Claude Code 为每个 skill 建一个链接。
- 把 skill 挪进
~/.agents/skills。你在~/.claude/skills或~/.codex/skills里写的每个 skill,把文件夹挪过去,比如mv ~/.claude/skills/release-notes ~/.agents/skills/。~/.claude/skills/synced别动:Claude Code 把你 claude.ai 账号里的 skill 放在那里。 - 把每个 skill 链接到 Claude Code 的文件夹。在 macOS 或 Linux 上运行下面这段。那里已经有同名文件夹或链接的 skill 会跳过。
mkdir -p ~/.agents/skills ~/.claude/skills
for d in ~/.agents/skills/*/; do
n=$(basename "$d")
[ -e ~/.claude/skills/"$n" ] || ln -s ~/.agents/skills/"$n" ~/.claude/skills/"$n"
done- Windows 上用目录联接(junction)。不需要管理员权限。在 PowerShell 里运行:
New-Item -ItemType Directory -Force "$HOME\.claude\skills" | Out-Null
Get-ChildItem "$HOME\.agents\skills" -Directory | ForEach-Object {
$link = "$HOME\.claude\skills\$($_.Name)"
if (-not (Test-Path $link)) { New-Item -ItemType Junction -Path $link -Target $_.FullName | Out-Null }
}- 在每个工具里确认一下。新开一个会话。Claude Code 里输入
/找这个 skill;Codex 里运行/skills;OpenCode 里输入@。
团队共用的项目,在仓库里照做一遍:skill 放在 .agents/skills,再从 .claude/skills 用相对链接指过去,比如 ln -s ../../.agents/skills/release-notes .claude/skills/release-notes。
有几点要注意:
- 逐个链接 skill,别链接整个文件夹。如果把
~/.claude/skills整个指向~/.agents/skills,Claude Code 的synced和.trash文件夹就会落进共用文件夹,Codex 和 OpenCode 也可能把同步来的 skill 一起加载。代价是每加一个 skill,都要再跑一遍上面的循环。 - 链接文件夹,别链接 SKILL.md 文件。Codex 会跟随链接过来的 skill 文件夹,但 SKILL.md 本身是链接时会被忽略。OpenAI 已把这个需求关闭,标为不计划支持。
- 别给用 Windows 的同事提交链接。Git for Windows 默认会把链接检出成一个小文本文件。用初始化脚本建链接,或者直接提交真实副本。
- OpenCode 会看到每个 skill 两次,只留一个。它既读
~/.claude/skills里的链接,也读~/.agents/skills里的文件夹。2.2 版会静默合并;1.19 版会记一条重复警告,设置OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1可以让 OpenCode 不再读 Claude 的文件夹。
写一个三家都能加载的 skill
下面这个 SKILL.md 在 Claude Code、Codex 和 OpenCode 里加载结果一样。它放在 ~/.agents/skills/release-notes/SKILL.md,旁边有一个 references 文件夹和一个 scripts 文件夹。
---
name: release-notes
description: "Drafts release notes from git commits since the last tag. Use when the user asks for a changelog, release notes, or what changed since the last release."
license: MIT
---
# 发布说明
1. 找到上一个 tag:git describe --tags --abbrev=0
2. 列出那之后的提交:git log <tag>..HEAD --oneline --no-merges
3. 按本 skill 文件夹里的 references/format.md,把提交分成 Added、Changed 和 Fixed 三组。
4. 需要存成文件时,在本 skill 的文件夹里运行 scripts/write_notes.sh。- skill 的名字和文件夹名保持一致。只用小写字母、数字和连字符,最长 64 个字符。Codex 认
name,OpenCode 2.2 认文件夹名,Claude Code 两个都认。两者不一致时,同一个 skill 在不同工具里要用不同的名字调用。名字超过 64 个字符的 skill,Codex 会跳过。 - 描述控制在 1,024 个字符以内,把别人会用到的词放在前面。这是标准规定的上限,更长的描述 Codex 也会在 skill 列表里截到这个长度。
- 值里有“冒号加空格”的,要加引号。否则 frontmatter 可能解析失败。这种情况 Codex 多数能自己修好,Claude Code 会当作没有 frontmatter 来加载,OpenCode 则可能直接跳过这个 skill,不报错。
- 让脚本自己找到所在的文件夹。这些工具是在你的项目文件夹里执行命令的,不是在 skill 的文件夹里。脚本开头写
cd "$(dirname "$0")",在哪里运行都行。 - 名字里别带“claude”,如果你可能把这个 skill 上传到 claude.ai 或 Claude API。两边都会拒绝含“claude”或“anthropic”的名字。
哪些东西从 Claude Code 带不过去
Codex 只读 name、description 和 metadata 下的一个简短描述。OpenCode 2.2 另外还读 metadata 和 disable-model-invocation。其他字段两边都会直接忽略,不报错,所以 Claude Code 的 skill 能加载,但表现不一样。
| Claude Code skill 里的写法 | Claude Code | Codex | OpenCode 2.2 |
|---|---|---|---|
allowed-tools | 生效 | 忽略 | 忽略 |
disable-model-invocation: true | 生效 | 忽略;改用 agents/openai.yaml | 生效 |
context: fork、agent、model、hooks、argument-hint | 生效 | 忽略 | 忽略 |
正文里的 $ARGUMENTS 和 $1 | 替换成你传的参数 | 原样保留 | 原样保留 |
正文里的 !`command` | 在 Claude 读 skill 之前执行 | 原样保留 | 原样保留 |
${CLAUDE_SKILL_DIR} | 替换成 skill 所在文件夹 | 原样保留 | 原样保留 |
- 步骤写成不依赖这些功能也能执行的样子。用“在本 skill 的文件夹里运行 scripts/check.sh”代替
${CLAUDE_SKILL_DIR},缺信息时用大白话让 agent 问你,代替$ARGUMENTS。Claude Code 照样能按这些说明做。 - 不想让 Codex 自己调用某个 skill,就在 skill 文件夹里加一个
agents/openai.yaml,在policy下写allow_implicit_invocation: false。用$skill-name仍然可以手动调用。 allowed-tools管不住 Codex 和 OpenCode。npx skills的兼容表写着两边都支持,但两个工具加载 skill 的代码都不读这个字段。要限制权限,请在各工具自己的权限设置里设。
一次装给多个 agent 的工具
| 工具 | 怎么共用 skill | 注意什么 |
|---|---|---|
npx skills(Vercel,38,500 星) | 把 skill 复制进 .agents/skills,再把各个 agent 的文件夹链接过去。Windows 上用目录联接。--copy 会生成各自独立的副本。 | 和这篇的做法一样。运行 npx skills add owner/repo,装到个人文件夹加 -g。 |
| skillshare(2,900 星) | 只保留一个源文件夹,链接到每个工具的文件夹;Windows 上用目录联接。 | 2026 年 11 月 6 日有更新。用 Homebrew 或一段 shell 脚本安装。 |
Codex /import | 把 .claude/skills 里的 skill 复制到 .agents/skills。 | 复制出来的副本会和原件越差越远。它还会把文本里的“claude”改成“Codex”,连文件路径里的也改(issue #40147,未关闭)。 |
| openskills(10,800 星) | 把 skill 复制进 .claude/skills,再列进 AGENTS.md。 | 2026 年 1 月以后没有发过版。它的 --universal 选项写到 .agent/skills,三个工具都不读这个文件夹。 |
CLAUDE.md 和 AGENTS.md 怎么办?
Codex 和 OpenCode 读 AGENTS.md;项目里没有 AGENTS.md 时,OpenCode 会改读 CLAUDE.md。从 2.1.277 版起,Claude Code 也读 AGENTS.md,但只在项目里没有 CLAUDE.md 和 CLAUDE.local.md 的时候。两个文件都留着的话,在 Claude Code 里打开 /config,把 Project instructions 设成两个都加载。所有 agent 都要遵守的规则写进 AGENTS.md,只有 Claude Code 需要的内容留在 CLAUDE.md。
在 Orkas 里用同一套 skill
Orkas 是一个桌面应用,能把 Claude Code、Codex、OpenCode、OpenClaw 和 Hermes 作为 agent 放进同一个对话里运行。它用的是你电脑上装好的那份,登录的也是你自己的账号。你的 skill 是这样交到这些 agent 手里的:
- 共用文件夹照常生效。Orkas 启动每个 CLI 时,它们照样读自己的 skill 文件夹,所以上面的设置不用改。Orkas 只是在你的 MCP 服务器旁边加上自己的,不会替换它们。
- 在 Orkas 里加的 skill,每个 CLI 都能用。Orkas 启动的每个 CLI 都会多一个叫
orkas的 MCP 服务器。它会列出你在 Orkas 里的 skill,任务对得上时加载对应的那个,还能运行 skill 自带的脚本。你可以点名让 Claude Code 用某个 skill,也可以让它自己挑。 - Orkas 也读你 Claude Code 和 Codex 的 skill。
~/.claude/skills和~/.codex/skills里的 skill 会出现在技能库 ▸ 全局文件夹里,指挥官在自己的任务里也能用。Orkas 对这两个文件夹只读不写。它不直接读~/.agents/skills,所以按上面的设置,它是通过~/.claude/skills里的链接找到你的 skill 的。
想装 GitHub 上的 skill 包,把仓库链接贴进和指挥官的对话,让它安装就行。如果这个包需要装依赖,Orkas 会先问你。装好的 skill 出现在技能库 ▸ 外部包里。之后从 Orkas 运行 Claude Code、Codex 和 OpenCode 时,它们都能用这些 skill,不用往三个文件夹里各复制一份。开始用的话,在侧栏点接入智能体,选上你装好的 CLI。想看两个 CLI 并排干活的完整流程,见如何让 Claude Code 和 Codex 一起用。
该选哪种做法?
| 你的情况 | 这样做 |
|---|---|
| 一台电脑上用其中两三个工具 | skill 放在 ~/.agents/skills,逐个链接到 ~/.claude/skills |
| 团队在仓库里共用 skill | 提交 .agents/skills;.claude/skills 里的链接用初始化脚本建 |
| 经常从 GitHub 装 skill | 用 npx skills add,它会帮你建好同样的链接 |
| 只用 Claude Code 和 OpenCode | 继续用 ~/.claude/skills;OpenCode 本来就读它 |
| 在 Orkas 里运行这些 CLI | 在 Orkas 里装一次 skill 包,它启动的每个 CLI 都能用 |
常见问题
Claude 的 skill 能在 Codex 里用吗?
能。Codex 读的是同一种 SKILL.md 格式,但它去 ~/.agents/skills 和 .agents/skills 找,不去 ~/.claude/skills。把 skill 文件夹挪过去,再给 Claude Code 链接回来;或者在 Codex 里运行 /import 复制过去。allowed-tools 这类字段和 $ARGUMENTS 这类功能只在 Claude Code 里生效。
OpenCode 能读 Claude Code 的 skill 吗?
能。OpenCode 会读 ~/.claude/skills 和 .claude/skills,也读 ~/.agents/skills 和它自己的文件夹,所以 Claude Code 的 skill 不用设置就会出现。不想要的话,设置 OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1。
Claude Code 读 .agents/skills 吗?
不读。截至 2026 年 11 月,Claude Code 只从 .claude 文件夹读 skill,文档也写明它不读 .agents 目录下的任何内容。要求加上这个功能的 issue #31005 还没关闭。在那之前,从 ~/.claude/skills 逐个链接过去。
为什么 Codex 看不到我链接过去的 skill?
Codex 会跟随链接过来的 skill 文件夹,但 SKILL.md 文件本身是链接时会被忽略。改成链接整个文件夹。相对链接是从链接所在的文件夹算起的,所以要从那里核对路径对不对。
为什么同一个 skill 出现了两次?
通常是工具会读的文件夹里有两份。Codex 除了 ~/.agents/skills,还在读旧的 ~/.codex/skills,同名的两份会都列出来。在 ~/.agents/skills 里留一份,删掉另一份。
想比较三个工具在 skill 以外的差别,见 Claude Code vs Codex vs OpenCode。