如何写好一个 skill：从定位问题到对症下药

大家在工作里用 skill 的时候，是不是遇到过这种场景：

听说某个 skill 特别好用，跑去 GitHub 一看，star 好几千，评论区一片「神器」「效率翻倍」。你装好后满怀期待地丢了个真实任务进去，结果模型跑出来的东西，要么抓不住重点，要么纠结一堆无关紧要的格式问题，跟大家吹的完全对不上。折腾了一下午，最后默默把它删了，心里嘀咕一句：是不是我用得不对？

如果你有过这种经历，我想先说一句：大概率不是你的问题，那个 skill 多半也写得没毛病。它只是从一开始，就没打算为你而写。

那我们该如何写出一个好用的skill呢？

要讲清楚这件事，得先从 skill 到底是个什么东西说起。

简单说，skill 是一包你预先准备好、交给模型在合适时机自己取用的「专项知识和工具」。

你可以把它想象成给一个能力很强、但对你这摊业务一无所知的新人，准备的一份份「专项操作手册」。新人本身很聪明，通用的活儿都会干，但你们团队那些约定俗成的规矩、那些只有老员工才知道的坑、那套特定格式的交付物，他不可能凭空知道。于是你把这些整理成一份份手册，平时收在柜子里，等他真碰到对应的活儿，再抽出那一本来看。

skill 干的就是这件事。它把某一类操作的流程、规范、踩坑经验，连同可能用到的代码和模板，打包成一个独立的单元。模型平时不用管它，一旦遇到对应的场景，再把它「取出来」按需使用。

要理解 skill 为什么有效，得先理解大模型的一个软肋。

我们和大模型交互，靠的是上下文窗口。直觉上你可能觉得，把所有信息一股脑全塞给它，它知道得越多就答得越好。但实际恰恰相反：上下文里的信息越多、越杂，模型反而越容易出问题。该关注的重点被淹没，不相关的内容互相干扰，最后模型开始「一本正经地胡说八道」——这就是我们常说的大模型幻觉。

skill 的机制，正是冲着这个问题来的，它的核心叫渐进式加载。

模型启动时，并不会把每个 skill 的全部内容都读进上下文。它看到的，只是一份轻量的清单——每个 skill 叫什么、什么时候该用。只有当它判断「眼下这个任务正好对得上某个 skill」，才会把那个 skill 的详细内容真正读进来。需要里面更细的参考资料或脚本时，再进一步去取。

这样一来，上下文里始终只装着「当下这件事真正需要的东西」，干净、聚焦，模型自然更不容易跑偏。这也是 skill 比一份巨长的系统提示词更高明的地方：它把信息按场景拆开，用的时候才加载。

很多人对 skill 的理解，停留在「写一个 SKILL.md，告诉模型该怎么做」。Claude 团队特意点明了这个误区——skill 其实是一个文件夹，里面可以放脚本、参考代码、模板、数据，模型能去发现、读取、调用这些东西。

这个认知差，直接决定了你能写出什么层次的 skill。

如果你只把它当一段 prompt，那你能塞进去的就只有文字。但如果你把整个文件目录都当成可以调度的资源，事情就完全不一样了。需要一段固定格式的输出？放个模板文件让模型去 copy。有套取数的逻辑反复要用？写成函数库塞进去，让模型直接调，而不是每次现写。文档太长？拆成几个 reference 文件，让模型按需去读，需要哪块读哪块。

它的结构大致长这样：

暂时无法在飞书文档外展示此内容

其中 SKILL.md 的开头是这样：

暂时无法在飞书文档外展示此内容

SKILL.md 是整个 skill 的入口和大脑，也是唯一必需的组件。开头的 frontmatter 里，name 给它一个清晰的身份，description 则负责告诉模型「什么情况下该触发我」——这是模型判断要不要用这个 skill 的依据，所以要把最关键的使用场景写在最前面。frontmatter 下面的正文是核心指令，讲清这类任务怎么做、有哪些规范和坑，并且要尽量精简，因为它一旦加载就会在整个会话里占用上下文。

剩下的都是按需调用的支撑材料：篇幅长事实依据的细节拆进 reference，对照样例放进 examples，固定格式的产出物给一份 template 模板，可复用的代码塞进 scripts/。关键是要在 SKILL.md 里点名它们、说清各自装了什么，模型才会在恰当的时机去读或去执行。这套结构之所以高效，靠的正是前面说的按需加载：SKILL.md 常驻且轻量，参考资料和示例等真用上了才读，脚本只在执行时才跑——上下文里始终只装着当下真正需要的东西。这几样配合起来，skill 才从「一段提示词」变成「一套能被模型调度的工具」。

现在能找到 skill 的地方不少：像 Clawhub 这样的聚合站、Anthropic 官方的 skills 仓库、各家模型厂商陆续推出的技能商店，都是现成的来源。

但用过一圈你就会发现，很多 skill 并没有它们宣传的那么好用，或者他离你所期望的效果还有一些距离。问题出在哪？这些开源 skill，都不是为你量身定做的。你自己工作流里那些真正的麻烦——某个内部系统的怪脾气、某张表的特殊取法、你们团队心照不宣的规范——只有你自己知道。说白了，它们缺的就是个性化。

话说回来，「把自己的那部分填进去」听着轻巧，做起来才是真功夫。不管你是从模板改起，还是干脆从头写，最后都绕不开同一个问题：怎么判断一个 skill 到底好不好，又该往哪儿动手改？

这里先摆一个观念：好 skill 几乎不是一次写成的。Anthropic 前段时间发过一篇博客：《Lessons from building Claude Code: How we use skills》，里面讲到，他们内部最好用的 skill，大多是从几行字加一条踩坑起步，再一点点补出来的。所以与其纠结「怎么一次写对」，不如把它当成一个循环——先定位问题，再对症下药，跑上几轮，skill 自然就趁手了。

你觉得一个 skill「不好用」，得先知道它到底卡在哪一环，最直接的办法就是在本地跑一遍，盯着它的实际执行过程看：这个 skill 到底有没有被触发？触发之后它读了哪些文件、跑了哪些脚本？从哪一步开始跑偏的？看下来，问题基本能归成两类。

1.skill 根本没被触发

这里得先明确一点：skill 是模型自主决定要不要用的。前面说过，模型靠 skill 的 name 和 description 来判断该不该调用它。所以触发与否，取决于两件事。

一是模型本身的理解能力。这是个硬条件——如果模型连你的意图都没读懂，再好的 description 也白搭。这种情况换一个更强的模型往往就解决了。

二是当模型已经到了能力上限、手头又没有更好的模型可换时，你能动的就只剩 description。这时候要做的，是把它写得让模型更容易看懂「这个 skill 是做什么的、什么时候该用」。几条撰写参考：

• 只写「何时用」，不写「怎么做」。 description 的职责是帮模型判断要不要调用，而执行细节属于正文。把任务步骤塞进 description，既占地方又干扰判断。比如一个读 PDF 的 skill，别写成「先解析表单字段，再逐页 OCR，最后导出 JSON」；写成「用于从 PDF 中提取文本、表格或表单字段，当用户上传 PDF 并要求读取或填写其中内容时使用」就对了。
• 带上用户会自然说出口的词。 模型很大程度上靠关键词来匹配，把真实场景里的触发短语放进去。博客里就提到，他们给一个看护 PR 的 skill，直接在 description 里写上「babysit」这个触发词，模型就更容易认出它。
• 最关键的场景写在最前面。 skill 一多，清单里的 description 会被压缩（官方上限是 1536 字符），写在后面的关键词可能被直接砍掉，所以重要的话往前放。
• 提高区分度。 写清楚什么时候该用、什么时候不该用，避免它和功能相近的 skill 抢着触发。

还有一种「没被触发」是数量惹的祸：一个系统里 skill 太多，模型选起来就容易乱。一个办法是按类别把 skill 聚一聚——文档类、coding 类、报表类分开管理。任务切得越细，模型越能顺着这种树形结构去检索，越容易定位到该调哪一个。

顺便一提，如果是一个很复杂的系统，怎么发现一个 skill 长期没被触发？ Anthropic 的做法是用一个 PreToolUse hook 记录每个 skill 的使用情况，借此看出哪些很受欢迎、哪些远低于预期没人用——后者往往就是 description 没写好的信号。

2.skill触发了，但效果不好

这才是大多数人真正头疼的，也是 skill 能不能做出「个性化」的关键。Anthropic 给的一种简单的解决方案是：补 Gotchas。

什么是 Gotchas？ 直译就是「容易踩的坑」，是一份具体的避坑清单，记的全是模型在这个任务上反复犯的错。比如某张表只增不改，你要的是 version 最高那行，而不是时间最新的；又比如某个字段在网关里和在另一个服务里叫不同名字，其实是同一个值。这种坑模型永远猜不到。

放在哪？ 就写在 SKILL.md 里，单开一个「## Gotchas」小节；条目多了，也可以拆进一个单独的 reference 参考文件，在正文里指过去。

怎么生效？ 因为这些内容是 skill 正文的一部分，skill 一被触发就会随之加载进上下文，模型读到这些警告，自然会绕开那些已知的坑。它最妙的地方在于「越用越准」：每遇到一个新的失败案例，你就往清单里补一条，skill 就朝你的场景又贴近一步。这也正是它能装下「只有你才知道」的私有经验、做出个性化的根本原因。

3.如果补坑还不够，该动哪个文件

Gotchas 是最轻的一种修法——一句提醒。但有时候问题不在「少了一句提醒」，而是 reference 本身过时了、脚本有 bug，或者正文的流程压根就错了。这种时候，先别急着乱改，先判断这是哪一类问题，因为每个组件对应的是不同性质的问题：知识问题多半出在 reference，流程问题出在 SKILL.md 正文，稳定性问题该找 script。判断清楚，再对应去改。

改 SKILL.md 正文，针对流程问题。 模型走错步骤、漏了环节或顺序乱了，就把正确的流程写清楚、理顺。这里有个反直觉的点：如果某条规则你明明写了，模型却老不遵守，往往不是写得不够多，而是它被埋在一堆废话里淹没了——这正是 Anthropic 说的「别说废话」，模型本来就会的东西写进去等于没写，还把关键规则挤到了角落。该做的是精简正文、把要紧的规则提到显眼处。另一个常见的坑是「别把模型框死」：指令写得越死，skill 越脆，换个场景立马崩，所以给够信息的同时要留出让它随机应变的余地。最后还有一个最容易忽略的——你加了 reference 或 script，模型却完全不用，多半是因为 SKILL.md 里没点明它。一定要写一句「需要完整接口时看 reference.md」「用 scripts/xx.py 做这件事」，模型才知道有这东西可用。

改 reference，针对知识问题。 模型把接口、格式这类事实细节搞错，就更新或补全 reference 里对应的内容；它找不到要的信息，就说明 reference 缺了那一部分，补上；如果 reference 太长、模型读串了，就拆细、加清晰的小标题让它能精准定位。改完别忘了回头确认：SKILL.md 有没有在恰当的时机指向这份 reference。一份再完美的参考，模型不知道去读，等于没有。

改 script，针对稳定性问题。 脚本本身有 bug、输出不对，直接修；模型反复手写同一段样板，说明你缺一个脚本，补一个；模型老用错某个脚本，通常是接口太绕，简化函数、起更直白的名字、加上注释。还有一种情况值得专门记住：某件事必须每次都一模一样（比如格式校验、固定的数据清洗），与其用文字反复叮嘱，不如写成脚本交给确定性的代码——文字指令模型可能打折扣，代码不会。

这样你就有了一条完整的判断链：先看是知识、流程还是稳定性问题，定位到该改哪个文件；再看这问题该用多复杂的手段，决定是补一句话，还是写一段代码。

所以「好 skill 得自己写」这句话，不是什么自力更生的鸡汤，它有结构性的原因。skill 的本质，是把你的工作经验和判断，编码成模型能读懂、能调用的形式。别人能给你一个好骨架，给不了你血肉。

下载一个你欣赏的 skill，读懂它的结构，然后动手把它改成你自己的——从一条你今天刚踩的坑开始，明天再补一条。等它慢慢完善起来，你会发现这个其貌不扬、可能就几十行的 skill，比当初让你失望的那个高 star 项目，好用得多。