从 Claude 换到 Kimi Code，我的 skills 全丢了

• 一、Agent Skills 的开放标准，只管格式不管目录
• 二、六款 Agent 的 skill 目录地图
• 三、为什么目录分裂比格式分裂更难搞
• 四、我最后是怎么解决的
• 五、给正在选 Agent 的人一个提醒
• 六、结语
• 参考文献

本文首发地址 https://h89.cn/archives/632.html

上周我订阅了 Kimi Code。安装、登录、打开项目，一切顺利。直到我习惯性地敲出 /git-release，终端没有任何反应。

我愣了一下，以为指令记错了。又试了 /summarize-changes、/code-review，全部石沉大海。这些 skill 我都写在 ~/.claude/skills/ 里，用了大半年，怎么可能突然消失？

排查了十分钟，问题定位到了：Kimi Code 根本不读取 .claude/skills/ 目录。

这不是 bug，是设计选择。类似的目录分裂，几乎存在于每一款 AI Agent CLI 里。

1

一、Agent Skills 的开放标准，只管格式不管目录

如果你关注 AI 编程工具，应该听过 Agent Skills 这个开放标准。它定义了一个 skill 应该长什么样：

• 一个以 skill 名命名的目录
• 目录里放一个 SKILL.md
• SKILL.md 顶部有 YAML frontmatter，包含 name 和 description
• 下面是 Markdown 形式的指令内容

这个标准解决了一个大问题：skill 的内容格式不再被某一家厂商绑架。Claude Code、Codex、Gemini CLI、Hermes Agent、OpenCode、MiMo-Code……都声称支持 Agent Skills。

标准只规定了 skill 是什么，没规定 Agent 应该去哪里找 skill。

于是各家开始在自己的地盘划线：

• Claude Code：放我 .claude/skills/ 里
• Codex：放我 .agents/skills/ 里
• Gemini CLI：放我 .gemini/skills/ 里，.agents/skills/ 也能凑合读
• Hermes Agent：都放到 ~/.hermes/skills/，外部目录要单独配置
• OpenCode/MiMo-Code：我全都要，.claude/skills/、.agents/skills/、.codex/skills/、自己的品牌目录都扫
• kimi-code：只认 .kimi-code/skills/ 和 .agents/skills/，.claude/skills/ 不看

这就是我从 Claude 切到 Kimi Code 后 skills 失踪的原因。格式是通用的，目录查找路径不是。

二、六款 Agent 的 skill 目录地图

我把各家官方文档和源码翻了一遍，整理出下面这张表。

几个值得注意的细节：

Claude Code 原生支持 .claude/skills/，是这个目录的原创者。 这个目录最先由 Claude 推出，OpenCode/MiMo 后来加入兼容，但 kimi-code 不读这个目录。更关键的是，Claude 不读 .agents/skills/。如果你从 Codex 切到 Claude，skill 一样会丢。

.agents/skills/ 成了最大公约数。 Codex 把它当原生目录，Gemini CLI 把它当别名，kimi-code 把它当通用兼容目录，OpenCode/MiMo 也读它。它最接近“中立目录”的角色，但 Claude 不读。

OpenCode/MiMo 同时扫 .claude/skills/、.agents/skills/、.codex/skills/，甚至 .opencode/skills/。策略很明确：谁家的 skill 都尽量认得，降低用户迁移成本。代价是更复杂的覆盖优先级和潜在冲突。

kimi-code 的兼容性卡在中间。它读 .agents/skills/，这符合开放标准的推荐方向；但它不读 .claude/skills/。对于从 Claude 迁移过来的用户，这就是一道隐形门槛。

三、为什么目录分裂比格式分裂更难搞

格式不兼容至少能让你一眼看出问题：文件结构不一样，肯定读不了。目录分裂更隐蔽——skill 文件本身没问题，只是放错了衣柜。

这种隐蔽性带来三个实际麻烦：

1. 迁移成本被低估

很多人换 Agent 时只比较模型、速度、价格，却很少问：我积攒的 skills 能不能直接带过去？

我的 .claude/skills/ 里有十几个自用的 skill：git 工作流、发布脚本、代码审查清单、项目初始化模板。它们是我过去半年把重复劳动固化下来的工具。换到 Kimi Code 后，这些工具集体失效，等于要我重新跑一遍磨合期。

2. 多 Agent 团队需要维护多份目录

如果团队里有人用 Claude，有人用 Kimi，有人用 Codex，skill 该放哪里？

• 放 .claude/skills/：Claude 用户开心，Kimi/Codex 用户看不到
• 放 .agents/skills/：Codex/Kimi/Gemini 能读，Claude 用户看不到
• 两边都放：同步成本翻倍，版本不一致时更头大

唯一干净的方案是 symlink，但这又要求每个成员都知道自己用的是什么 Agent、该怎么链。

3. 品牌目录把用户越绑越紧

.claude/skills/、.gemini/skills/、.kimi-code/skills/、.hermes/skills/……这些以品牌命名的目录，本质上是在用户的文件系统里圈地。你存的 skill 越多，换工具时要搬的东西就越多。

Agent Skills 开放标准想要让 skill 跨工具流通，“格式统一”只是第一步。只要查找路径还是各家自己说了算，换工具的代价就会以另一种形式存在。

四、我最后是怎么解决的

解决其实很简单，只是不应该由用户来猜。

我把 ~/.claude/skills/ 下的 skill 全部复制了一份到 ~/.agents/skills/。Kimi Code 重启后，skill 列表里就出现了。

更准确地说，我做了三件事：

1. 把通用 skill 迁移到 ~/.agents/skills/。这类 skill 不依赖特定工具，放中立目录最稳。
2. Claude 专属 skill 留在 .claude/skills/。比如用了 Claude 特有 frontmatter（context: fork、allowed-tools 等）的 skill。
3. 用 symlink 桥接。在 ~/.agents/skills/ 里给通用 skill 建了指向 .claude/skills/ 的符号链接，避免未来维护两份。

如果你也用多个 Agent，我建议把 ~/.agents/skills/ 当作 skill 的“主仓库”，然后根据各家兼容情况做映射。这不算最优雅的方案，却是现实条件下最省事的。

五、给正在选 Agent 的人一个提醒

下次你评估一款 AI Agent CLI 时，除了模型、价格、响应速度，还请多问一句：

我的 skill 放在哪个目录？它能不能读我现有的 skill？

这个问题听起来很小，却能决定你未来半年是“平滑迁移”还是“重新配置”。

目前看来，各家的兼容策略可以分成三档：

• 最封闭：Claude Code，只认 .claude/skills/
• 最开放：OpenCode/MiMo，多家目录都读（.claude/、.agents/、.codex/ 等）
• 中间派：kimi-code、Codex、Gemini CLI、Hermes Agent，以自家目录或 .agents/skills/ 为主，对 .claude/skills/ 无支持

如果你是从 Claude 生态迁移出来的用户，OpenCode/MiMo 是最无缝的；kimi-code 需要你先把 skill 搬到 .agents/skills/；Codex 用户反而不会遇到我这种问题，因为 Codex 原生就读 .agents/skills/。

六、结语

Agent Skills 开放标准让 skill 的内容格式统一了，但去哪里找 skill，决定权还在各家手里。

我从 Claude 换到 Kimi Code 的经历，表面看是"skill 没加载"，背后是格式统一之后，目录查找路径成了新的换工具门槛。

希望这篇文章能帮你少踩一次坑。如果你也遇到过类似问题，欢迎分享你的迁移方案。

参考文献

本文的数据来源与事实核查：

开放标准

• Agent Skills Specification

官方文档

• Claude Code Skills 文档
• Codex Skills 文档
• Gemini CLI Skills 文档
• Hermes Agent Skills 文档

源码仓库

• OpenCode (packages/opencode/src/skill/)
• MiMo-Code
• kimi-code (packages/agent-core/src/skill/)
• Hermes Agent
• Codex