今天折腾小宇宙播客下载转文本的技能，我又踩到一个老问题：脚本本身不难，难的是让 Codex、Claude Code、Cursor 都用同一套规则运行。

我本地同时用这几个 Agent。如果每个 Agent 都有自己的一份 skill，很快就会分叉。今天改了 Codex，Cursor 可能还在读旧版本。最后你以为自己维护的是一个技能，其实是三份影子。

这次 xiaoyuzhou-audio-download 的路径问题，就是一个真实例子。

1. 不硬共享目录

一开始最自然的想法，是让所有 Agent 共用同一个 skills 目录。

但后来发现不稳。

不同 Agent 的 Skill Spec 不完全一样。有的有自己的 frontmatter，有的有自己的权限模型，有的还有内置系统 skill。强行共享一个物理目录，短期看省事，长期看会把兼容性问题混在一起。

所以我放弃了“硬共享目录”。

我真正需要的是统一源头，而不是统一物理目录。

2. 我的最终模型

最后我定成三层：

GitHub 仓库管源头
vercel-labs/skills 负责安装
Codex / Claude Code / Cursor 只负责使用

我只维护源仓库，不直接去各个 Agent 的目录里手改文件。

本地根目录是：

/Users/liguwe/skills

下面分两个库：

/Users/liguwe/skills/skills       # 公开技能库
/Users/liguwe/skills/832-skills   # 私有上下文库

公开库只放我自己长期维护、可以公开复用的技能，比如 PNG 压缩、二维码生成、文档翻译、小宇宙下载。

私有库放个人路径、私有流程、项目上下文。

第三方技能不搬进我的公开库。需要时从原来源安装。我的仓库只管我自己的能力。

3. 说明层用中文

后面我也定了一个小规则：自有技能的说明层默认写中文。

主要包括：

• SKILL.md
• references/
• agents/openai.yaml

但命令、参数、路径、包名、API 名称、代码不翻译。

原因很简单：skill 不只是给 Agent 看的，也是给未来的我看的。中文说明更容易快速看懂：什么时候触发、做什么、有什么限制。

4. 安装方式不纠结，但必须验证

vercel-labs/skills 可以用 copy，也可以用 symlink/link。

我一开始纠结过到底选哪个。后来想清楚了：底层是 copy 还是 symlink 没那么重要，重要的是两件事：

1. 源仓库是唯一维护入口。
2. 更新后重新安装，并用真实任务验证。

安装命令大概是这样：

npx skills add /Users/liguwe/skills/skills \
  -g \
  -a codex \
  -a claude-code \
  -a cursor \
  --skill '*' \
  -y

如果只更新一个技能，就只装一个：

npx skills add /Users/liguwe/skills/skills \
  -g \
  -a codex \
  -a claude-code \
  -a cursor \
  --skill xiaoyuzhou-audio-download \
  -y

5. 这次真正踩的坑

小宇宙下载技能在 Codex 里是对的，默认下载到：

/Users/liguwe/skills/podcast

但 Cursor 里还在走旧路径：

/Users/liguwe/832/flomo/podcast

这说明 Cursor 读到的还是旧版本。

所以我不能只看 Codex 能不能跑通，也不能只看安装摘要。最后我按这个顺序收口：

• 改源仓库里的脚本和 SKILL.md。
• 重新全局安装到 Codex、Claude Code、Cursor。
• 用真实小宇宙链接跑一遍。
• 看输出路径是否正确。
• 看下载完成后是否自动打开文件夹。

真正可靠的验证不是列表里有没有这个 skill，而是它能不能返回：

"folder_opened": true

6. 结论

这套方案不复杂，也不完美，但我觉得够稳定。

我现在只坚持几条：

第一，自己维护的技能进自己的源仓库。 第二，公开能力放公开库，私人上下文放私有库。 第三，说明层用中文，命令和代码保持英文。 第四，更新后重新安装。 第五，最后用真实任务验证。

这次折腾后我更确定一件事：

AI Agent 的能力不是靠“装很多技能”堆出来的，而是靠一套可维护的技能管理方式长出来的。

技能只是文件。真正有价值的是：我知道它在哪里维护，怎么安装到不同 Agent，出问题时从哪里查，以及下一次怎么不再踩同一个坑。