我给 AI 装了个"技能包"，写重复活儿终于不用再解释了

一个让我很不爽的场景

每次让 AI 帮我做同一类活儿，我都要重新交代一遍规矩。

"写日志要带 traceId"、"部署走灰度环境别直接上生产"、"这个字段不能为空要给默认值"。第一遍说了，第二遍还得说，第三遍我已经开始烦了。

有段时间我甚至怀疑是不是自己记性太差。后来想明白了：这不是记性问题，是这东西本来就该被固化下来。

Agent Skills 是什么

说白了，就是一个文件夹，里面放一个 SKILL.md，告诉 AI 干某件具体事该怎么干。

my-skill/
├── SKILL.md          # 必须有：元数据 + 指令
├── scripts/          # 可选：可执行脚本
├── references/       # 可选：参考文档
└── assets/           # 可选：模板、资源

SKILL.md 是唯一不能缺的文件。里面分两段。

前面是段 YAML，声明这技能叫什么、什么时候该拿出来用：

---
name: roll-dice
description: Roll dice using a random number generator. Use when asked to roll a die (d6, d20, etc.).
---

后面是正文，也就是给 AI 的操作手册。

举官方那个最夸张的例子，一个掷骰子的技能，正文就一句：

echo $((RANDOM % <sides> + 1))

写完就能用了。不用编译，不用注册，不用申请什么 API。

它到底解决啥

模型再强也有三个硬伤绕不过去。

知识有截止日期。 它不知道你公司那些没写进文档的内部约定。

没有领域经验。 你团队的最佳实践只存在于老员工脑子里，没进过任何训练集。

没有项目上下文。 代码风格、架构决策、工具链版本，模型一概不知。

Skills 就是拿来补这三样的。把散落在人脑和文档里的经验，整理成 AI 能读懂的操作手册。

我觉得最漂亮的设计：渐进式披露

这个机制解决了实际问题。

假设我装了几十个技能。要是每次都把所有 SKILL.md 全塞进上下文，模型马上变笨。渐进式披露的做法是分三步走：

description 那一行因此成了整个体系里最要紧的地方。它决定技能会不会被正确触发。我为这个吃过亏，后面会讲。

跟 Prompt、MCP 怎么区分

这三个经常被混着说，但差别挺清楚的。

一句话：MCP 管"AI 的手能伸到哪"，Skills 管"AI 脑子里有没有那套流程"。

什么时候值得动手写一个

不是啥重复劳动都值得写成技能。几个信号：

你在反复解释同一件事。 最有说服力的标志是多轮对话里陷入了"解释、纠正、再解释"的循环。第三次说同一句话的时候，就该动手了。

通用模型缺特定领域知识。 模型能力够，就是缺料。像让一个高材生做设计却没给他品牌手册。

流程有明确步骤和验收标准。 一件事如果本身就有 SOP 的味道，几步、每步产出什么、怎么算做完，那它就是天然的技能候选。

反过来，如果一件事你每次做法都不一样、也说不太清，那就别硬写。写出来的 description 匹配不到，等于白折腾。

description 怎么写才灵

格式上的硬约束不多。name 只能小写字母数字和连字符，64 字符以内；description 最长 1024 字符。

但格式只是下限，真正决定触发率的是内容。三要素缺一不可：核心功能、适用场景、触发关键词。

对比一下差别：

❌ 用于处理文件、辅助文档操作
✅ 用于提取PDF文本、表格、填写表单、合并PDF文件，触发词：PDF、提取表单、合并文档

上面那句太虚，任何沾"文件"的请求都可能误触发。下面那句把干的事和关键词都摆明了，匹配精度完全不一样。

最容易踩的坑：触发词要写用户嘴里会冒出来的话。用户会说"帮我把这几个 PDF 合起来"，不会说"调用 pdf-merge 技能"。

正文怎么组织

匹配上了之后，AI 才会去读 SKILL.md 正文。这块建议写两块。

使用指引。 一步步写清楚流程，操作规则、工具用法、边界约束都列上。写的时候心里默念"一个新人照着做会不会出错"，会那就补上。

使用示例。 列几个真实用户指令的原文。这能明显降低 AI 的理解成本，让它很快认出一个指令属于哪类活儿。

我踩过的几个坑

坑一：写成了大而全。

一个技能里塞三件事，触发率必掉。拆开写。生成用例、生成脚本、执行验证，各管各的。

坑二：references 当成了垃圾桶。

那目录是给 AI 执行时按需查的，不是给人看的说明文档。塞一堆无关内容只会增加误读概率。

坑三：写完不验证。

大模型有挺明显的顺从性，你写错它可能顺着你错继续发挥。技能写完得拿真实任务跑一遍。评测先行在 Agent 工程里听着别扭，实际很管用。

坑四：description 里的触发词太"内部"。

这条我踩得最狠。我当时的写法是"执行任务工作流"，结果用户说"帮我把这个流程跑一下"就完全不触发。改成"任务工作流、跑一遍、执行流程"之后立刻就灵了。

一点自己的体会

用下来，Skills 最大的价值其实不在于省了多少 token。

真正有价值的是把"不确定"变成了"确定"。

以前让 AI 做一件有流程的事，它每次做法可能略有不同，你得每次检查、每次纠偏。写成技能之后，同样的输入，稳定给出同样的产出。对需要重复执行的事情，这是质变。

另一个体会是别指望一个技能解决所有问题。它的定位是把已经想清楚的东西固化下来。一件事如果你自己都还没想明白该怎么做，写成技能只是把混乱固化了而已。

小结