同一套 Skills 跨 Agent 迁移：Claude Code、Codex、Gemini CLI 的兼容性实测-开发者社区

同一套 Skills 跨 Agent 迁移：Claude Code、Codex、Gemini CLI 的兼容性实测

【免费下载链接】claude-skills380 Claude Code skills & agent skills & plugins (30+ Agents, 70+ custom commands, 380+ skills, customizable references, scripts)for Claude Code, Codex, Gemini CLI, Cursor, and 8 more coding agents — engineering, marketing, product, compliance, C-level advisory, research, business operations, commercial & finance, and your daily productivity skills.项目地址: https://gitcode.com/GitHub_Trending/cla/claude-skills

当开发者的技能资产被锁定在单一工具里，迁移一次 Agent 就意味着重写一遍提示词与工作流——这是 Agent 工程化路上最真实的痛点。Anthropic 的 Agent Skills 规范（SKILL.md + YAML frontmatter）正试图终结这种"技能孤岛"：一套技能包能否在 Claude Code、OpenAI Codex、Gemini CLI 之间原样迁移，决定了它究竟是"单工具插件"还是"可复用软件资产"。

本文以本地仓库 claude-skills 为实测样本——它对外宣称 355 个生产级技能、602 个纯标准库 Python 工具、覆盖 13 个编码工具（README.md）。我逐行阅读了三端各自的安装脚本、同步脚本与格式转换器，用源码级证据回答三个问题：跨 Agent 技能规范到底统一到什么程度？三端实测差异在哪？迁移的真实成本与坑是什么？

一、跨 Agent 技能规范：SKILL.md 正在成为"公约数"

先说结论：Claude Code、OpenAI Codex、Gemini CLI、Hermes Agent、Mistral Vibe 五家已经事实上收敛到了同一套技能格式——SKILL.md文件加 YAML frontmatter。这套被社区称为 agentskills.io 的标准，核心结构非常克制：

--- name: skill-name description: "When to use this skill. Include trigger keywords and phrases users might say." license: MIT metadata: version: 1.0.0 category: domain-name --- # Skill Name ## Before Starting ## How This Skill Works ...

仓库根目录的 SKILL-AUTHORING-STANDARD.md 把这份模板固化为所有技能的"DNA"：frontmatter 只负责声明（name、description、license、metadata），正文负责指令与决策框架。以实际的工程技能为例，engineering/skills/changelog-generator/SKILL.md 的 frontmatter 只有两行核心声明，正文则完整承载了 Conventional Commits 解析、语义化版本推断、Keep a Changelog 渲染等全部方法论。

这种设计的巧妙之处在于description 字段同时承担了触发与索引双重职责。Claude Code 依据 description 的语义匹配决定何时加载技能；Codex 的同步脚本从 frontmatter 提取 description 生成索引清单；Gemini CLI 同样靠它做技能发现。技能能否跨 Agent，本质上取决于这个字段写得是否足够"机器可读"——它既是门面，也是兼容性的第一道关卡。

仓库的领域编排也为此做了铺垫。scripts/sync-codex-skills.py 中的find_skills明确支持三种技能发现模式：<domain>/<skill>/SKILL.md扁平模式、<domain>/skills/<skill>/SKILL.md标准模式，以及<domain>/<plugin>/skills/<skill>/SKILL.md嵌套插件模式，并按路径去重。也就是说，仓库内部本身就为"同一套技能被不同工具以不同目录结构发现"做了归一化处理。

社区对这一趋势的关注也在升温：中文社区的 Awesome Agent Skills 类合集普遍宣称技能包"兼容 Claude Code、Codex、Gemini CLI、Cursor 等主流 AI 助手"，并将"技能的可复用性、Git 可追踪性"视为核心卖点。规范统一、目录标准、描述驱动——这三件事叠在一起，跨 Agent 迁移才有了技术前提。

二、三端实测：安装、发现与激活的对照

同一套技能在三端的"手感"差异，体现在安装路径、发现机制和激活方式三个环节。以下全部来自仓库实际脚本的代码级核实。

Claude Code：插件市场原生集成

Claude Code 是技能格式的"母语者"，安装体验最顺滑，走的是插件市场路线：

/plugin marketplace add alirezarezvani/claude-skills /plugin install engineering-skills@claude-code-skills /plugin install marketing-skills@claude-code-skills

也可以直接复制技能目录到~/.claude/skills/。触发机制是描述语义匹配——Agent 读取技能时，依据 description 判断当前任务是否命中，命中才把 SKILL.md 全文加载进上下文。这解释了一个社区常见困惑：为什么技能"不触发"往往要先去检查 description 写得是否精准。

OpenAI Codex：npx 一键安装或脚本同步

Codex 走的是"索引 + 符号链接 + 实体复制"的三段式。官方推荐一行命令：

npx agent-skills-cli add alirezarezvani/claude-skills --agent codex

仓库内则提供了更可控的本地同步：scripts/sync-codex-skills.py 会扫描全部领域目录，在.codex/skills/下为每个技能建立符号链接，并生成skills-index.json清单（含 category、description，供工具链做分类统计）。随后 scripts/codex-install.sh 负责真正落地到~/.codex/skills/，它支持--all、--category <name>、--skill <name>三种粒度，并在复制时使用cp -rL跟随符号链接展开真实内容——这一步暗藏玄机，下文详述。

Gemini CLI：显式激活，另辟蹊径

Gemini CLI 的接入最特别。运行./scripts/gemini-install.sh后，scripts/sync-gemini-skills.py 在.gemini/skills/下建立符号链接树和索引，而激活方式从"语义匹配"变成了显式函数调用：

activate_skill(name="senior-architect") activate_skill(name="content-creator")

更值得注意的是，Gemini 的同步脚本把仓库的 agents 和 commands 也纳入了技能体系：GEMINI.md 明确写到，agents/下的子代理文件（如cs-engineering-lead）和commands/下的斜杠命令（如tdd）都会被同步为 category 为agent、command的技能，统一通过activate_skill(name=...)激活。也就是说，在 Gemini CLI 眼里，技能、子代理、斜杠命令被拉平到了同一个发现机制里。

三端对照汇总如下：

维度	Claude Code	OpenAI Codex	Gemini CLI
安装方式	插件市场 /`~/.claude/skills/`	`npx agent-skills-cli`/ 同步脚本	`./scripts/gemini-install.sh`
格式转换	无（原生）	无（原生）	无（原生）
发现机制	description 语义匹配	`skills-index.json`索引	`.gemini/skills/`符号链接树
激活方式	自动触发	自动/按需	`activate_skill(name=...)`显式激活
附加资产	仅技能	技能 + 分类索引	技能 + agents + commands 统一入索引

分层之外：原生标准 vs 格式转换

把视野放大到全部 13 个工具，兼容性其实是分层的。Hermes Agent 与 Mistral Vibe 采用与仓库完全相同的 agentskills.io 标准，属于"零转换"的 BYO-sync 层级，只需python scripts/sync-hermes-skills.py或./scripts/vibe-install.sh做一次符号链接同步（scripts/sync-hermes-skills.py 源码注释直言"no format conversion needed"）。

而 Cursor、Aider、Kilo Code、Windsurf、OpenCode、Augment、Antigravity 这 7 个工具则必须经过 scripts/convert.sh 的格式适配，再交给 scripts/install.sh 落地：

目标工具	输出格式	默认安装位置
Cursor	`.mdc`规则文件（`globs`/`alwaysApply`）	`<project>/.cursor/rules/`
Aider	单文件`CONVENTIONS.md`（全部技能拼接）	`<project>/CONVENTIONS.md`
Kilo Code	纯 Markdown 规则	`<project>/.kilocode/rules/`
Windsurf	`SKILL.md`技能目录包	`<project>/.windsurf/skills/`
OpenCode	`SKILL.md`+`compatibility: opencode`	`<project>/.opencode/skills/`
Augment	Markdown 规则文件	`<project>/.augment/rules/`
Antigravity	`SKILL.md`+`risk`/`source`/`date_added`	`~/.gemini/antigravity/skills/`

转换器的核心逻辑非常简洁（见 scripts/convert.sh）：用 awk 解析出 frontmatter 的name与description，正文原样透传，再按目标工具的 frontmatter 约定重新包装。这套设计保证了"指令不丢、元数据重映射"。

三、迁移的适配成本与坑

规范统一不等于零成本。逐行读脚本和文档后，我整理出六个真实的坑，它们共同决定了迁移的"摩擦系数"。

坑 1：frontmatter 解析是迁移的咽喉

convert.sh 的 awk 解析器只认name:和description:两行，而且必须出现在文件最顶部的---块内。frontmatter 缺失或字段为空，技能会被直接跳过，脚本会打印Skipping invalid frontmatter。文档也承认：使用折叠（>）或字面量（|）写多行 description 的技能，转换后可能出现描述乱码。也就是说，一个在 Claude Code 下运行良好的技能，如果 description 写法不规范，迁移时可能"静默消失"——这是迁移失败最隐蔽的形态。

坑 2：符号链接的"伪共享"陷阱

Codex 和 Gemini 的同步脚本默认建立符号链接而非复制，本意是省空间、保单一事实源。但随之而来的问题是：符号链接一旦指向绝对路径，克隆到另一台机器就全线断裂。仓库文档专门记录了这个坑：如果克隆了提交了绝对路径符号链接的分支，Hermes 会报"Symlinks point to a path on someone else's machine"。仓库的解法是 v2.7.2+ 一律生成相对符号链接，并在 codex-install.sh 中用cp -rL把符号链接展开成实体文件再落到用户目录——实体复制意味着与源仓库解耦，任何一次git pull都不会破坏已安装内容。

坑 3：扁平规则工具会丢失支持目录

这是最容易低估的适配成本。Cursor、Aider、Kilo Code、Augment 这类只支持"每技能单文件"的工具，转换时只得到 SKILL.md 正文——scripts/、references/、templates/三个支持目录全部丢失。反观 Windsurf、OpenCode、Antigravity 等支持子目录的工具，才能拿到完整技能包。以 changelog-generator 为例，它的正文明确引用了references/hotfix-procedures.md等配套文档，迁到 Cursor 后这些引用直接失效。选择目标工具前，必须先确认自己的技能栈是否强依赖 Python 脚本与参考文档。

坑 4：重名与命名空间冲突

技能迁移到新平台后，名称冲突是确定性事件。scripts/sync-gemini-skills.py 为此实现了三重消歧策略：同一目录下重名自动加-2、-3后缀；与既有技能重名的 agent 文件加agent-前缀；重名的 command 加cmd-前缀。而 Hermes 侧则用~/.hermes/skills/claude-skills/子目录做命名空间隔离，避免覆盖其内置技能。即便是这样，斜杠命令仍可能碰撞——文档明确记载了/research与 Hermes 内置命令冲突时，需要手动改名或用全限定路径调用的处理方式。

坑 5：嵌套结构的扁平化

仓库内部大量技能采用engineering/caveman/skills/caveman/SKILL.md这种嵌套插件布局。Hermes 等工具要求 SKILL.md 位于技能目录顶层，同步脚本必须把嵌套结构压平为claude-skills/<domain>/<skill>/SKILL.md。如果某个技能在同步后"找不到 SKILL.md"，十有八九是符号链接指向了错误层级，重新运行同步脚本即可。这提醒我们：技能仓库的内部目录结构，本身就是为兼容多工具发现机制而设计的产物，而非随意的文件摆放。

坑 6：更新与版本兼容

跨 Agent 迁移不是一次性动作，后续的同步更新才是常态成本。标准操作是git pull origin main后重跑同步脚本或convert.sh + install.sh。仓库在 README.md 中承诺语义化版本管理："patch 版本内不改动脚本参数、插件源路径和 SKILL.md 结构"，这意味着跨 Agent 维护的长期稳定性是有约束保障的，而非口号。

综合评估：三端（Claude Code / Codex / Gemini CLI）作为 SKILL.md 原生阵营，迁移成本极低——零格式转换，只付出"同步 + 索引 + 符号链接"的适配代价；真正的成本集中在扁平规则工具（丢失支持目录）、frontmatter 规范性和符号链接管理上。

结语

回到开头的问题：同一套 Skills 能否跨 Agent 迁移？实测答案是可以，但"可以"的程度有清晰的梯度。SKILL.md 标准已经为 Claude Code、Codex、Gemini CLI 等主流工具提供了公约数，技能资产的跨平台复用从"手动翻译提示词"进化到了"同步脚本一键落地"；同时，description 驱动的触发机制、符号链接的生命周期管理、支持目录的保留策略，构成了迁移的真实摩擦面。

对技能作者而言，最务实的结论是：把 description 当作接口契约来写，把 frontmatter 当作公共 API 来维护——因为它在每一个目标工具里都被解析、被索引、被触发。一套规范的 SKILL.md，就是一套能同时在十三个 Agent 里工作的软件资产。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考