"Agent Skills 跨工具兼容：四层移植边界"

Agent Skills 统一了知识和工作流的包装方式，却没有统一承载它们的运行环境。一个完全符合规范的 SKILL.md，仍可能在另一款工具里找不到、触发方式改变，或者因为权限和依赖不同而执行失败。本文依据截至 2026 年 7 月 22 日的官方文档，拆解 Codex、Claude Code、Gemini CLI 与 GitHub Copilot 之间真正可移植的边界。

阅读时间：约 10 分钟 · 约 3,400 字 · 本文是官方文档矩阵，不是全版本、全平台实机测试报告

核心结论

• Agent Skills 规范只约束 skill 目录内部的基本结构，不规定所有客户端必须扫描同一个目录。
• 跨工具核心应保留 name、description 和相对路径资源；license、compatibility、metadata 是可选字段，allowed-tools 仍是实验性字段。
• .agents/skills 是实现惯例，不是规范要求。Codex、Gemini CLI 和 Copilot 已在官方文档中支持它，Claude Code 当前没有。
• 兼容性必须分四层验证：内容能解析、客户端能发现、调用方式等价、运行时能力等价。只过第一层，不能证明工作流已经迁移成功。

先划清边界：规范到底统一了什么

Agent Skills 规范把一个 skill 定义为目录，其中至少包含 SKILL.md。脚本、参考资料和资产目录都可以按需加入。最小 frontmatter 只有两个必填字段：

---
name: dependency-review
description: 审查依赖变更的来源、风险与策略合规性。新增或升级软件包时使用。
---

license、compatibility、metadata 都是可选项。allowed-tools 也是可选项，而且规范明确将其标为实验性，客户端支持程度可能不同。正文则是自由的 Markdown 指令。

这个共同格式解决了一个重要问题：团队可以用可读、可版本控制的目录交付流程知识，不必把所有说明塞进系统提示词。但它没有规定以下内容：客户端去哪里找 skill、是否向上遍历目录、同名 skill 谁覆盖谁、何时自动触发、显式调用使用什么命令、权限提示如何呈现、工具叫什么、脚本能否联网，以及运行环境预装了什么。

Agent Skills 客户端实现指南也把发现、暴露和加载留给实现方。.agents/skills 是多个客户端正在采用的共享路径，但不是格式规范强制的目录。

因此，本文比较的是 2026 年 7 月 22 日官方文档所描述的行为。它不是四款产品所有版本、操作系统、企业策略和分发形态的实机穷举。文档更新或管理员策略都可能改变实际结果。

四款工具的官方兼容矩阵

Codex Skills 文档明确写出了从当前工作目录向仓库根目录逐层发现 .agents/skills 的规则。对 monorepo 来说，启动目录不同，可见的 skill 集合就可能不同。Codex 还允许在 skill 内使用 agents/openai.yaml 补充展示和依赖元数据；它属于 Codex 适配层，不是最小跨客户端合同。

Claude Code Skills 文档列出 .claude/skills、~/.claude/skills、插件和额外目录，并提供丰富的调用扩展字段。当前官方发现路径没有列出 .agents/skills。要求增加共享搜索路径的 anthropics/claude-code issue #56193已经以 not planned 关闭。Issue 状态不代表永久承诺，但能佐证本文时间点上的文档差异。

Gemini CLI 创建指南把 .agents/skills 明确作为 .gemini/skills 的别名，同时支持工作区和用户级目录。Gemini CLI 管理指南还定义了层级优先级和激活确认。发现成功不代表立刻执行：skill 每次触发后，用户仍需同意激活并开放资源访问。

发现深度也不能直接类推。Gemini CLI 文档描述的是当前工作区中的 skill 目录，Codex 则明确写出从当前工作目录向仓库根目录逐级扫描。团队从嵌套目录启动两款客户端时，不应假设它们看到的项目 skill 完全相同。

GitHub Copilot Skills 文档支持本次比较中最宽的项目目录别名集合。它也特别提醒：如果用 allowed-tools 预先授权 shell 或 bash，确认步骤会被移除，恶意 skill 或提示词注入可能借此执行任意命令。

四层兼容模型

问“支不支持 Agent Skills”太粗了。更有用的问题是：兼容性在哪一层停止？

第一层是开放格式带来的成果。第二到第四层属于 harness。

这个区分与MCP vs CLI 的接口问题相通：描述一种能力的方式相同，不代表执行环境相同。它也符合中文 Harness Engineering 框架的核心判断：模型之外的发现、工具、反馈和约束，才决定工作流能否稳定交付结果。

哪些内容能移植，哪些必须适配

可移植核心应该刻意保持小而清晰：

1. 目录名与符合规范的 name。
2. 同时写清能力和触发条件的 description。
3. 不依赖产品专属调用语法的 Markdown 指令。
4. 指向 scripts/、references/、assets/ 的相对路径。
5. 有明确解释器、依赖检查、稳定输入输出和失败退出码的脚本。
6. 运行结果确实受环境影响时，在 compatibility 中声明依赖。

可选字段也可以进入共享核心，但要保守使用。license 说明复用条款，metadata 适合保存带命名空间的字符串，compatibility 可以声明 Python、Git、网络或系统包要求。它们只是声明，不保证每个客户端都会执行检查。

下面这些内容应该放进适配层，或者至少写入明确的运行假设：

• 扫描路径和同名优先级。
• Claude Code 的 disable-model-invocation、user-invocable、argument-hint、model、context、agent 与 hooks。
• Codex 的 agents/openai.yaml。
• Gemini CLI 的激活许可与会话内启停状态。
• Copilot 在 cloud、CLI、review、app、IDE 等入口之间的工具差异。
• Bash、shell、Read 或特定 MCP 工具等客户端词汇。
• 网络、工作区信任、sandbox、密钥、预装包和操作系统行为。

还要警惕宽松解析器。Claude Code 可能接受规范之外的字段，或为缺失字段提供默认值。某个 skill 在 Claude Code 能运行，不代表它能通过更严格的规范校验。只要目标是多客户端复用，就应按开放规范的最小要求编写，而不是按最宽松的客户端编写。

单一来源如何分发到四种客户端

不要维护四份手工副本。更稳定的做法是保留一个规范核心，再生成客户端视图。

agent-skills/
├── src/
│   └── dependency-review/
│       ├── SKILL.md
│       ├── scripts/
│       ├── references/
│       ├── assets/
│       └── agents/
│           └── openai.yaml
├── adapters/
│   └── claude-code/
│       └── dependency-review.frontmatter.yaml
├── fixtures/
│   └── dependency-review/
│       ├── prompt-explicit.txt
│       ├── prompt-implicit.txt
│       └── expected.json
└── dist/
    ├── .agents/skills/dependency-review/
    └── .claude/skills/dependency-review/

源目录里的 SKILL.md 只写规范字段。Codex 的 agents/openai.yaml 可以作为额外文件留在目录内，因为规范允许存在其他资源。如果团队确实依赖 Claude Code 专属 frontmatter，就在构建阶段将 overlay 合并进 .claude/skills 的产物。生成文件要带源校验和与“禁止手改”提示。

发布产物默认使用复制，不要把软链接当作唯一方案。包管理器、压缩包、Windows 环境和远程 Agent 对软链接的处理并不一致。本地开发可以用 link 加速迭代，CI 则应从干净目录生成副本，分别校验两套输出，并在产物与源不一致时失败。

用一个 fixture 测完四层

兼容 fixture 越简单越好。它的任务是证明 harness 合同，而不是测试模型能否完成复杂工作。

可以建立一个 compatibility-probe skill：frontmatter 只使用规范字段；引用 assets/marker.txt 并要求原样返回固定标记；带一个只读脚本输出固定 JSON；定义一个显式触发短语和一个自然语言触发场景；不联网、不写文件、不产生外部副作用。

然后在四个客户端运行同一组检查：

C1  解析：标准校验器是否接受源目录？
C2  发现：项目级和用户级副本是否出现在预期作用域？
C3  显式调用：能否按客户端官方方式直接启动？
C4  隐式调用：自然语言提示能否稳定选中？
C5  资源：能否通过相对路径读取 marker？
C6  运行时：能否按预期权限流程执行安全脚本？
C7  失败：依赖缺失时是否明确停止，而不是假装成功？
C8  冲突：项目级和用户级同名时，哪一份生效？

结果要记录客户端版本、操作系统、启动目录、策略配置和调用方式。不要压成一个“支持/不支持”的布尔值。更有用的格式是：内容=通过，发现=通过，调用=有条件，运行时=失败，并附上日志证据。

当核心 skill、适配层、安装器或客户端基线变化时，CI 都应重跑这个 fixture。它是 harness 的合同测试，不是模型排行榜。

安全边界：Skill 是可执行的信任

Skill 看起来像文档，但其中的指令可以引导 Agent 读文件、执行 shell、访问网络和接触密钥。安装 skill 本质上是一项信任决策。

分发前应审查整个目录，而不只是 SKILL.md。远程来源要固定到 commit 或 release，记录校验和，扫描脚本，并维护解释器与依赖白名单。Skill 更新应按代码变更走审查和来源追踪。

不要把 allowed-tools 当作跨客户端 sandbox 策略。它在规范中仍是实验性字段，各客户端的权限语义也不相同。Claude Code 将其描述为预授权，而不是对其他工具的全局禁止。Copilot 则明确警告，预授权 shell 会移除关键确认边界。真正的拒绝规则、工作区隔离、网络策略和密钥范围，必须由宿主 harness 执行。

职责分工应当清楚：skill 声明自己需要什么，harness 决定它实际能得到什么。迁移到新客户端时，不能因为工具词汇变化，就默认扩大 skill 权限。

FAQ

一份 SKILL.md 能原样跑在四款工具里吗？

可以，但前提是它只使用规范核心，已安装到每个客户端的官方路径，而且依赖的能力在四个环境都存在。这只能证明内容复用，不能证明自动触发和执行结果等价。

.agents/skills 是统一标准目录吗？

不是。它是 Codex、Gemini CLI 和 Copilot 当前支持的跨客户端惯例，但 Agent Skills 规范没有强制它。Claude Code 当前仍记录 .claude/skills。

共享 skill 应不应该写 allowed-tools？

只有在每个目标客户端都完成测试，而且团队理解其安全效果时才建议写。由于字段仍属实验性，权限语义又不同，很多共享 skill 更适合把工具策略留在客户端专属配置中。

是否需要为四款工具拆成四个仓库？

通常不需要。一个源目录、少量适配层、生成产物和兼容 fixture 已经足够。只有运行依赖或发布责任真正分离时，才值得拆仓库。

最小迁移测试包含什么？

校验源文件，从真实启动目录确认发现，分别测试显式和隐式调用，读取一个相对资源，运行一个无害脚本，再观察一次受控失败。这个顺序刚好覆盖四层。

结论与下一步

Agent Skills 确实解决了可移植性问题，但解决的是内容层。更稳健的工程方案是保留规范核心、隔离客户端扩展、按官方路径分发，并用 harness 合同测试代替“兼容”标签。

下一步很具体：本周先做一个只读 compatibility-probe fixture，在团队实际支持的 Codex、Claude Code、Gemini CLI 和 Copilot 入口上各跑一遍。在迁移任何生产 skill 前，先把四层结果和证据发布到团队内部。

官方参考资料

• Agent Skills 规范
• Agent Skills 客户端实现指南
• OpenAI Codex：Build skills
• Claude Code：Extend Claude with skills
• Anthropic issue #56193：增加共享 skill 搜索路径
• Gemini CLI：Creating Agent Skills
• Gemini CLI：Managing Agent Skills
• GitHub Copilot：Adding agent skills