跨工具复用 Skill：同一份 SKILL.md 在 Claude Code / Codex / Gemini CLI 通用

你花时间写好了一个 Skill——让工具按你的代码规范审 PR、或者帮你按固定格式整理发布日志。然后你发现：这个 Skill 只待在 Claude Code 的 ~/.claude/skills/ 目录里，同事用 Codex，另一个同事在试 Gemini CLI，三个人各写各的，同一件事干了三遍。

这就亏了。

同一份 SKILL.md 理论上在多个支持开放标准的工具之间直接复用，不用重写。 这一节讲清楚它为什么能移植、实际怎么做、有哪些注意点，以及怎么把散落的 Skill 攒成一笔可复用的资产。

---

为什么 Skill 能跨工具移植

理解这一点需要先看清 SKILL.md 的本质：它是一段 YAML frontmatter 加上一段 markdown 正文，没有编译步骤、不需要特定运行时、不调用任何工具私有的 API。

这种设计不是偶然的。Skills 格式遵循 agentskills.io 这套开放标准——它定义了一个 skill 应该长什么样，但不属于任何一家工具。只要某个工具实现了对这套标准的支持，它就能读懂你的 SKILL.md，不需要你改任何内容。

对比一下：MCP（Model Context Protocol）需要你为每个连接起一个 server 进程；而 Skill 只是一个文本文件夹。换工具时，MCP 配置得重写，而 SKILL.md 直接复制过去就行。

还有两层技术原因让 Skill 天然适合移植：

markdown 是事实上的通用格式。任何 AI 工具都能读 markdown，渐进式披露的三层结构（元数据常驻 → 命中加载正文 → bundle 按需读取）对工具来说也只是"读文件"这件事，没有锁定点。关于渐进式披露的原理，可以回看 Skills 入门：SKILL.md 是什么，渐进式披露怎么省 token。

方法和执行者解耦。SKILL.md 里写的是"这类活怎么做"——这是过程知识，不是"在这个工具里点哪个按钮"。过程知识是工具无关的，所以天然可移植。

---

实际怎么做：各工具的发现机制

说"可以跨工具复用"是一回事，实际配置是另一回事。各工具发现和加载 skill 的目录位置和配置方式会有差异，这里只给思路，具体以官方文档为准——因为这类细节随版本更新快。

通用原则：

• 大多数支持 agentskills.io 标准的工具，都有一个用户级技能目录（跟着用户走，换项目也有）和一个项目级技能目录（放在仓库里，跟项目走）。
• 用户级目录一般在用户 home 下某个配置文件夹（Claude Code 是 ~/.claude/skills/，其他工具类推）。
• 项目级目录一般在仓库根目录的 skills/ 或 .skills/ 子文件夹里，放进 git 就能随仓库一起分发。

操作流程：

1. 查你要复用 skill 的那个工具的官方文档，确认它支持 agentskills.io 标准，找到它的技能加载目录。
2. 把整个 skill 文件夹（技能名/SKILL.md，加上同目录的 bundle 文件）原样复制到对应目录。
3. 重启工具，用一句自然语言触发，确认它按预期行为走。
4. 如果没触发，先检查 description 字段是否写了"当用户……时使用"的触发句式——这是各工具共用的命中机制。

一个实际的目录结构例子，把 skill 同时供给两个工具：

~/.claude/skills/           ← Claude Code 的用户级目录
└── review-pr/
    └── SKILL.md

~/path/to/codex/skills/     ← Codex 的对应目录（以官方为准）
└── review-pr/
    └── SKILL.md            ← 同一个文件

如果你嫌两边各放一份太麻烦，可以用符号链接（ln -s）指向同一份源文件，或者把 skill 统一放进 git 仓库，各自通过工具的"加载外部技能目录"功能指向这个仓库。

关于如何在进阶实战中用好 SKILL.md 的渐进披露层，见 SKILL.md 渐进式披露实战。

---

跨工具复用的注意点

移植本身不难，但有几类写法会悄悄打破可移植性，踩坑前先认识一下：

1. 写死了工具特有的路径

最常见的坑。比如在 skill 正文里写：

把结果写入 ~/.claude/output/result.md

这个路径在 Claude Code 的用户环境里存在，换到 Codex 里就不对了。

怎么破：用相对路径，或者在正文里只描述"把结果写入当前项目根目录下的 output/result.md"——让工具根据自己的当前工作目录去解析，而不是硬编码绝对路径。

2. 调用了某工具的私有命令或斜杠命令

有些工具有自己独有的斜杠命令（比如 /status、/clear）。如果你在 skill 正文里写"执行 /xxx 命令"，其他工具不认识这个命令，skill 就失效了。

怎么破：用自然语言描述意图，而不是调用特定命令。比如"检查当前认证状态"比"/status"更通用。工具特有的能力可以在正文末尾单独标注"以下步骤在 [工具名] 中额外执行……"，让用户知道这步不跨工具通用。

3. 依赖某工具特有的上下文机制

某些工具有独特的上下文注入方式（比如自动读取特定格式的配置文件）。如果 skill 正文里的逻辑假设这个上下文一定存在，换工具就会出错。

怎么破：在 skill 里只假设最基础的能力——工具能读文件、能理解 markdown 指令。需要特定上下文的步骤，在正文里写"如果你的工具支持 X，则……；否则手动提供 Y"。

---

怎么组织一个可复用的 Skill 库

把 skill 散在各处，就算每个都写得好，价值也是碎的。真正的杠杆是把 skill 当资产管。

个人的 Skill 库

最简单的结构：一个专门的目录，按用途分文件夹：

~/my-skills/
├── README.md          ← 记录每个 skill 是干什么的、上次改动原因
├── coding/
│   ├── review-pr/SKILL.md
│   └── write-commit/SKILL.md
├── writing/
│   ├── weekly-report/SKILL.md
│   └── release-notes/SKILL.md
└── ops/
    └── deploy-check/SKILL.md

用 git 管这个目录。换电脑时，clone 下来，再按各工具的文档把这个目录注册为技能来源，所有积累立刻全部到位。

团队的 Skill 库

团队场景下，最关键的变化是一个真相源：不要五个人各自维护一份，否则同一件活有五种做法，没法累积。把 skill 库放进一个公共 git 仓库，所有人从同一个地方拉取，改进走 PR 评审，合并后全队立即生效。

每个 skill 指定一个 owner，出问题有人认领。description 字段写清触发场景，写成"当用户说……时使用"并给两三个真实措辞示例——这是决定 skill 被不被正确命中的命门，不是装饰性的介绍文字。

关于团队 Skill 共享的详细实操清单（命名规范、版本管理、避坑表），见 Skills 可移植与团队共享：跨工具复用、agentskills.io 标准。

---

和"平台锁定"的对比

不用开放标准时，你的选择通常是：把"怎么做某类活"写成某工具的私有插件、私有提示词模板、或者特定工具的配置文件。这些东西有一个共同缺点：只在那个工具里有效，工具一换，资产作废。

平台锁定的代价不只是"换工具时要重写"——更深的代价是你不敢轻易尝试新工具，因为切换成本太高。这让你在工具选择上失去了灵活性。

基于 agentskills.io 开放标准的 Skill 把这个问题反过来了：

维度	绑定某工具的私有配置	agentskills.io 开放标准的 SKILL.md
换工具成本	重写，资产清零	整批复制，直接可用
团队工具不统一	每个工具维护一套	一份通用
版本管理	依赖工具提供的能力	纯文本，Git 直接管
人能读懂吗	不一定	纯 markdown，谁都能读
沉淀的本质	某工具的插件配置	与工具无关的方法论

说到底，SKILL.md 里写的是你的判断和方法，不是某个工具的命令序列。你的方法比任何工具的寿命都长——这才是把它写成开放格式的真正价值。

有意思的是，AI 编程工具这个领域发展极快，今天主流的工具组合，明年可能完全不同。如果你的"工具使用经验"存在某家私有格式里，每次洗牌都要重来；如果存在开放标准的 SKILL.md 里，它会随你一起走过所有工具的迭代。

---

常见问题

Q：所有 AI 编程工具都支持 agentskills.io 标准吗？

不是所有工具都支持。在实际操作前，先去目标工具的官方文档确认它是否支持 agentskills.io 标准，以及具体的技能目录路径。如果某个工具不支持，SKILL.md 的内容依然可以手动转换——正文是 markdown 描述的方法步骤，你可以把它粘贴进那个工具的提示词、规则文件或等价配置里。虽然不能"原样复用"，但内容不用重新想，只是格式适配。

Q：SKILL.md 里的 bundle 脚本文件（.py、.sh 等）跨工具也能用吗？

这取决于两件事：一是目标工具是否支持 bundle 文件（以官方文档为准），二是脚本本身的依赖环境（Python、shell 等）在目标机器上是否存在。纯 markdown 的 SKILL.md 正文是最通用的，bundle 脚本的跨工具移植性次之。如果你希望 skill 尽可能通用，把核心逻辑写在 markdown 正文里，bundle 脚本作为"在支持的工具里的增强"，而非必要依赖。

Q：同一个 skill 在不同工具里触发条件有差异，怎么办？

这属于各工具的实现差异，通常体现在 description 字段的语义匹配精度上。一个好的做法是：在 description 里给出多个不同措辞的触发例句，覆盖各种说法，而不是只写一句。比如"当用户说'帮我审一下这段代码'、'review 这个 PR'、'看看这里有没有问题'时使用"——这种写法对不同工具的语义匹配都更友好。如果在某个工具里实在触发不了，在那个工具的配置文件（如 CLAUDE.md）里加一行"你有 review-pr 这个 skill，收到代码审查类请求时主动使用"来强化触发。

Q：团队里有人用不支持 Skills 的工具，怎么让他们也受益？

一个务实的做法是：SKILL.md 的正文用清晰的 markdown 写步骤，不熟悉 Skills 机制的人也可以直接读这份文档，把它当"操作规范"人工执行，或者手动复制到他们工具的系统提示词里。开放 markdown 格式的好处之一就是"人也能读"——它本来就不只是给 AI 看的。

---

浏览 AI 编程教程大全 可以找到 Skills 体系的完整脉络，从入门到进阶，包括 Skills 入门 和 团队共享实操，按需取用。Skills 术语解读 适合想快速对齐概念的人。

👉 看看我们的 AI 编程实战体系课，或逛 AI 编程教程大全 把基本功打扎实。