skills如何做到跨Agent全兼容:一套Agent Skills同时驱动Claude Code、Codex与Gemini CLI

原创2026-10-11 16:17:071,936 阅读

skills如何做到跨Agent全兼容:一套Agent Skills同时驱动Claude Code、Codex与Gemini CLI

skills 是一套 Agent Skills(智能体技能),它把「从想法到上线、验证、归档」的完整软件开发流程拆成 9 个可组合的 Markdown 技能,并且同一套技能可以同时驱动 Claude Code、Codex 与 Gemini CLI。它没有为每个 AI 编码助手各写一份提示词,而是靠三件事做到全兼容:SKILL.md 作为所有客户端通用的指令层、面向 Codex 的轻量界面适配器、以及一个自动拦截「工具绑定写法」的兼容护栏。下面带你看清这套机制。

跨 Agent 兼容的核心设计:一个 skill 目录 = 通用指令 + 工具适配层

skills 基于开放的 Agent Skills 格式构建,每个技能就是一个文件夹,结构非常清晰:

skills/scope/
├── SKILL.md          ← 真正的技能指令,所有 Agent Skills 客户端都读它
└── agents/
    └── openai.yaml   ← 工具专属的界面元数据(以 Codex 为例)

1️⃣ SKILL.md:所有客户端共读的"唯一事实源"

每个 SKILL.md 的 frontmatter 里声明三样东西:name(技能名)、allowed-tools(允许使用的工具清单)、description(一句话描述,会加载进每个会话)。以 develop 技能 为例:

---
name: develop
allowed-tools: Bash, Read, Grep, Glob, Write, Edit, Agent, AskUserQuestion
description: "Run /develop to build a feature, UI or backend, from an approved design..."
---

无论是 Claude Code、Cursor、Codex 还是 Gemini CLI,安装时读的都是这份 SKILL.md,正文里全是「面向能力」的自然语言指令,而不是某家工具的私有配置,这是跨工具可移植的地基。

2️⃣ agents/openai.yaml:Codex 的"纯展示"适配层

openai.yaml 只承担一件事:告诉 Codex 在自己的 agent 选择器里显示什么名字、简介和开场提示。

interface:
  display_name: "Scope"
  short_description: "Plan and reconcile feature scopes"
  default_prompt: "Run the scope skill: read its SKILL.md, then plan the next feature slices..."

它不包含任何执行逻辑,所有技能逻辑都留在 SKILL.md 里。换句话说,适配层只做"展示",不做"实现",换工具时改的只是这一层薄壳。

兼容性护栏:11 条自动化规则,杜绝"悄悄绑定某个工具"

跨工具漂移最大的敌人是"无意识":某次编辑里写上 Claude 专属的模型别名,或粘进一段只在 bash 里成立的命令,skill 就悄悄失去了可移植性。skills 的做法是把约束变成每次必跑的自动检查:scripts/check-portability.mjs,一条命令执行(npm run check),任何违规直接让检查失败。规则包括:

规则 作用
每个 SKILL.md 必须声明 allowed-tools 工具权限统一可审计
禁止硬编码 Claude 专属模型别名(haiku / sonnet / opus) 改用「低成本的快速模型」「强模型」这类角色化描述,各工具按自己语境解释
正文不得点名具体子代理工具名 保持"能力优先",不绑定任何厂商实现
禁止在指令正文使用 >/dev/null 等 shell 粘合写法 这类写法在 Windows PowerShell 下会直接失败
SKILL.md 与配套文件有字节预算,description 不超过 400 字符 防止指令膨胀拖慢每个会话
每个技能必须附带 agents/openai.yaml 且字段齐全 Codex 适配器不能缺席
跨技能复制的契约代码块必须字节级一致 防止"同一份规则"在不同技能里发生漂移

这套检查把"兼容性"从团队口头约定变成了可执行的质量门禁——它不依赖任何人记得某条规矩,而是让违背规矩的改动根本进不了仓库。

状态文件化:换工具,工作不中断

跨 Agent 兼容的另一半是"状态跟着走"。skills 把工作状态全部落在文件里(scope、specs、AGENTS.md、测试),而不是聊天会话里,详见 docs/workflow-guide.md:

  • 会话断了、换了工具、换了一台电脑,新会话直接从磁盘读状态,继续上次进度
  • 阶段切换时建议 /clear 清空上下文:新会话从文件重新加载,长对话不会堆积成本

这意味着你上午可以用 Claude Code 跑 /scope 规划,下午换到 Codex 跑 /develop 构建,工作流完全无感衔接。

一行命令安装:npx skills 分发到任意 Agent Skills 客户端

skills 通过 npx skills 分发,按你使用的客户端选一行即可:

# 安装到 .claude/skills,然后重启 Claude Code
npx skills@latest add JavaScript-Mastery-Pro/skills -a claude-code

# 安装到通用的 .agents/skills,Codex 等 agent 可直接读取
npx skills@latest add JavaScript-Mastery-Pro/skills

装好后把 skills 目录提交进仓库,团队共享同一套 AI 工程实践——无论成员用哪个客户端,读到的都是同一份 SKILL.md 指令。

项目关键路径速查

常见问题 FAQ

换到另一个 agent 需要重新安装吗? 需要,但只是一行 npx skills 命令把技能装进对应客户端的 skills 目录;技能内容本身零改动,这正是"一份 SKILL.md 打天下"的意义。

openai.yaml 会让我的技能只对 Codex 有效吗? 不会。它只控制 Codex 选择器里的显示名、简介和开场提示,不含执行逻辑;删掉它,技能在其它客户端照常运行,只是 Codex 展示少了几个字段。

如何保证技能不随时间悄悄失去兼容性? 运行 npm run check 触发 check-portability.mjs:11 条规则逐文件校验,任何违规以退出码 1 失败,可以直接接进 CI 当门禁。

状态存在会话里怎么办,换 agent 就丢了吧? skills 的设计原则就是状态落盘:scope、specs、AGENTS.md 都在仓库文件里,任何新会话从磁盘重建上下文,换工具、换机器都不丢进度。

登录后查看全文
skills