聊聊 .agents：Codex、Claude Code、Cursor 之间的 Skills 兼容性

这两天我在本机里注意到了一个目录：~/.agents。

打开一看，里面是一个非常熟悉的结构：

~/.agents/
  skills/
    frontend-design/
      SKILL.md
    git-commit/
      SKILL.md

第一反应很自然：

这是不是某种通用的 Agent 规范？如果我写一套 skills，是不是 Codex、Claude Code、Cursor 都能直接吃？

答案是：

方向上越来越接近“通用”，但现实里还没有通用到可以完全无脑互换。

这篇文章就聊清楚三个问题：

~/.agents 到底是什么
SKILL.md 为什么越来越像跨客户端的共同格式
Codex、Claude Code、Cursor 真正的兼容差异到底在哪

先说结论：它更像“开放约定”，不是“统一标准”

如果你去看本地的 skill 文件，大概率会发现两件事：

每个 skill 都是一个独立目录
核心入口是 SKILL.md

有些 skill 里还会附带：

reference/ 文档
示例代码
辅助脚本
模板文件

这说明它本质上不是一个“只写 prompt 的文本片段”，而是一个更接近“可复用能力包”的东西。

但这里要注意一个非常重要的区分：

SKILL.md 是技能描述格式
~/.agents 是某些客户端约定会去扫描的目录

这两层不要混在一起。

很多人会误以为：

只要目录叫 .agents，所有 Agent 客户端就都会自动识别。

其实不是。

更准确地说法应该是：

越来越多客户端开始接受 SKILL.md 这套组织方式，但“从哪个目录加载、怎么触发、能绑定哪些工具”，各家还不完全一样。

为什么说 `SKILL.md` 正在变成共同语言

这两年 Agent 产品一个很明显的趋势，就是大家都在试图解决同一个问题：

怎么让模型别每次都从零开始，而是能按任务加载稳定、可复用、可维护的专业能力。

于是 skills 这种形态就很自然地出现了。

它通常包含几部分：

这个 skill 适合什么场景
什么时候应该触发
具体工作流怎么走
允许或偏好使用哪些工具
还可以补哪些参考资料

而 SKILL.md 的好处，在于它足够简单：

人能直接读
模型也容易消费
Git 友好
非常适合跟脚本、模板、文档一起放在目录里管理

所以从生态演进上看，它很像一种正在形成共识的“技能封装格式”。

但这不等于所有产品已经做到完全兼容。

真正的差异，不在 skill 内容，而在“加载机制”

如果你只看 skill 目录本身，会很容易觉得三家差不多。

真正一上手，差异主要出在下面这几层。

1. 扫描目录不同

这是最先踩坑的地方。

同样是一份 SKILL.md：

在一个客户端里，~/.agents/skills 可能会自动生效
在另一个客户端里，它可能只认项目内目录
还有一些客户端会更偏向自己的专有目录名，比如 .claude/... 或 .cursor/...

所以如果你问：

~/.agents 是不是行业统一目录？

我会说：

不是。它更像一个跨工具社区里逐渐流行起来的目录约定。

目录兼容性通常没有“文件格式兼容性”那么强。

2. 触发方式不同

有些客户端是：

你显式提到 skill 名称，它才加载

有些是：

根据描述自动匹配

还有些会混合：

既支持显式点名
也支持根据上下文推荐或自动触发

这意味着同一个 skill，在不同客户端里即使“被识别”，也不一定“被同样地调用”。

3. 工具绑定能力不同

这点特别关键。

一个 skill 不只是写“请你这么做”。

很多客户端还会让 skill 和工具生态产生关系，比如：

Bash
Git
Browser
Computer Use
MCP 工具
第三方插件

问题在于，不同客户端的工具模型完全不同：

工具有没有权限分级
能不能声明允许工具
能不能约束命令范围
能不能接插件或 MCP

这些差异会直接决定：

同样一份 SKILL.md，在 A 客户端里是“真能力包”，在 B 客户端里可能只是“高级提示词”。

4. Frontmatter 字段容忍度不同

有些 skill 会在头部加：

---
name: git-commit
description: ...
allowed-tools: Bash
---

有些客户端会读取这些字段。

有些客户端即使不严格消费，也能把它当作普通元信息忽略掉。

所以一般来说：

name
description

这类基础字段兼容性最好。

但更进一步的字段，比如：

allowed-tools
更细的权限声明
客户端私有扩展字段

就不一定是通用能力了。

那 Codex、Claude Code、Cursor 该怎么理解

如果只从“工程使用感受”出发，我会这么总结。

Codex

Codex 对 skills 的支持已经比较自然了。

尤其是当它把 ~/.agents/skills 或其他本地 skills 目录纳入会话上下文后，你能明显感觉到：

skill 是一等公民
skill 可以和工具、插件、权限模型联动
不只是“贴一段提示词”

也就是说，在 Codex 里，skills 通常更像可操作的工作流模块。

Claude Code

Claude Code 很早就在推 skills 这类工作方式，它对 SKILL.md 的理念影响也很大。

但从使用上要区分两件事：

它支持 skills，不代表它一定默认扫描 ~/.agents
它有自己的目录和工作流约定

所以我会把 Claude Code 理解成：

对 skill 理念支持很强，但目录约定不一定和别家完全一致。

Cursor

Cursor 这两年的方向也越来越明确：开始把 Agent 技能、自动化上下文、项目级复用能力收进自己的体系。

但 Cursor 的问题通常不是“有没有 skill”，而是：

这个版本到底认哪些目录
是全局加载还是项目加载
它把 skill 当作多强的一层能力

因此对 Cursor 来说，更实用的思路不是问：

它支不支持 SKILL.md？

而是问：

它当前版本会从哪里找 skill，以及找到之后会用多深。

所以 `~/.agents` 只支持 skills 吗

如果从你当前目录内容看，答案几乎是：

对，你现在看到的核心内容就是 skills。

但如果从“它能承载什么”来理解，skills 又不只是一个孤零零的 Markdown 文件。

一个完整的 skill 往往会带着这些东西一起工作：

SKILL.md
参考资料
模板
局部脚本
使用说明

所以说它“只支持 skills”没错，但这个 skills 本身已经是一个小型能力包，而不是一句 prompt。

如果你真想做跨客户端复用，最稳的做法是什么

如果你的目标是：

一份 skill，尽量在 Codex、Claude Code、Cursor 之间都能复用

我会建议你按下面的思路写。

1. 把 `SKILL.md` 写得尽量朴素

优先保留最稳定的部分：

name
description
明确的触发条件
清晰的 workflow
尽量少依赖客户端私有语法

这样即使某些字段不被消费，至少正文还能工作。

2. 把“能力”写在目录里，不要全塞进 prompt

比如：

参考文档放 reference/
模板单独存文件
示例命令直接写清楚

这样迁移到不同客户端时，最多是“入口不一样”，而不是整份 skill 都要重写。

3. 把工具声明当成“增强项”，不是“基础项”

如果一个 skill 离开某个私有工具字段就完全不能工作，那它的可迁移性会非常差。

更好的方式是：

没有工具声明时，也能当成流程说明运行
有工具声明时，再获得更强的自动化能力

4. 把目录适配当成最后一层

真正的复用顺序应该是：

先保证 SKILL.md 内容可迁移
再处理不同客户端的目录约定
最后按客户端补专有增强

不要一开始就把 skill 绑死在某个目录名上。

一个我自己觉得很实用的判断框架

以后你看到一个 Agent 客户端支持 skills，可以直接问四个问题：

它认不认 SKILL.md
它默认扫描哪些目录
它是怎么触发 skill 的
它能不能把 skill 和工具权限联动起来

如果只满足第 1 条，那它更像“能读 skill 文本”。

如果四条都满足，它才更像“真正支持 skills 体系”。

这个区分很重要，因为它决定了：

你是在写可执行工作流
还是只是在写更高级的 prompt 模板

最后的结论

回到最开始的问题：

~/.agents 是不是一个通用 agent 规范？

我的答案是：

不是严格意义上的统一标准，但它代表了一套正在被越来越多客户端接受的开放约定。

而 SKILL.md 本身，确实正在变成不同 Agent 产品之间最像“共同语言”的那一层。

如果你要追求兼容性，别把注意力全放在 .agents 这个目录名上。

更值得关注的是：

SKILL.md 是否写得足够通用
skill 是否和目录、工具、权限过度耦合
当前客户端到底把它当“提示词”还是“能力包”

想明白这三个问题，基本就不会被“看起来都支持 skills”这件事误导了。