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

时间：2026-07-08 08:47:55 编辑：袖梨来源：一聚教程网

写出好用的skill，关键在于理解模型如何按需加载信息，避免信息过载。
核心内容：
1. 定义skill的本质与作用
2. 剖析skill“渐进式加载”的核心机制
3. 构建完整skill文件夹的实践方法

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

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

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

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

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

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

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

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

为什么 skill 好用：关键在「渐进式加载」要理解 skill 为什么有效，得先理解大模型的一个软肋。

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

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

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

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

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

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

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

一个完整的 skill 都包含什么它的结构大致长这样：

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

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

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

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

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

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

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

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

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

博客链接：https://claude.com/blog/lessons-from-building-claude-code-how-we-use-skills你觉得一个 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 项目，好用得多。