面向不写 agent 代码、但想给 AI 配一套「能力插件」的普通人。
开篇：为什么你的 skill 总不好使
如果你给 AI 写过 skill，大概率撞过这两堵墙：
第一堵墙是------AI 压根不用它。你明明写了一个"代码审查 skill"，结果让它 review 代码时，它该怎么干还怎么干，根本没翻你写的那份东西。
第二堵墙是------它用了，但做得不对。skill 是被加载了，可输出跟你想要的差了十万八千里，你只好在文档里不停加"必须""一定""禁止"，越加越长，效果却越来越玄学。
这两堵墙背后其实是同一个误解：很多人把"写 skill"当成"写一篇说明文档"------以为只要把要求写清楚、写全，AI 自然会照办。
但真相是：写 skill 更像是在给一位很聪明、但记性和注意力都有限的新同事，设计一份"会被翻开、翻开后能照着做"的工作手册。文档写得全不等于会被读，被读不等于会被执行。
讲这件事，与其干巴巴讲理论，不如找一个现成的好范本来拆。这篇文章选的范本有点特别------它叫 skill-creator，是一个"教 AI 怎么写 skill 的 skill"。
它特别在哪？它把"怎样才算一个好 skill"的方法论，直接写进了自己的实现里。所以我们可以反过来读它：它要求别人怎么做，往往正是它自己被做好的方式。这篇文章就从它身上，倒推出几条普通人也能用的原则。
我们先从最基础的两件事讲起：skill 到底是什么 ，以及它凭什么能被"读得动"。
第一章：先建立直觉------skill 到底是什么
它不是程序，是"手册 + 工具箱"
很多人第一次接触 skill，会下意识觉得它是某种"后台运行的小程序"：我装上它，AI 就多了一个功能模块，像手机装 App 一样。
这个直觉是错的，而且这个错误会让你后面写 skill 时处处别扭。
我们先把"魔法感"拆掉，说三个朴素的事实：
- skill 没有自己独立的 AI 模型，跑你 skill 的还是当前这个 AI；
- skill 没有编译器、没有运行时，不会有一段代码在那里逐行执行你的"流程";
- skill 的本体，就是几个文本文件 ------核心是一个叫
SKILL.md的 Markdown 文件，外加可选的脚本、文档、模板。
那它凭什么能"增强"AI？答案朴素到有点反高潮：
skill 的全部作用，就是在合适的时机，把一段预先写好的文字塞进 AI 的"上下文"里，让 AI 照着这段文字去做事。
"上下文"（context）你可以理解成 AI 当前对话的"工作记忆"------它此刻能看到的所有内容。skill 干的事，就是往这块工作记忆里，在对的时候塞进对的内容。
所以更贴切的类比是：
| 现实世界 | skill 世界 |
|---|---|
| 公司通讯录里每个岗位的一句话简介 | description（决定"要不要找这个人"） |
| 岗位的详细操作手册（SOP） | SKILL.md 正文（决定"具体怎么做"） |
| 手册里提到的专用工具、表格模板 | scripts/、assets/、references/ |
写 skill，本质上就是在写一份给 AI 看的岗位手册------而不是在编程。
一个真实的例子：skill-creator 被触发的那一刻
拿我们的范本举例。当你对 AI 说"帮我做一个处理 PDF 的 skill"时，背后发生的事大致是：
- AI 扫一眼当前所有 skill 的"一句话简介"，发现有个叫
skill-creator的，简介里写着"创建新 skill、改进 skill......"，跟你的需求对上了； - AI 决定"翻开这本手册"，于是
skill-creator的SKILL.md正文（486 行）被整段塞进上下文； - 接下来 AI 读到的不是什么 PDF 知识，而是一份操作流程：先问清楚你想要什么、再写草稿、再帮你验证、再迭代、最后打包。
注意这里的关键：skill-creator 没有"执行"任何代码，它只是让 AI 读到了一份 SOP，然后 AI 按这份 SOP 扮演起"skill 作者"的角色。
这就是 skill 的运作全貌。把这个直觉立住，后面所有原则你都会觉得顺理成章------因为它们本质上都在回答同一个问题：
既然 skill 就是"在对的时候塞进对的文字"，那怎么保证它在对的时候被塞进来、塞进来之后又真的有用？
这恰好引出最关键的机制：它凭什么能被"读得动"。
第二章：原理一------三层加载，决定 skill"读不读得动"
上下文是稀缺资源，不能一次全塞
上一章说，skill 的作用是"往 AI 的工作记忆里塞内容"。但这块工作记忆是有限的------它要同时装下你们的对话历史、AI 自己的思考、其他可能用到的 skill、还有你现在的问题。每一段文字都在抢这块有限的空间。
这就带来一个矛盾：
- 你希望 skill 写得足够详细，这样 AI 才知道每个细节怎么处理；
- 但如果每个 skill 都把"详细的一切"一股脑塞进上下文，工作记忆很快就爆了，AI 反而会"看不过来""记不住重点"。
skill 体系解决这个矛盾的办法，叫渐进式披露（Progressive Disclosure） ------说人话就是：分层加载，要用到了才展开。
三层加载是怎么分的
skill-creator 把内容分成三层，按"被加载的时机"区分：
第一层：name + description（名片）------永远在场
这是每个 skill 的"一句话简介"，非常短（大概几十到一百多字）。它始终待在 AI 的工作记忆里，作用只有一个：让 AI 在每次对话时都能扫到，判断"这个 skill 现在用不用得上"。
第二层：SKILL.md 正文（手册）------被选中才加载
只有当 AI 根据第一层的"名片"决定"我要用这个 skill"时，正文才会被整段读进来。这是真正的操作说明，理想情况下控制在 500 行以内。
第三层：scripts / references / assets（工具箱）------按需取用
更细的文档、可执行脚本、模板文件等，放在这一层。AI 只在确实需要时才去读其中某一个文件，平时它们安安静静躺在文件夹里，不占用工作记忆。
用一个生活场景串起来就很好懂：
- 电梯里贴的部门小纸条（第一层）：「财务找小王，报销发票对账都归他」------每个人每天都能扫一眼；
- 小王抽屉里的报销操作手册（第二层）：你真要报销了，他才把手册翻出来；
- 手册里提到的报销系统、专用表格（第三层）：手册写"金额计算请用这个 Excel 模板"，到那一步才打开模板。
没人会把整本手册和所有表格都贴在电梯里------那样谁都看不过来。skill 的三层加载，就是同一个道理。
skill-creator 自己就是这么干的
回头看我们的范本，它把渐进式披露用得很彻底：
- 主流程 （怎么创建 skill、怎么迭代、怎么打包）写在
SKILL.md正文里； - 打分的详细规则 被单独拆到
agents/grader.md，只有当 AI 真的要去给测试结果打分时，才会被提示"去读这个文件"； - 各种数据文件的格式约定 拆到
references/schemas.md，平时根本不加载，只有要手写某个 JSON 时才去查。
它的目录结构长这样：
skill-creator/
├── SKILL.md # 第二层：主流程，被触发时加载
├── agents/
│ └── grader.md # 第三层：打分细则，用到才读
└── references/
└── schemas.md # 第三层：格式规范，查的时候才读而 SKILL.md 正文里，会有这样的"指路牌"------明确告诉 AI 什么时候该去翻第三层：
需要给结果打分时，去读
agents/grader.md；要手写某个数据文件时，去references/schemas.md查准确格式。
这一句"指路牌"非常关键。渐进式披露能成立，前提是上层得讲清楚"下层在哪、什么时候去读"------否则拆出去的文件就成了没人翻的死文件。
可操作建议
如果你只想记三条，记这三条：
- 正文别贪长 。
SKILL.md尽量压在 500 行以内。太长不是"更全面"，而是会稀释重点，让 AI 在长文档里"抓不住主线"。 - 把不常用的细节拆出去。冗长的格式说明、边角案例、参考资料，统统挪到单独的文件里。正文只留主干。
- 拆出去的同时，留好"指路牌" 。在正文里明确写清楚："遇到 X 情况，去读
references/Y.md"。拆分不是把内容藏起来，而是让 AI 按需找得到。
一个简单的自检方法：写完 SKILL.md，问自己一句------"如果我是那位聪明但忙碌的新同事，扫一遍这份手册，能不能在 1 分钟内抓住'我该按几步走、细节去哪查'?"如果不能，多半是该拆了。
第三章：原理二------description 是"触发开关"，决定 skill"用不用得上"
第一堵墙的真正成因
回到开篇那个最让人崩溃的问题：AI 压根不用你的 skill。
很多人第一反应是"是不是我功能没写好"，于是回去把正文改了又改。但其实，正文写得再好都没用------因为 AI 根本没走到"读正文"这一步。
上一章讲过，决定"要不要翻开手册"的，是第一层的那张名片 ，也就是 description。AI 每次面对你的需求时，它做的判断非常简单粗暴：扫一遍所有 skill 的 description，看哪个对得上。 对不上，正文写得再精彩也不会被加载。
所以 description 不是"功能简介"那么随意的东西，它是整个 skill 的触发开关。这一句话写得好不好，直接决定你的 skill 是"随叫随到"还是"形同虚设"。
两种典型的失败
触发开关失灵，通常是两个方向：
方向一：该用却不用（学名叫 undertrigger）
描述写得太窄、太含蓄。比如你写"生成数据看板"，但用户说的是"把这个月的销售数字做成图给我看看"------字面上对不上，AI 就没触发。
skill-creator 对这个问题专门有个提醒，很有意思：它说现在的 AI 有"不爱用 skill"的倾向 ，所以建议把描述写得稍微"主动"一点。它给的对比是：
- 偏弱的写法：「如何搭建一个展示内部数据的看板。」
- 更主动的写法：「如何搭建展示内部数据的看板。只要用户提到看板、数据可视化、内部指标，或想展示任何公司内部数据------哪怕没明说"看板"二字------都应使用本 skill。」
后者把"什么时候该用我"摊开讲透了，触发率自然高。
方向二：不该用却乱用（false trigger）
反过来，描述写得太宽太泛，比如"处理各种文档"，结果用户一提到任何带"文档"字样的需求都把它勾出来，哪怕那需求其实该用别的工具。
一个反直觉的事实：太简单的任务，谁也触发不了
这里有个很多人想不到的点，skill-creator 特意点明了：
简单的、一步就能做完的任务（比如"读一下这个 PDF"），即使描述完全匹配，也可能压根不触发任何 skill。
为什么？因为 AI 判断"要不要翻手册"时，还有一层隐含逻辑：这事我自己直接做是不是更快？ 读个 PDF、看个文件，它用最基础的能力就解决了，犯不着大费周章去加载一个 skill。
只有当任务足够复杂、多步骤、或需要专门知识时，AI 才觉得"这事值得先查查手册"。
这个事实对你有个直接影响：别拿过于简单的场景去测试你的 skill 是否触发，那测不出任何东西。要用真实、有点复杂度的需求去验证。
skill-creator 较真到什么程度
普通人写到"把描述写主动点"也就够了。但 skill-creator 作为范本，把这件事做到了极致------它不靠手感，靠数据：
它内置了一整套脚本来"科学地"优化描述。流程大致是：
- 先准备一批真实的用户问法，标好"这个该触发""这个不该触发"；
- 用脚本（
run_eval.py）拿当前描述去实测------每条问法跑 3 次，算出真实触发率； - 把"该触发却没触发""不该触发却触发了"的失败案例喂给 AI，让它改写描述（
improve_description.py）； - 改完再测，反复几轮，最后选一个表现最好的版本。
它甚至给描述定了硬上限：1024 个字符 。为什么要限制长度？因为这张"名片"是要始终待在工作记忆里 的------它越长，占用的空间越多，挤占的是所有对话的空间。所以它逼你用最精炼的话讲清"做什么 + 何时用"，而不是写成一长串"这种要触发、那种不要触发"的清单。
可操作建议
你不需要那套脚本，但可以借走它的思路：
- description 必须同时回答两件事 ：做什么 （WHAT）+ 什么时候用我（WHEN）。只写功能不写场景，是最常见的错误。
- 用用户的真实说法，别用内部黑话。用户不会说"执行 PDF 文本抽取"，他会说"帮我把这个 PDF 里的表格弄到 Excel 里"。描述里多放些用户真会说的词。
- 宁可稍微主动一点。在合理范围内，把边缘但相关的场景也写进"什么时候用我"，对抗 AI"懒得用 skill"的倾向。
- 写完拿 2-3 个真实复杂场景自测：直接问 AI，看它会不会主动用你的 skill。不触发，先改描述，而不是改正文。
第四章：原则一------讲"为什么"，少用"必须"和"禁止"
把 AI 当聪明同事，而不是提线木偶
前面解决的是"读不读得到、用不用得上"。从这一章起，我们谈读到之后，怎么让它做得对。
普通人写 skill 最常见的本能动作是：堆命令。「必须用 X」「一定要先 Y」「禁止 Z」「永远不要......」满屏的"必须""禁止"，恨不得把每一步都焊死。
skill-creator 对这种写法的态度非常鲜明，几乎是直说的：满屏的大写 ALWAYS / NEVER 是一张"黄牌"。 一旦你发现自己在疯狂下硬命令，往往说明你没把"为什么"讲清楚。
它的理由是：今天的 AI 已经相当聪明，有不错的"换位思考"能力。当你解释清楚一件事为什么重要，它往往能举一反三、灵活应对；而当你只给它一条死命令，它在命令没覆盖到的边角场景就会"卡壳"或乱来。
一个对照例子
同样是要求"用某个库提取 PDF 文本"：
- 生硬的写法：「必须使用 pdfplumber，禁止使用其他库。」
- 讲理的写法：「提取文本用 pdfplumber，因为它对表格和多栏排版的处理比其他库更稳；遇到扫描件（纯图片）时它会失效，这种情况改走 OCR。」
后者多说了两句"为什么"和"什么情况下例外"，AI 拿到的就不只是一条规则，而是一套可迁移的判断依据。碰到你没预料到的扫描件，它知道该怎么办；而前者只会一条道走到黑。
例外：关键的、易错的节点，仍然要"下狠手"
讲理是默认策略，但不是说完全不用硬约束。skill-creator 自己也保留了少数全大写的强命令------而且都用在最容易被偷懒跳过、一跳过就出问题的关键节点上。
最典型的一处，是它反复强调（甚至破例用了全大写）：先把测试结果摆到人面前，再动手改 skill。因为它太了解 AI 的"坏习惯"了------AI 容易自己跑完测试、自己看一眼、自己就把 skill 改了，跳过了"让人审一下"这一步。这一步一旦被跳过，整个迭代就失去了人的把关。所以这里它不讲理，直接下死命令。
这给我们的启发是：硬约束要省着用，用在刀刃上。
默认讲道理（让 AI 理解、灵活应对），只在"一旦做错代价很大、且 AI 有倾向做错"的关键路口才下硬命令。
可操作建议
- 写完一条规则，习惯性追问一句"为什么"，把答案也写进去。
- 数一数你的
SKILL.md里有多少个"必须/禁止/一定/永远"。如果一屏好几个，回头把大部分改写成"因为......所以建议......"。 - 留 1-2 个真正关键的硬约束就好，多了就贬值了------满纸都是重点，等于没有重点。
第五章：原则二------为"用一百万次"而写，别为眼前的例子打补丁
overfit：最隐蔽的陷阱
这是 skill-creator 反复强调、也最容易被忽视的一条。
写 skill 时，你手头通常只有两三个具体例子。你拿这几个例子反复调，调到它们都完美了，就觉得"成了"。
但问题在于：skill 是要被复用成千上万次的，面对的是无数你现在还想象不到的场景。 如果你的 skill 只对手头那几个例子好使，换个说法、换份文件就翻车------那它基本没用。
这个陷阱有个名字叫 overfit（过拟合）：你以为在"改进 skill"，其实只是在"往少数样本上贴补丁"。
它的典型症状是：每遇到一个翻车案例，你就往 skill 里加一条特例------"如果遇到这种文件，就这样处理""如果用户这么问，就那么回答"。规则越加越多，skill 越来越长、越来越脆，换个没覆盖到的情况照样崩。
skill-creator 的解法
它的应对原则一句话概括：从失败里"归纳"，而不是"罗列"。
具体体现在两个地方：
其一，在改进 skill 时它明确要求：从反馈中提炼出更普遍的规律 ，而不是堆砌"这个 query 要触发、那个 query 不要触发"的清单。遇到顽固问题，它甚至建议你换个比喻、换种思路重写，而不是再加一条特例。
其二（前面提过的）描述的 1024 字符硬上限，本质上就是一道"防 overfit 的物理护栏"------它从空间上就不允许你把描述写成一长串特例清单，逼着你提炼通用表达。
可操作建议
- 每加一条规则前，问自己：「这是一条通用原则，还是只为了救眼前这一个例子？」如果是后者，警惕。
- 遇到反复修不好的顽固问题，别急着加第十条特例。退一步，换一种说法或思路整段重写------往往比打补丁更有效，成本也不高。
- 心里始终装着那句话：我写的是"给未来无数场景用的手册"，不是"给手头三个例子的答案"。
第六章：原则三------确定的事交给脚本，别让 AI 每次重造轮子
AI 擅长判断，不擅长"每次都一模一样"
AI 很适合做需要理解、判断、写作的活；但它不适合做那种"每次都该严丝合缝、一字不差"的机械活------因为它每次发挥都可能有细微差别，而有些事差一点就出错。
这类事情的正确做法是：写成脚本或模板，让 AI 去"调用"，而不是每次"现场重写"。
skill-creator 怎么做的
它把好几件"机械且要求精确"的事，都固化成了 Python 脚本：
- 格式校验 （
quick_validate.py）：检查 skill 的"名片"格式合不合规------名字是不是规范、描述有没有超长、有没有非法字符。这种检查规则固定、不容差错，交给脚本，对就是对、错就是错； - 打包 （
package_skill.py）：把 skill 文件夹打成一个可安装的.skill包，并且打包前先自动跑一遍格式校验，不通过就不让打包； - 结果聚合 （
aggregate_benchmark.py）：把多次测试结果按固定格式汇总成统计数据。
更值得学的是它的一条自我进化建议：
如果你发现 AI 在每个测试里都各自独立地写了同一个辅助脚本 （比如都写了个生成 Word 文档的小程序），那就是个强信号------应该把这个脚本写一次，固定放进
scripts/，让 skill 直接用它。
这一条特别能体现"脚本化"的价值：与其让 AI 每次重新造一遍轮子（还可能每次造得不太一样），不如造好一个轮子让它复用------又快、又稳、又一致。
可操作建议
- 审视你的流程，哪些步骤是"每次都该一模一样"的（格式检查、固定计算、套模板）？把它们脚本化或模板化。
- 哪些步骤是"需要看情况判断"的（理解需求、组织语言、做取舍）？这些才留给 AI。
- 你不会写代码也没关系------可以让 AI 帮你把这些机械步骤写成脚本，关键是意识到"这步不该靠 AI 临场发挥"。
第七章：原则四------闭环验证 + 人来把关，别凭感觉说"行了"
skill 不像代码，所以更要"测一测、看一看"
普通程序有个好处：同样的输入，永远是同样的输出，对错很确定。skill 不一样------它依赖 AI 的理解，同一份 skill，不同场景下的表现会有波动。
正因为这种不确定性，"凭感觉觉得写好了"是最危险的。你觉得好，不代表换个真实用户、换个真实场景还好。
skill-creator 把"验证"做成了它整个流程的主心骨，循环是这样的：
- 写几个真实的测试场景（用户真会这么说的话）；
- 让 AI 带着 skill 去跑这些场景；
- 把结果摆到人面前看------而不是 AI 自己看自己改；
- 根据人的反馈改进 skill；
- 重复，直到满意。
注意第 3 步------前面讲硬约束时提过，它甚至用全大写强调"先让人审，再动手改 "。这背后是一个朴素但重要的认知：AI 不适合当自己作业的唯一判官。它写的 skill、它跑的结果、它自己评判好坏------这个闭环里缺了"人"，就容易自说自话。
"轻量版"闭环
skill-creator 那套带打分、带统计的完整流程，对普通人来说太重了。但闭环的精神你完全可以低成本照搬：
准备 3 个你真实会遇到的场景，亲手让 AI 用你的 skill 跑一遍，自己看结果。
就这么简单。这一下就能暴露出"描述触发不了""输出格式不对""漏了某一步"之类的大部分问题。
关键有两点：
- 场景要真实。别用"帮我处理一下文件"这种空泛的测试，用你工作里真会发生的、带具体细节的需求。
- 人要亲自看。别让 AI 跑完自己说"看起来不错"。你才是最终标准。
不满意，就回去改 skill，再跑一遍。改的时候，记得用上前面几章的原则------讲为什么、防 overfit、该脚本化的脚本化。
第八章：反向总结------从 skill-creator 提炼的"好 skill 检查清单"
我们从一个"教 AI 写 skill 的 skill"身上，倒推出了一条完整的脉络。把它压缩成一张你写完每个 skill 都能对照的清单：
| 维度 | 自检项 | 对应原理 |
|---|---|---|
| 能被用上 | description 同时写清了"做什么 + 什么时候用我"，用的是用户真实说法 | 触发开关 |
| 能被用上 | 描述稍微主动一点，覆盖了相关的边缘场景 | 对抗 undertrigger |
| 读得动 | 正文精简（尽量 <500 行），细节拆到子文件 | 渐进式披露 |
| 读得动 | 拆出去的文件，正文里留了"什么时候去读它"的指路牌 | 渐进式披露 |
| 做得对 | 多解释"为什么"，"必须/禁止"只留在最关键的 1-2 处 | 讲理 > 命令 |
| 做得对 | 写的是通用原则，不是为眼前几个例子贴的补丁 | 防 overfit |
| 做得稳 | 机械、要求精确的步骤，写成了脚本/模板 | 确定性脚本化 |
| 靠谱 | 用 3 个真实场景亲手跑过、亲眼看过 | 闭环 + 人把关 |
如果要把这一切再浓缩成一句话，那就是：
写 skill 的本质，不是写一篇说明文档，而是替"未来无数次 AI 对话"，提前准备好一份------会被翻到、翻开后读得懂、读懂后能照着做、做出来还靠谱的------经验手册。
"会被翻到"靠 description，"读得懂"靠精简和分层，"照着做"靠讲理而非堆命令，"靠谱"靠脚本化和验证闭环。这几件事做到了，你的 skill 就不会再卡在开篇那两堵墙前面。
彩蛋：最好的范本，是它自己
最后留一个有点意思的观察。
skill-creator 教别人"怎么写好一个 skill"------而它教的每一条，恰好都是它自己被写好的方式：
- 它讲"渐进式披露"，自己就把打分细则、格式规范拆进了
agents/和references/； - 它讲"description 要精准触发"，自己就内置了一整套优化触发率的脚本；
- 它讲"确定的事交给脚本"，自己就用脚本管校验、打包、聚合；
- 它讲"验证要闭环、要人把关"，自己整个流程的主心骨就是"测---看---改"的循环。
这种"言行一致"本身，就是判断一个 skill 好不好的最朴素标准------
一份好的 skill，应该首先说服得了它自己。