大家在工作里用 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 项目好用得多。