Claude Skills 实测：哪几个字段真正决定它被触发

版权与内容来源声明
本文为原创整理。文中涉及官方文档、开源仓库、论文与公开报道的内容，均在附表 A 中标注来源；引用官方原文保持原样，不作改写。文中命令、版本号与界面截图以本文成文时的实测/核验结果为准，标注「待验证」的部分请以你本地环境实际输出为判断依据。本文不推荐任何不合规的软件获取方式，也不对任何收益结果作承诺。转载请注明出处。

第 1 章 一个很常见的情形：Skill 装好了，它却不响

设想一个很具体的下午。你把自己反复用过的一套流程——比如「把一份接口文档整理成字段表，再顺手拼一份示例请求」——写成了SKILL.md，放进目录，重启会话，然后对着对话框说了一句和这套流程几乎一字不差的需求。结果模型没有用你写的 Skill，而是按自己的理解现场编了一套做法，字段名和顺序都跟你平时的不一样。

你开始怀疑：是不是正文写得太短？是不是漏了triggers？是不是必须写version和license？——因为你在网上刷到的 Skill 示例里，这些字段都出现过。

这一章先把两个概念说清楚，再把本文的数据从哪来交代清楚。

1.1 Skill 到底是什么（一句人话）

Skill 不是一个新模型，也不是一个新工具，它就是一个目录。这个目录里至少放一个名叫SKILL.md的文件。这个文件分两段：开头夹在两个横线之间的部分叫 frontmatter（用 YAML 写的元数据，你可以理解成 Skill 的「名片」），后面是正文，也就是操作手册。

Anthropic 官方文档对 Skill 的定义是：它是「打包了指令、元数据和可选资源的模块化能力」，模型在判断相关时会自动使用它。官方还有一句更口语的类比：给 Agent 写一个 Skill，就像给新同事写一份上手交接文档。

1.2 本文实测：扫了 4 个根目录、219 个 SKILL.md

本文出现的所有数字都来自本机一次只读扫描。脚本是work/2026-10-13_skills结构实测.py，输出日志是work/2026-10-13_skills结构实测.log。扫描覆盖本机 4 个 Skill 根目录（用户级 skills 目录、插件市场目录、内置插件缓存目录、以及一份内置插件源目录），一共命中 219 个SKILL.md。

先把这次实测的边界交代清楚，免得你把结论用过头：

• 它是一次截面观察，不是全网统计。它说明的是「我这一台机器上这 219 个文件长什么样」。
• 它统计的是字段有没有出现、体量有多大，不涉及「哪个 Skill 写得好」。
• 它没有统计触发成功的情况，也没有做对照实验。所以本文不会给你任何「这样写就一定被触发」的承诺。

真正有价值的地方在于：这 219 个文件里既有别人写的，也有官方和各家插件市场内置的。当大多数文件的某个字段都是空的，你至少可以问一句——这个字段真是必需的吗？

第 2 章 机制层：Skill 的信息分三次进上下文

要理解「写哪个字段有用」，得先理解 Skill 的信息是分几次、在什么时候进入模型视野的。这里先解释一个词：上下文窗口（context window），简单说就是模型这一次对话里「能同时看见」的全部文字，它是有限的，塞满了就得压缩或者丢弃。

2.1 三级加载：名片先进、手册后进、附件按需进

官方文档把 Skill 的内容分成三级，每一级进入上下文的时机都不一样。

这张表是整篇文章的地基，它解释了两件事。

第一件：启动时就进上下文的，只有那两行名片。不是整个SKILL.md，更不是目录里的其他文件。官方文档的原话是，会话启动时系统提示词里只预载每个 Skill 的name和description。

第二件：正文是在模型判断「这个 Skill 相关」之后，才被当作一次文件读取读进来的（Claude Code 里是用 bash 读取）。引用文件和脚本是更后面一层，脚本运行时代码本身不进上下文，只有输出进。

这里补一句口径提醒：官方两处材料给出的 token 估计并不完全一致（另一篇官方工程博客把元数据的量级写成约 50 tokens、完整SKILL.md约 500 tokens）。所以本文只取它们共同支持的定性结论——名片很小、手册中等、附件按需，不把这些数字当成精确值引用。

2.2 为什么这套设计要分成三级

不分成三级会怎样？你可以自己算一下本机的比例。

本机 219 个SKILL.md里，所有description字段加起来是 45710 字符；而所有SKILL.md全文加起来是 1676939 字符。全文是「名片」的约36.7 倍。

这个 36.7 倍要按字符看，请不要把它换算成 token 当成实测值——我没有在本机做过分词计量。它想说明的事情非常简单：如果启动时把全文都塞进上下文，那要常驻的是 1676939 字符这个量级的东西；而只放名片，常驻的是 45710 字符这个量级。前者大约是后者的 36.7 倍，差的是一个多数量级。

再叠一层：每个 Skill 目录里还可能有引用文件和脚本。按官方文档的说法，一个 Skill 能带几十个引用文件，任务只用得上其中一个，其余的在磁盘上待着、不产生任何开销。所以「36.7 倍」只是最保守的一层差价。

这就是「按需加载」这四个字的实际含义，也是本文后面所有判据的前提。

第 3 章 字段分布实测：真正近乎全覆盖的只有两个

3.1 出现频次：name 与 description 之外，全是长尾

本机 219 个文件的 frontmatter 字段出现次数如下（同一文件出现重复字段不重复计数）：

这张表最值得看的是断层：description和name都在 200 以上，第三名version直接掉到 68，再往下全是个位数到二十几。

也就是说，「大家都写的字段」在本机只有两个。其余字段——包括看起来很关键的triggers——出现在不到十分之一到三分之一的文件里。如果triggers是必需项，另外 200 个文件早就该集体失效了。它们写法各不相同，说明这些字段是可选扩展。

3.2 必填与可选的判定

我把官方口径和本机覆盖放在一起对照：

判定依据有两处一手来源。官方帮助中心写得很直接：SKILL.md的 frontmatter必须包含两个字段——name（友好名称，最多 64 字符）和description（说明这个 Skill 做什么、什么时候用，最多 200 字符），并且明确说description「很关键，模型用它判断何时调用你的 Skill」；其余字段属于可选。官方工程博客说法一致：文件必须以 YAML frontmatter 开头，其中包含必需的元数据name和description。

所以：name和description是必填，其余都是可选。triggers、inputs、outputs、alwaysApply这类字段名，在官方的必填/可选说明里根本没有出现，它们是不同宿主、不同插件市场各自加的写法。不要把可选字段当成触发条件去补。

3.3 那为什么大家都爱写 version

因为「有没有这个字段」和「这个字段有没有用」是两件事。version在版本管理和插件市场展示上有用，license在你把 Skill 分享出去时有用，author在多人协作时有用。它们解决的是分发与协作问题，不是触发问题。一个 Skill 只写name+description+ 正文，照样能被触发。

这里还有一个值得记下来的细节：官方帮助中心给的description上限是 200 字符，而本机最长的description是 945 字符。差这么多，只能说明一件事——同名字段在不同宿主上的规范并不统一。所以你从某篇文章或某个仓库抄来的字段写法，未必适用于你正在用的那个宿主。抄字段之前先确认它属于哪个生态。

下面是一个「扩展写法」长什么样子的示例，注意它依然只是把必填的两个字段写好，其余都只是附带：

name:api-doc-to-fieldsdescription:把一份接口文档整理成字段表，并生成一份示例请求。当用户提到接口文档、字段表、示例请求、参数说明时使用。version:1.0.0author:你的名字license:MITtriggers:-接口文档-字段表inputs:-接口文档路径outputs:-字段表-示例请求

第 4 章 决定触发的其实是 description 里写了什么

4.1 长度分布：中位 149，最长 945

本机 219 个文件的两个体量指标先摆出来：description字符数最小 0、中位 149、最大 945；正文非空行数最小 1、中位 108、最大 766。

中位 149 是个很有意思的数字：它离官方给的 200 字符上限不远，说明大部分作者是在有限的长度里把信息压紧。而最小值为 0 这件事更值得说——219 个文件里存在description为空的文件（本机明细里能看到 name 也是空的行）。这类文件基本等于放弃被模型自动触发：名片是空的，模型拿什么去匹配你的请求？

4.2 只有 14/219 显式写了「触发词」小节

本机 219 个文件里，只有 14 个在文件里显式出现了「触发词」这个写法。也就是说，超过九成的 Skill 并没有用一个专门的小节去罗列触发词，而是把关键词直接写进description。

这个观察和官方说法完全对得上。官方文档对description的表述是：它是模型拿你的请求去匹配的那段文字，所以它必须同时说清这个 Skill 做什么和什么时候该用它。Claude Code 的官方文档还补了反面情形：如果描述含糊或者互相重叠，模型可能加载错 Skill，或者漏掉本来能帮上忙的那个。

把这两件事合起来，结论就很清楚了：决定「被不被触发」的是description里的关键词覆盖，而不是你有没有写triggers这个字段名。你写一个triggers列表，宿主要是不认这个字段，它就是一段普通文本；而description是官方明确说会被读进系统提示词、并被用来做匹配的那一段。

4.3 description 的差写法与好写法

下面是三组对照。「好写法」的共同结构是：先写做什么，再写什么时候用，并把用户可能说的词直接写进去。

正反两个极端的写法长这样。好写法是「动作 + 触发线索」，用户可能说的词都直接写进去：

description:>-把一份接口文档整理成字段表，并生成一份示例请求。 当用户提到接口文档、字段表、示例请求、参数说明， 或要求把文档转成可核对的表格时使用。

差写法则是堆了一串「什么都能沾一点」的词，等于没有边界：

description:帮助用户处理文档、表格、PDF、Markdown、数据、写作、代码、翻译、总结、排版、报告。

下面重点回答一个反直觉的问题：为什么description里堆无关关键词，反而更容易失效？至少有三条原因。

第一条，你的名片是和别人几十张名片一起被比较的。你堆上一串万能词，等于在多个不相关的问题上都显得「有点像」。模型的判断是有取舍的，它在这些问题上更可能选中一个真正对口的 Skill，而你这个「什么都沾」的反而被挤下去。

第二条，description是有长度约束的（官方帮助中心写的是最多 200 字符）。前面塞了不相关的词，真正有区分度的词就被挤到后面，甚至直接被截掉。你本意是扩大覆盖面，实际效果是把真正的触发线索挤没了。

第三条，官方文档已经点名了这种失效方式：描述含糊或互相重叠时，模型可能加载错的 Skill，也可能漏掉有用的那个。「含糊」和「重叠」正好是堆关键词的两个后果。

第 5 章 最小可用 SKILL.md 模板

5.1 只有三部分

按前面查到的官方口径，一个能用的SKILL.md只需要三部分：frontmatter 的name、frontmatter 的description、以及正文。下面就是完整形态（实际文件里，最上面那两行字段用一对三条短横线包成 frontmatter 块，这里为了排版只列字段本身）。

name: api-doc-to-fields description: 把一份接口文档整理成字段表，并生成一份示例请求。当用户提到接口文档、字段表、示例请求、参数说明时使用。 ## 接口文档转字段表 ### 什么时候用 用户给了一份接口文档，希望把它变成可核对的字段表和一份示例请求时。 ### 步骤 1. 通读接口文档，列出所有请求字段与响应字段。 2. 每个字段补齐：名称、类型、是否必填、示例值、说明。 3. 按字段表拼一份最小可用的示例请求。 4. 文档里没写清楚的字段，单独列一节「待确认」，不要自己补默认值。 ### 输出格式 先给字段表，再给示例请求，最后给「待确认」清单。

关于这个模板，有三点要说明。

第一，name用短横线连接的小写英文最稳妥；官方给的上限是 64 字符，别拿一整句话当名字。

第二，description里我刻意把「接口文档、字段表、示例请求、参数说明」这几个词都写了进去。这不是凑字数，是在主动覆盖用户可能说的话——触发靠的就是这种字面命中。

第三，「什么时候用」这一节写在正文里和写在description里作用不同：正文那节是给已经触发之后的模型看的，等于再确认一次判断标准；description里那句是触发之前唯一的依据，它必须自己站得住。

5.2 目录长什么样

一个 Skill 就是这样一个目录：

my-skill/ ├── SKILL.md # 必须有：frontmatter（name + description）+ 正文 ├── reference.md # 可选：只在特定场景才读的引用文件 └── scripts/ └── run.py # 可选：脚本，运行时代码本身不进上下文

reference.md和scripts/都是可选的。而且就算你写了，它们在没被引用之前也不占上下文——这正是第 2 章那套三级加载的意义。

5.3 那正文该怎么写

正文就按「你要交给一个聪明但完全不了解你业务的同事」来写：步骤要能照着做，边界要写清楚，输出格式要写死。不要写成散文，也不要写成宣传语。具体多长合适，第 6 章给参考线。

《Claude Skills 完全指南》专题：这一章的最小模板和字段判定，配套的在线知识库里有更完整的 Skill 创建全流程拆解，可以和上面的模板对着看。放在资料包里，扫码即可获取：

第 6 章 正文该写多长，什么时候该用 Skill

6.1 正文体量：中位 108 行，最长 766 行

回头看第 4.1 节那组数字里的第二项：正文非空行数最小 1 行、中位 108 行、最长 766 行；本机最长的那个正文有 26615 字符。

这组数字说明两件事。短 Skill 才是常态——一半的文件正文不超过 108 行。但长也确实能很长——766 行那个已经不是「操作手册」，而是一整套文档集了。两种都存在，说明长度本身没有硬性规定，关键看它有没有到「该拆」的程度。

我给出三条可执行的拆分判据，你对着自己的正文数就行：

• 正文超过大约 200 行，并且里面有整段只在某个子场景才用得上 → 把那段挪进第二个.md文件，正文里留一行指向它。
• 正文里出现大段「如果用户要 A 就……如果用户要 B 就……」的分支 → 这其实是两个 Skill，拆开比堆在一起更容易被正确触发。
• 正文里出现整节的字段对照表、参数表这类查表内容→ 移到引用文件，需要时再读。

反过来说，如果正文只有几十行、讲的是一件事、步骤清晰，那就没必要拆。本机中位数 108 行这个水平，就是「写得清楚但没膨胀」的样子。

6.2 什么时候该写 Skill，什么时候直接写提示词

这是比字段更前置的一个判断。先把表格摆出来：

判据可以压成一句话：这段说明是「只有这次需要」还是「以后每次都想要」？是前者，就直接写进提示词；是后者，就写成 Skill。

还有一个更细的判断：官方文档在旁边给过一条相关建议——常驻的项目说明文件建议控制在 200 行以内，把参考资料移到按需加载的 Skill 里。这句话本身就是上面那张表的一个注脚：常驻的东西要短，按需的东西可以长。

最后一个实操取舍：Claude Code 官方文档提到，只想自己手动调用的 Skill，可以在 frontmatter 里用一个字段把它对模型隐藏。截至 2026-10-13，官方口径是「默认描述在会话启动时加载、完整内容在使用时加载；仅供用户调用的 Skill 在调用前不加载任何内容」——也就是这类 Skill 在调用前的上下文代价为零。带副作用的 Skill 值得优先考虑这一档。

第 7 章 触发失败时先查什么

7.1 按这个顺序查，别一上来就改正文

很多人一发现不被触发，就去重写正文、加长步骤、补一堆字段。这是最容易白费的改法，因为触发根本不看正文。建议按下面的顺序查：

1. 文件位置与命名 2. frontmatter 能不能被解析 3. description 单独抄出来读一遍 4. 用 / 手动调用一次 5. 正文与引用文件是否存在

第 4 步是整个排查里最省时间的一步，因为它能把问题一刀切开：手动调用能跑通、但自动触发不响 → 问题在名片（description）；手动调用也跑不通 → 问题在正文或它引用的文件。很多「Skill 不生效」的困惑，卡在没有先做这个二分。

7.2 什么时候该停手

改 Skill 有个明显的收益递减点，我把它写成两条停手信号：

• 你已经把description改了三轮，还是不被触发，而且你自己也很难用一句话说清「这个 Skill 什么时候该用」→ 这不是描述问题，是这个 Skill 的边界太宽。停手，先拆成两个更窄的 Skill。
• 你的description越写越长，已经明显超过官方给的 200 字符量级 → 停手。这说明你想让它同时管好几件事，而名片越长，每件事的区分度越低。

另外，别用「多塞几个同类 Skill」来解决问题。官方已点明描述含糊或互相重叠会导致加载错、漏掉；加一个边界模糊的 Skill，等于给自己和别人的名片一起添噪声。

《Agent Skills 从入门到落地》专题：这一章的排查顺序，可以配合在线知识库里 Agent Skills 从创建到落地的完整流程一起看，先把「名片」和「手册」这两层分清楚再用。放在资料包里，扫码即可获取：

附表 A：本文引用事实与出处对照表

附表 B：术语速查表

写在最后：这篇用到的资料

写这篇文章时，把相关的官方文档和源码又翻了一遍，顺手也整理了几份配套的东西：

• 大模型学习路线图：从零基础到能自己动手做 Agent，按阶段说明每一步该学什么、哪些可以先跳过
• 《LangChain + LangGraph + MCP 智能体开发实战》视频课：7 个模块，从私有化部署、Embedding+RAG 到 MCP+Agent 全流程
• AI 大模型知识库（在线可查）：Agent Skills 从入门到落地、Claude Skills 完全指南等专题，按目录浏览即可
• 640 套 AI 大模型行业报告 + 经典 PDF 书籍：看行业落地案例和别人怎么做的时候用得上
• 大模型零基础到精通教学视频：跟着敲一遍，比只读文档快得多

资料是我自己整理的，放在下面这个码上，扫码即可获取：

添加时备注「AI」，优先通过。

资料按「先路线、再动手、最后查漏」的顺序整理好了，建议先看学习路线那一份，照着它挑一条适合自己当前基础的路径再往下看。