skill 到底是什么
如果拿最直白的话来说，skill 不是插件，不是模型微调，也不是某种神秘黑盒。它更像一个可复用的任务包。
这个包里，通常会有几样东西：
SKILL.md- 参考资料
- 输出模板
- 辅助脚本
其中真正的核心，其实还是 SKILL.md。它负责告诉 agent，这个 skill 是干什么的，用户要给什么输入，你应该按什么顺序处理，最后输出成什么样。
截至 2026 年 4 月，OpenAI 对 Codex skill 的官方表述已经很明确了：skill 是把 instructions、resources 和 scripts 打包起来，让 Codex 能按团队偏好稳定完成任务。Anthropic 那边现在也把 Claude Code 的这套能力放到了 skill 机制里，旧的 slash command 目录还兼容，但推荐逐步迁到 .claude/skills/<name>/SKILL.md 这种结构。换句话说，这事不是临时玩具，已经是正经工作流能力了。
小白最适合先写什么 skill
别一开始就写“全能编程助手”。
这种 skill 看起来很厉害，实际最容易废掉。因为边界太大，输入太散，最后 agent 只能靠猜。你以为自己在做一个万能工具，实际做出来的是一个每次表现都不一样的 prompt 大杂烩。
更适合新手起步的，是下面几类：
- 固定格式写作
- 固定格式总结
- 固定格式排障
- 固定格式代码检查
- 固定格式发布前检查
它们有个共同点：输入清楚，步骤固定，结果也容易判断对不对。
比如：
- 给博客起草 Markdown 成稿
- 把 issue 整理成开发任务
- 根据报错日志给出排查路径
- 按项目规范做一次 PR review
- 发布前检查 frontmatter、目录、脚本和链接
说白了，skill 最适合先固化重复劳动，不适合一上来替你承包所有思考。
一个最小可用的 skill，长什么样
先看最小目录结构：
my-skill/
├── SKILL.md
├── references/
│ └── guide.md
├── templates/
│ └── output-template.md
└── scripts/
└── validate.ps1
很多人第一反应是，既然 SKILL.md 最重要，那就把所有规则全塞进去。这样短期确实省事，但后面通常会越来越乱。更稳的做法，是把主流程放 SKILL.md，把那些不需要每次都读的大块内容拆出去。
像这些东西，就很适合拆：
- 风格规则
- 输出模板
- 名词解释
- 校验脚本
- 示例文件
这样做的好处很直接。第一，主文件更短，agent 不容易被无关信息带偏。第二，后续维护也轻松，改模板时不用动主流程，改风格时不用碰脚本。
SKILL.md 应该怎么写
对于小白，我建议先老老实实写五段。
1. 这个 skill 是干什么的
别写空话。不要写什么“你是一个专业、全面、系统的助手”。这类句子几乎没信息量。
直接写任务目标，比如：
- 根据用户提供的大纲和链接，输出一篇可发布的 Markdown 博客
- 根据错误日志和代码片段，整理排查路径和可能根因
- 根据 PR diff 和项目规范，输出 review 意见
2. 用户要提供什么
这里要写输入边界。
比如博客写作 skill，就可以写：
- 必填：大纲
- 必填：链接或关键词
- 选填：目标读者
- 选填：长度和语气
这一段越清楚，后面误解越少。
3. 你要按什么步骤做
这是 skill 最关键的部分。
不要只说“分析需求并输出结果”，要把顺序写出来。比如：
- 先判断是不是依赖最新事实
- 如果依赖最新事实，先查官方文档或一手资料
- 再整理名词、日期、数字和因果链
- 最后按指定风格生成正文
- 返回前执行格式和事实检查
你会发现，真正有用的 skill，核心不是“语气多高级”，而是流程够不够稳。
4. 输出应该长什么样
这一步也经常被忽略。
如果你不写，agent 就会按它自己的理解输出。今天给你列表，明天给你散文，后天给你半成品。要想结果稳定，就得把输出格式写死一点。
比如：
- 必须带 frontmatter
- 必须包含
<!--more--> - 必须补
## 参考资料 - 必须返回最终写入路径
5. 自检要检查什么
这一段非常值钱。
因为很多结果看起来“完成了”，其实只是“生成了”。真正决定能不能直接拿来用的，往往就是最后这轮自检。
常见的自检项可以包括：
- 是否缺少必填字段
- 是否引用了没核实的事实
- 是否输出成了错误格式
- 是否偏离目标读者
- 是否把研究稿误写成了正式成稿
小白最容易踩的几个坑
把 skill 写成空泛 prompt
这是最常见的。
如果你的 SKILL.md 里充满“全面”“深入”“系统”“高质量”这种词，基本可以理解为你什么都没说。agent 看到这种内容，还是只能自己猜。
写 skill 时，真正重要的是这些：
- 什么时候要联网
- 优先查什么来源
- 哪些资料能当参考
- 哪些情况必须停下来
- 输出必须长什么样
把所有说明塞进一个文件
这事短期最省事，长期最麻烦。
一旦 skill 开始变长，你就会发现，每次改一点点东西，都要在一大坨说明里翻来翻去。更现实的问题是，agent 每次都得重新吞一大段并不总是相关的内容。
不写“不该做什么”
很多人只写“该怎么做”，不写“什么情况下别做”。这会让 agent 太积极。
比如：
- 没核实事实时，不要直接下结论
- 用户明确只要研究稿时，不要直接生成成稿
- 目标文件已存在时，不要静默覆盖
这类约束非常重要。说白了，它们决定了 skill 会不会惹事。
没有自检和落盘规则
尤其是写作类、发布类、代码生成类 skill，没有最后的检查和写入规则，结果通常就停留在“聊天窗口里看起来还行”。
一旦要落到真实仓库里，就得补上：
- 路径生成规则
- 覆盖策略
- 最小格式要求
- 写入成功后的反馈
一个比较稳的 Codex skill 开发流程
如果你准备自己动手，我建议按下面这个顺序来。
先选一件最近重复做过三次以上的事
不要选最复杂的，选最重复的。
比如：
- 写博客初稿
- 做 PR review
- 整理 issue
- 检查发布物
这类任务最容易看到收益。
先写最小版 SKILL.md
先别追求漂亮，先让它能跑。
最小版只要能回答四个问题：
- 它做什么
- 需要什么输入
- 按什么步骤做
- 最后交付什么
拿真实任务跑两三轮
这一步不能省。
你要看的不是“它有没有输出内容”，而是：
- 有没有误解输入
- 有没有跳步骤
- 有没有乱用旧经验
- 输出是不是能直接拿来用
skill 的价值，不在于生成一段文字，而在于减少你重复解释和返工的次数。
把高频重复说明拆出去
等你发现某段说明经常改，就别继续堆在主文件里了。
把它拆到：
references/templates/scripts/
让主流程只保留决策逻辑。
最后再补失败约束
也就是：
- 哪些情况不能继续
- 哪些情况必须联网确认
- 哪些情况只能给草稿，不能直接落盘
这一步补完之后，skill 才开始像一个能长期复用的东西。
如果这个 skill 要迁到 Claude Code，需要改什么
先说结论：能迁，而且如果你本来就写得规矩，改动不会特别大。
但这不等于“复制过去就完事”。真正要改的，主要是运行环境相关的那一层。
第一，目录位置要改
如果你现在在 Codex 这边用的是自己仓库里的 skill 目录，比如 .agents/skills/<name>/SKILL.md，那迁到 Claude Code 时，通常要改成：
.claude/skills/<name>/SKILL.md
这是目前 Claude Code 官方推荐的项目级 skill 位置。旧的 .claude/commands/*.md 还兼容，但官方已经明确更推荐 skill 目录结构，因为它更适合同时带参考资料、模板和脚本。
换句话说，迁移时第一件事不是改 prompt，而是先把目录放到 Claude Code 能识别的地方。
第二，调用方式要改
Codex 这边的 skill 调用，可以是自动，也可以是显式点名。在一些工作流里，甚至会直接写成 $skill-name 这种形式。
到了 Claude Code，显式触发通常更接近 slash command 的用法，也就是：
/skill-name
所以如果你原来的 skill 文档里写了很多 Codex 专属的调用说明，迁过去时要一起改掉。不然不是 skill 本身坏了，而是入口已经不对了。
第三，把 Codex 专属术语换成 Claude Code 的术语
这是最容易漏的地方。
比如你原来的 skill 里，如果隐含依赖了这些东西：
- Codex 的 team config
- Codex 专属工具名
- Codex 的权限规则
- Codex 的技能自动发现方式
迁到 Claude Code 时，就要换成它自己的语境：
CLAUDE.md.claude/settings.json.claude/agents/.mcp.json- Claude Code 的权限与 MCP 配置
说白了，Markdown 文件本身好迁，真正难迁的是运行时假设。
第四，补上 Claude Code 特有的配置点
如果你只是想“能用”，前三步其实已经差不多了。
但如果你想“用起来顺”，还得再补一点 Claude Code 特有的东西。比如 frontmatter 配置、是否允许自动触发、是否显式触发优先、是否配合 subagent 使用。
Claude Code 现在这套 skill 机制，已经不只是一个静态 prompt 文件了。它可以结合子代理、MCP、项目设置和按需加载文件来工作。所以如果你原来的 Codex skill 是个特别大的单文件，迁过去之后，通常值得顺手拆细一点。
哪些 skill 最适合双端复用
不是所有 skill 都值得同时维护 Codex 和 Claude Code 两个版本。
最适合双端复用的，通常是这些：
- 写作类
- 文档整理类
- 研究总结类
- 规范检查类
- 流程执行类
因为它们的核心是流程约束，不太依赖某个平台的专属工具。
最不适合直接复制的，通常是这些：
- 强依赖平台专属工具调用的
- 强依赖自动发现目录的
- 强依赖权限模型的
- 强依赖某个内置 prompt 行为的
这类 skill 不是不能迁，只是迁完以后，本质上已经更像“同一个目标的两套实现”。
一个比较稳的迁移思路
如果你手上已经有 Codex skill，我建议这么做。
- 保留原版，不要直接覆盖。
- 复制一份到
.claude/skills/<name>/SKILL.md。 - 把调用语法、目录约定、工具名改成 Claude Code 的说法。
- 把通用逻辑和平台逻辑拆开。
- 用两三个真实任务回归测试。
不要一边迁一边大重构。这样最容易把问题搅在一起，最后你自己都说不清到底坏在哪。
说到底，skill 开发最重要的不是高级，而是稳定
很多人第一次写 skill，总想着一步到位，做一个又聪明又全面的东西。
但真正能留下来的 skill，通常都不花哨。它只是把一件高频小事做稳了。输入稳定，步骤稳定，输出稳定，出错时也知道该停下来。你下次再用的时候，不用重新解释半天，也不用担心它突然换了一套做法。
这事看起来不炫，但很值钱。
因为 agent 真正替你省下来的，不是一两次灵感爆发，而是那些原本要反复解释、反复返工、反复检查的小动作。把这些小动作固化成 skill，本质上就是在给自己做接口。
先别想着写一个万能 skill。先写一个你明天还愿意继续用的版本，这就够了。
参考资料
- OpenAI, Introducing the Codex app: https://openai.com/index/introducing-the-codex-app/
- OpenAI Academy, Skills: https://academy.openai.com/public/resources/skills
- OpenAI Skills Catalog: https://github.com/openai/skills
- Anthropic, Claude Code slash commands and skills: https://code.claude.com/docs/en/slash-commands
- Anthropic, Claude Code settings: https://code.claude.com/docs/en/settings