GeminiDesktop GeminiDesktop
教程指南

Claude Code skills 迁移到 Gemini：一键把 SKILL.md 变 Gem

发布于 · 作者： GeminiDesktop Team

Claude Code skills 迁移到 Gemini：一键把 SKILL.md 变 Gem

结论先行： 如果你在 Claude Code 里攒了 30 个 skill（包括代码审查、commit message、博客写作、AEO 审计之类），换到 Gemini 不需要重写，也不需要复制粘贴。GeminiDesktop 会自动扫描 ~/.claude/skills 和 project/.claude/skills 两级路径，把每一个 SKILL.md 的 YAML frontmatter 和正文映射成对应的 Gem（Gemini 的自定义 Agent 容器），name、description、system_prompt 一一对齐。

一句话概括： 把 SKILL.md 当作“跨 Agent 的 prompt 源代码”，Claude Code / Cursor / Gemini 三端都能消费同一份内容。

你已经写了 30 个 skill —— 换 Gemini 不等于推倒重来

2024 年 Agent Skills 协议发布后，Claude Code 用户迅速积累了大量自定义 skill：/commit、/review-pr、/blog-writer、/improve-aeo-geo…… 一旦积累到 30 个以上，“换一个 Agent 就要重写全部 prompt” 成为一个真实的切换成本。

但其实 skill 的核心价值不在于绑定某个 Agent runtime，而在于 那一段经过反复迭代、形成可执行操作手册的 Markdown 文本。这段文本可以被 Claude Code 当 slash command 调用，也可以被 Cursor 当 .cursorrules 片段引用，理论上也可以被 Gemini 当 Gem 的 system_prompt 注入。

关键问题是：中间需要多少“手工翻译”？我们在 Gemini Desktop 里把这件事做成了开箱即用的扫描 + 自动映射——零配置、零复制粘贴。

Claude Code skill 结构回顾

先快速过一遍 Claude Code skill 的标准结构（Anthropic 官方规范，2024 年 8 月定稿）：

---
name: review-commit-push
description: Review code, commit with context, and push with type-check auto-fix
allowed-tools: Bash, Edit, Read, Grep
---

# Review Commit Push

When the user asks to commit, follow this procedure:

1. Run `git status` and `git diff --staged`
2. Analyze changes and draft a conventional commit message
3. ...

核心字段：

字段 来源 语义 迁移到 Gem
name YAML frontmatter slash command 名 + Agent 内部标识 映射到 Gem name
description YAML frontmatter 触发词、一句话说明 映射到 Gem description
allowed-tools YAML frontmatter 允许调用的工具白名单 当前仅记录，不自动转发（下文详解）
正文 Markdown frontmatter 之后的全部内容 操作手册、规则、示例 映射到 Gem system_prompt

正文部分往往是几百到几千字的 prompt 文本，包含检查清单、决策树、代码模板等。这正是 “迁移到 Gemini 最值得自动化” 的部分。

GeminiDesktop 扫描路径：~/.claude/skills + project/.claude/skills

GeminiDesktop 启动时会按以下顺序扫描 skill 路径（两级 fallback）：

  1. 全局路径：~/.claude/skills/*/SKILL.md —— 用户个人积累的通用 skill（如 /commit、/review）
  2. 项目路径：<cwd>/.claude/skills/*/SKILL.md —— 当前项目特有的 skill（如 BibiGPT 自己的 /topic-finder、/blog-writer）

两级合并后，项目路径优先级更高（同名 skill 会用项目版覆盖全局版），这与 Claude Code 本身的行为保持一致。扫描是增量的——GeminiDesktop 会记住每个 SKILL.md 的 mtime，只有文件被修改后才重新导入。

导入后的 Gem 列表直接出现在 Gemini 对话框的 “/” 下拉里，用户体验与原生 Gem 一致。

导入规则：name / description / body → Gem system_prompt

自动映射的具体规则如下：

SKILL.md 字段 Gem 字段 变换规则
name: review-commit-push Gem name: review-commit-push 原样保留
description: ... Gem description 原样保留，最多 512 字符
正文 Markdown Gem system_prompt UTF-8-safe 截断到 32KB，确保不截在多字节字符中间
allowed-tools Gem 元数据 tags 仅作为 tag 展示，不自动绑定 MCP tool

32KB 截断的理由： Gemini 2.5 Pro 的 system instruction 硬上限是 32KB。对 99% 的 skill 来说这远远够用（SKILL.md 的中位数大约 6-8KB），但个别把大量示例塞进 prompt 的 skill 可能会超——GeminiDesktop 在截断时会在末尾插入 [...truncated at 32KB, original file at /path/to/SKILL.md]，让你知道截了就能手动精简。

UTF-8-safe 截断：中文/日文/韩文字符在 UTF-8 下占 3 字节，粗暴的字节截断会把一个字符切两半，产生解码异常。GeminiDesktop 的截断器会回溯到最近的合法码点边界，确保输出永远是合法 UTF-8。

为什么没做 MCP tool 全自动转发

技术上我们确实可以把 SKILL.md 里的 allowed-tools: Bash, Edit, Read 自动翻译成 Gemini 的 MCP tool 绑定，但我们刻意没这么做。两个原因：

原因 1：大多数 skill 隐含对 shell / git 环境的依赖

review-commit-push 假定 cwd 是一个 git 仓库，commit 假定有 husky hooks 配置，topic-finder 依赖 gcloud / gsc 命令行工具已登录。这些隐含依赖在 Claude Code 的本地 shell 环境中是默认成立的，但 Gemini 的执行环境可能完全不同（比如跑在 web UI 的沙箱里）。

如果无脑转发 Bash tool，用户会在 Gem 里调用 skill，看到它试图执行 git status 然后报错，体验比 “skill 只能当参考文档” 更糟。

原因 2：安全边界不清

Claude Code 的 allowed-tools 是一层松散的白名单，不是强制沙箱。Gemini 如果接管执行，需要重新评估每个 skill 是否真的只会做白名单内的操作，否则有潜在的数据泄露或破坏风险。这部分的工作量远超简单的字段映射。

当前做法： SKILL.md 正文被完整注入 system_prompt，Gem 知道这个 skill “应该” 做什么；但实际执行由用户手动触发，或通过 MCP server 显式配置。我们正在做的下一步是把 MCP tool 的自动绑定做成 opt-in——用户在 SKILL.md 里加 gemini-bridge: auto 才会开启。

跨 Agent 复用的最佳实践

基于上面的映射规则，我们总结了几条让 skill 更适合“跨 Agent 复用”的写作习惯：

  1. 工具依赖尽量最小化：能用纯 prompt 解决的逻辑不要依赖 bash 脚本。比如 “分析 git diff 并生成 commit message” 可以完全在 prompt 里描述规则，不需要真的执行 git diff
  2. 写成自解释的纯 prompt 段：不要假定读者“一定知道项目的目录结构”，关键上下文直接在 prompt 里讲清楚
  3. 工具名用语义描述而非具体命令：写 “run the repository’s test suite” 而不是 “run bun test”，后者在 Cursor、Gemini 等环境里可能不成立
  4. 保留 allowed-tools 字段：即便 Gemini 目前不自动转发，这个字段仍然是“这个 skill 到底会碰什么”的机器可读说明，未来的桥接工具会用上

更多 MCP server 配置 里讨论了 Claude Code / Cursor / Gemini 三端如何共享同一套 MCP server，配合 skill 复用可以把“跨 Agent 切换成本”压到最低。

BibiGPT AI 视频对话与智能溯源演示

场景：Claude Code 写代码 + Gemini 复用 video-summary skill

一个真实的使用案例：BibiGPT 的 bibigpt-skill 包提供了一个 Agent Native 的 “视频摘要” 能力，SKILL.md 里写了完整的“如何判断 URL 类型、如何选择 API、如何组装 prompt”的操作手册。

在 Claude Code 里：我开发代码时让它帮我总结一个 YouTube 视频里讲的实现思路，/video-summary https://youtube.com/... 一行搞定。

在 GeminiDesktop 里：同样的 SKILL.md 自动变成 Gem，我在浏览器里看到一个教程视频直接 /video-summary 当前页面 就能得到摘要。两边的输出格式、引用风格完全一致，因为 system_prompt 是同一份。

这就是“skill 作为跨 Agent 的 prompt 源代码”的价值——一份 SKILL.md 多端消费，你维护一份，全 Agent 生态都能用。

下一步：反向导出 + 三端同步

单向从 Claude Code 到 Gemini 已经跑通，下一步是做 反向导出 —— 如果你先在 Gemini 里设计了一个 Gem，能不能一键 dump 成 SKILL.md 导回 Claude Code？

这在技术上并不难——Gem 的 name/description/system_prompt 直接写回 YAML frontmatter 和正文就行。我们也在观察 Cursor 的 .cursorrules 格式，希望实现 “一份 SKILL.md 三端同步”。

延伸阅读：Gemini Mac 客户端缺失的 6 个功能 里盘点了 Gemini 当前相对 Claude Code 在本地化工作流上的差距，skill 迁移只是其中一环。

结语

Agent skill 不该是某个 runtime 的专有格式。SKILL.md 是知识的沉淀——你花几小时打磨出来的“审查规范”“博客写作手册”“AEO 审计表”不该因为换个 Agent 就作废。GeminiDesktop 的自动扫描 + 映射只是第一步，目标是让你的 skill 库真正 “Agent runtime 无关”。