在日常工作中使用 AI skill（技能）时，你是否也曾遇到这样的场景：

听人说某个 skill 特别出色，满怀期待去 GitHub 查看，star 数量高达数千，评论区满是「神器」「效率翻倍」的好评。你安装后信心满满地投入一个真实任务，但模型输出的结果要么偏离重点，要么纠缠于琐碎的格式细节，与宣传的效果大相径庭。耗费整个下午调试后，最终只能默默卸载，心中不免怀疑：难道是我使用方法有误？

如果你也曾有过类似经历，请先放心：大概率不是你的问题，那个 skill 本身可能也并无明显缺陷。它只是从一开始，就不是为你量身定制的。

那么，究竟怎样才能创作出一个真正好用的 AI skill 呢？

要解答这个问题，我们首先需要理解 skill 的本质是什么。

什么是 AI Skill？

简单来说，skill 就是你预先整理好、让 AI 模型在适当场合自行调用的「专项知识与工具包」。

你可以将其想象成给一位能力出色但对你的业务领域毫无了解的新同事，准备的一系列「专项操作手册」。这位新人本身很聪明，能胜任通用的工作，但团队内部约定俗成的规则、只有资深员工才知晓的陷阱，以及特定格式的交付物，他无法凭空知晓。于是，你将这些内容整理成一份份手册，平时存放在柜子里，待他真正接手对应任务时，再取出相应的那本来参考。

skill 正是承担这一职责。它将某一类操作的流程、规范、避坑经验，以及可能涉及的代码和模板，打包成一个独立的单元。平时模型无需加载它，只有在遇到匹配的场景时，才会将其「取出」并按需使用。

为什么 skill 高效？关键在于「渐进式加载」

要理解 skill 为何有效，首先需要了解大模型存在的一个弱点。

人类与大模型交互依赖的是上下文窗口。直觉上你可能认为，将全部信息一次性塞给模型，它知道得越多回答得就越好。但实际情况恰恰相反：上下文中的信息越庞杂、越混乱，模型反而越容易出现偏差。本该聚焦的关键内容被淹没，无关信息互相干扰，最终导致模型「一本正经地胡说八道」——这就是我们常说的大模型幻觉现象。

skill 的机制正是针对这一问题而设计，其核心称为「渐进式加载」。

模型启动时，并不会将所有 skill 的完整内容都读入上下文。它看到的仅仅是一份轻量级清单——明确每个 skill 的名称以及何时应该启用。只有当模型判断当前任务正好匹配某个 skill 时，才会真正将该 skill 的详细内容加载进来。如果需要更细致的参考资料或脚本，则再进一步按需获取。

这样一来，上下文中始终只保留「当前任务真正需要的内容」，简洁且聚焦，模型自然更不容易偏离方向。这正是 skill 比一份冗长的系统提示词更为高明之处：它将信息按场景拆分，仅在需要时才加载。

先破除一个常见误区：skill 绝不仅仅是一个 markdown 文件

许多人对 skill 的理解还停留在「写一个 SKILL.md 文件，告诉模型该怎么做」的层面。Claude 团队特意指出了这一误区——skill 实际上是一个文件夹，内部可以存放脚本、参考代码、模板、数据等资源，模型能够自主发现、读取和调用这些内容。

这一认知上的差异，直接决定了你能创作出什么层次的 skill。

如果你仅仅把它看作一段 prompt，那么你能放入的只有文本。但如果你将整个文件目录视为可调度的资源，情况则截然不同。需要固定格式的输出？放入模板文件让模型直接复制。有反复使用的取数逻辑？写成函数库嵌入，让模型直接调用，而无需每次重新编写。文档过于冗长？拆分成多个 reference 文件，让模型按需读取，需要哪部分读哪部分。

一个完整的 skill 应包含哪些组成部分

其基本结构示意如下：

其中，SKILL.md 文件的起始部分通常如下：

SKILL.md 是整个 skill 的入口与核心，也是唯一必需的组件。其开头的 frontmatter 中，name 赋予 skill 清晰的身份标识，description 则告知模型「什么情况下应触发该 skill」——这是模型判断是否启用的依据，因此必须将最关键的使用场景写在最前面。frontmatter 之后的正文为核心指令，详细说明这类任务如何完成、有哪些规范与注意事项，并且应力求精简，因为一旦加载，它将在整个会话中占据上下文资源。

其余部分均为按需调用的辅助材料：篇幅较长的事实依据细节拆分为 reference，对照样例放入 examples，固定格式的输出提供 template 模板，可复用的代码存放于 scripts/。关键在于在 SKILL.md 中明确列出这些资源并说明各自的内容，模型才能在适当的时机去读取或执行。这一体系之所以高效，正是得益于前文所述的按需加载机制：SKILL.md 常驻且轻量，参考资料和示例在实际需要时才读取，脚本仅在执行时运行——上下文中始终只保留当下真正需要的内容。这些组件协同工作，使 skill 从「一段提示词」进化为「一套可由模型调度的工具」。

目前可以在哪些渠道获取 skill？

如今，获取 skill 的渠道相当丰富：例如 Clawhub 等聚合平台、Anthropic 官方的 skills 仓库，以及各大模型厂商陆续推出的技能商店，都是现成的来源。

然而，实际使用一圈后你会发现，许多 skill 的实际表现与宣传中存在落差，或与你期望的效果尚有距离。问题究竟出在哪里？这些开源 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 并要求读取或填写其中内容时使用」。
• 使用用户自然会提及的词语。模型很大程度上依赖关键词进行匹配，因此应将真实场景中的触发短语写入 description。博客中曾提到，他们为一个监控 PR 的 skill 在 description 中直接写入了「babysit」这个触发词，结果模型能够更准确地识别它。
• 将最关键的场景写在最前面。当 skill 数量较多时，description 在清单中可能被截断（官方上限为 1536 字符），排在后面的关键词可能被直接切除，因此重要内容务必前置。
• 增强区分度。明确说明何时应该使用、何时不应该使用，避免与功能相似的 skill 发生冲突导致多重触发。

另一种情况则是因为数量过多导致的「未被触发」：一个系统中 skill 数量过多，模型在选取时容易混乱。一个应对策略是按类别对 skill 进行分组——例如文档类、代码类、报表类分开管理。任务划分得越细致，模型越能沿着这种树形结构进行检索，从而更容易定位到应当调用的那个 skill。

顺带一提，在复杂的系统中，如何发现某个 skill 长期未被触发？Anthropic 的做法是采用 PreToolUse hook 来记录每个 skill 的使用频率，从而识别出哪些 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 项目好用得多。