skills如何做到跨Agent全兼容:一套Agent Skills同时驱动Claude Code、Codex与Gemini CLI
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 指令。
项目关键路径速查
- 技能指令(所有客户端共读):skills/scope/SKILL.md、skills/develop/SKILL.md、skills/architect/SKILL.md
- Codex 界面适配器(展示层,无逻辑):skills/scope/agents/openai.yaml、skills/architect/agents/openai.yaml
- 跨工具兼容护栏(11 条自动规则):scripts/check-portability.mjs
- 完整工作流指南(状态文件化、安装与上手):docs/workflow-guide.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 都在仓库文件里,任何新会话从磁盘重建上下文,换工具、换机器都不丢进度。