Skill 更像 agent 的工种手册

它先解决“做法不稳”

如果用最通俗的话来解释，我会这么说：你把一个老员工脑子里的熟练做法，整理成一份能复用、能触发、能落地的说明书，这东西就是 Skill。

OpenAI 官方文档的定义也很直接，Skill 是一类面向特定任务的能力包，里面可以放指令、参考资料，以及可选的脚本。目的不是让模型“更聪明”，而是让它在某一类任务上，按固定工作流稳定输出。

它不像普通 prompt，因为它不是一次性说两句就完了；也不像 MCP，因为它不负责连工具和数据源；更不像 AGENTS.md，因为它不是全仓库通用规矩。它更像专项 SOP，或者说工种手册。

比如：

处理 GitHub PR 评论时，先看哪些评论要处理，再问用户处理哪几条，再改代码，再反馈结果
排查 CI 失败时，先拉取 GitHub Actions 日志，再提炼失败片段，再给修复计划，批准后才动手
写博客时，先按固定文风生成标题，再补事实，再补 frontmatter，再落盘

这些事的共同点都不是“模型不知道怎么回答”，而是“模型每次做法都不一样，很容易跑偏”。这时候，Skill 的价值就出来了：把会反复发生的偏差，提前写进流程里。

MCP 接世界，Skill 定流程

这事还是得放回真实工作流里看，不然很容易讲飘。

MCP 像接口层。

官方对 MCP 的定义，是把 AI 应用连接到外部系统的开放标准。文件、本地数据库、搜索引擎、设计稿、第三方服务，这些都可以通过 MCP 接进来。所以它解决的是“接进去”。

Skill 像流程层。

OpenAI 的 Agent Skills 文档里写得很清楚，Skill 是可复用工作流的编写格式。一个 Skill 至少要有一个 SKILL.md，还可以带 scripts/、references/、assets/。Codex 会先读取它的 name 和 description，只有在判断要用的时候，才把完整说明载入上下文。这就是官方说的 progressive disclosure。

所以这两者的分工很清楚：

MCP：把能力接进来
Skill：把做事顺序定下来

拿一个很直观的例子来说，Figma 转代码这种事，如果 agent 根本读不到设计稿，那你先补的是 MCP。但如果它已经能读设计稿了，只是每次都乱写，今天先写组件，明天先切页面，后天又忘了做视觉检查，那你补的就该是 Skill。

开发 Skill，先找重复偏差

这东西真没想象中那么重。

OpenAI 官方建议先用内置的 $skill-creator，让它帮你把触发条件、范围、是否需要脚本这些骨架先搭出来。默认优先是 instruction-only，也就是先别急着上脚本，先把说明写清楚。

如果手工写，最小结构也很简单：

my-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/

其中真正必需的，只有 SKILL.md。并且这个文件至少要有两项元数据：

---
name: skill-name
description: Explain exactly when this skill should and should not trigger.
---

真正要避免的，是把 Skill 写成“我希望模型更聪明”的愿望清单。它应该回答的是更具体的问题：哪类任务会反复出现，哪一步总跑偏，哪些资料只有在这类任务里才需要加载，哪些动作必须用脚本保证确定性。

1. 先找“重复出现的偏差”

不是所有任务都值得做成 Skill。

如果你只是偶尔让 agent 干一次活，普通 prompt 就够了。真正适合抽成 Skill 的，通常是这种情况：

你已经反复说过很多次同样的话
agent 明明有能力，但执行顺序总变
每次出错的位置都差不多

说白了，不是“能力不够”，而是“套路不稳”。

2. 把 `description` 写成触发条件

这一步非常关键。

官方文档专门强调，Codex 是否会隐式调用一个 Skill，很依赖 description。所以别写“这是一个很好用的技能”，要写“什么时候该用，什么时候不该用”。

比如 gh-fix-ci 官方技能的描述就很清楚：当用户要你调试或修复 GitHub PR 检查失败时使用；重点是检查日志、总结失败原因、给出修复计划，并且在得到明确批准后再实施。你一看就知道它的边界在哪里。

3. 能靠说明搞定，就先别写脚本

OpenAI 文档的建议也很务实，除非你明确需要确定性行为或者外部工具，不然优先用说明，不要一上来就脚本化。

为什么？因为脚本一多，维护成本就上来了。

很多 Skill 一开始只需要把步骤讲明白：

先做什么
再做什么
输出格式是什么
哪些情况要停下来问用户

这已经能解决大半问题。

只有当某一步特别稳定、特别机械、特别适合自动化时，再把它下沉到 scripts/。

4. 把资料、模版和资源拆出去

Skill 写着写着，很容易变成一坨超长说明文。这时候就该拆。

SKILL.md 负责讲规则和顺序
references/ 放背景文档和查阅材料
assets/ 放模版、图标、样例
scripts/ 放能稳定执行的动作

这样做有两个好处。

第一，主文件不会越来越臃肿。第二，模型只有在需要时才加载细节，符合 progressive disclosure 这套思路。

5. 本地先用，跨项目再分发

官方文档把这件事也分得很清楚。

如果你只是给自己当前仓库用，放在 .agents/skills/ 就够了。Codex 会从仓库、用户、系统这些位置扫描技能目录。

如果你已经发现这套东西不只一个仓库能用，或者想把多个技能一起打包分发，那就别只停在 skill folder 这一层了，应该考虑 plugin。OpenAI 官方文档的原话也很明确，Skill 是工作流本身，plugin 才是更适合安装和分发的单位。

哪些场景适合

Skill 不是越多越好，它最适合的是下面几类活。

高频重复任务

你每周都会做，而且每次顺序都差不多。

比如：

处理 PR review 评论
写博客并补 frontmatter
排查 CI 失败
做发布前检查

这类活，最怕的不是模型不会，而是每次都要重新讲一遍。

有固定流程的任务

某件事就是天然有先后顺序。

比如排查问题，你就应该先看日志，再收敛范围，再提计划，再改。这个时候，Skill 特别合适，因为它能把顺序写死，减少模型临场发挥。

需要绑定专业语境的任务

有些任务不只是步骤固定，还带强约束。

比如：

只能查官方文档
必须按某个审查格式输出
必须保留团队里的既有术语
必须遵守某个仓库的写作或开发规范

这类活，如果你每次都只靠 prompt 临时说，很容易漏。

工具和流程要一起用的任务

这个场景特别典型。

不是单纯“连上 GitHub”就完了，而是连上以后，还得按某种方法去看日志、归纳问题、决定要不要修改、最后怎么反馈。也就是说，外部连接和内部流程必须一起工作。

这时候常常就是 MCP + Skill 联合出场。

哪些场景不必上

反过来也要说清楚，不然很容易什么都想做成 Skill。

一次性的随口任务

用户临时问一句，普通 prompt 往往就够了。

你只是想“接一个外部系统”

那优先考虑 MCP，不是 Skill。

你想约束整个仓库的长期行为

这更像 AGENTS.md 的活，不是 Skill 的活。

所以简单总结一下：

缺连接，用 MCP
缺流程，用 Skill
缺全局规矩，用 AGENTS.md

看几个案例就够了

概念讲再多，不如看几个真的案例。

1. `roll-dice`：最小可用的入门案例

这个案例来自 OpenAI 官方 Agent Skills 文档。

它非常小，目录里几乎只有一个 SKILL.md，让 agent 在用户要求掷骰子时，调用 PowerShell 的随机数命令。

为什么这个例子好？

因为它把 Skill 最核心的那层骨架直接露出来了：

有明确触发条件
有明确执行方式
有明确边界

它说明了一件事，Skill 不一定非得很大。只要某件事会重复发生，而且你不希望模型瞎发挥，就可以做成 Skill。

2. `gh-address-comments`：处理 GitHub 评论的流程案例

这个案例来自 OpenAI 官方的 openai/skills 仓库。

它的目标不是“连 GitHub”，而是把“处理当前分支 PR 的评论”这件事固化下来。官方版本里的步骤就很典型：

先确认 gh 是否已经认证
再拉出当前 PR 的评论和 review threads
编号并总结这些评论
让用户明确选择要处理哪几条
然后才开始修

这个例子特别能说明 Skill 的价值。

很多工程任务，难点根本不在“模型知不知道 GitHub 是什么”，而在“它会不会按对的顺序处理事情”。gh-address-comments 解决的，就是这类顺序问题。

3. `gh-fix-ci`：排查 CI 失败的工程案例

这也是 openai/skills 仓库里的官方技能。

它针对的是另一种很典型的工程任务：PR 检查挂了，要不要修，怎么修。

这个 Skill 里定义的流程也很有代表性：

先确认 gh 登录状态
找到当前 PR
拉 GitHub Actions 的失败检查和日志
提炼失败片段
先给修复计划
得到批准后才动手

这就不是“帮我看看 CI 为什么挂了”一句 prompt 能稳定搞定的场景了。因为它里面有权限、日志、外部工具、审批边界、执行顺序，这些都需要定下来。

4. 仓库私有 Skill：把团队自己的套路沉淀下来

除了官方案例，我觉得 Skill 更大的价值，其实是在私有仓库里。

比如眼前这个博客仓库里的 blog-writer，本质上就是一个很典型的 repo-scoped skill。它不负责“让模型学会写中文”，而是把这个仓库已经固定下来的文风、结构、事实核验、输出路径、落盘格式都写成工作流。

这类 Skill 往往最有现实价值。因为它不是面向所有人，而是专门解决“你这个仓库里，哪类活总在重复出现，而且总容易跑偏”。

什么时候该认真做

所以最后还是回到最实际的问题，什么时候你应该认真做一个 Skill？

我的答案是：

当你发现问题已经不再是“模型能力不够”，而是“它每次做法都不稳”的时候。

这时候继续堆 prompt，收益通常越来越低。你今天补一句，明天再补一句，最后 prompt 长得像流水账，模型还是会漏。

反而是把它整理成 Skill，把触发条件、步骤、边界、脚本、资料分开管理，效果更稳，也更能复用。

MCP 把外部世界接进来，Skill 把内部套路固化下来。

前者解决“能不能做”，后者解决“怎么稳定地做”。

这就是我现在理解的 Skill。

它不是新提示词，也不是新协议。它更像是给 agent 配工种手册：少一点临场发挥，多一点可复用的做事顺序。

参考资料

写作附记

原始提示词

提示词：AI 大模型编程，先是出现了 MCP，然后是 Skill，用通俗的写法，解释下 Skill 是什么，如何开发 Skill，什么场景适用 Skill，分别出处具体的，有代表性的案例

写作思路摘要

这次重写保留了原稿里的官方定义、MCP 边界、开发结构和官方案例，但把文章主线从“概念综述”改成“Skill 解决做法不稳”。压缩了定义式段落，强化了触发条件、重复偏差和流程边界。