Anthropic 的文档明确指出：SKILL.md 应控制在 500 行以内。但他们自己的 docx 技能实际有 590 行。我在构建自己的技能市场的过程中，逐个阅读了 Anthropic 的全部 17 项官方技能及其 frontmatter。每次阅读都能发现相同的差距：文档说一套，实际语料库做另一套。而语料库才是正确的。

下面是阅读代码而非文档后得出的真实结论。

描述占技能的 90%

如果技能无法在正确时刻触发，那就毫无用处。而决定是否触发的关键不是 SKILL.md 的正文，而是 frontmatter 中的 description。Claude 会读取可用技能列表（仅包含名称和描述）并进行选择。因此，所有“何时使用”的信息都必须放在描述中，而不是正文中。

反直觉的地方在于，Anthropic 在自己的 skill-creator 中反复强调：Claude 触发技能的频率远低于实际需要。它只有在无法用简单方式处理任务时才会调用技能。“读取这个 PDF”即使描述写得完美，也永远不会触发 PDF 技能。因此有一个明确的建议：描述要写得稍显“强势”。

从代码中可以看到：xlsx 技能的描述是“任何时候当电子表格文件是主要输入或输出时使用此技能”，pptx 则说“任何涉及 .pptx 文件的情况”。毫不含糊。你需要推动触发，而不是克制它。

无人遵循的 500 行规则

“将 SKILL.md 控制在 500 行以内”是引用最多的规则之一。但实际中 docx 有 590 行，且文档本身补充道“如有需要可适当超出”。其他技能的行数范围在 32 到 404 行之间。真相是：500 行是一个目标，而非硬性规定。

其背后的真正原则不是长度，而是上下文预算。SKILL.md 的正文会在每次触发时加载。如果内容因包含必要信息而变长，这是可以接受的；但如果是因为拖带本可放在其他地方的细节而变长，那就是问题所在。大小本身不是问题。

渐进式披露：主要使用脚本，极少使用引用

核心技能模式是分阶段加载：元数据（名称 + 描述）始终在上下文中，正文在触发时加载，资源（scripts/、references/）仅按需加载。脚本甚至可以在不加载到上下文的情况下执行。

但在实际语料库中，17 个技能中有 11 个仅包含单个 SKILL.md 文件，没有任何子文件夹。拆分不是常规做法，只有在领域需要时才会采用。而当你确实拆分时，主要拆分为 scripts/：pdf、docx、xlsx、pptx 首先是用于确定性操作的脚本容器。references/（按需加载的文档）仅出现在两个技能中。经验教训是：优先将确定性操作提取为可执行代码，而不是将文本内容提取到单独文件中。

Anthropic 从不写的“NOT for”

在编写自己的技能时，我系统性地在描述中添加了“NOT for X”子句，以避免错误触发。但阅读官方技能后发现一个意外：它们几乎从不这样做。它们的描述列出包含条件（“包括……”），而不是排除条件。

原因很简单：它们的领域互不重叠。PDF 技能和 Excel 技能不会被混淆，因此无需排除，它们更倾向于最大化触发。我的情况不同：我的技能之间存在关联（审查 diff、发布功能、结束分支是相邻的操作）。“NOT for”可以帮助我在自己的技能之间进行区分。因此这不是通用规则，而是针对重叠情况的应对措施。如果你的技能领域不重叠，就不要添加它：你只会降低触发率，而这是最严重的缺陷。

他们如何实际优化描述

官方 skill-creator 中最具启发性的部分是：他们不是凭感觉猜测好的描述，而是通过测量来优化。完整的流程如下：

  • 20 个评估查询：其中 8-10 个应触发，8-10 个不应触发。查询要真实且杂乱，就像真实用户输入时那样（包含文件路径、个人上下文、拼写错误、小写字母）。
  • 负例是接近但不触发的查询，而不是明显的反例。“编写斐波那契函数”作为 PDF 技能的负例毫无意义。好的负例应与技能共享关键词，但需要其他条件才能区分。
  • 每个查询运行 3 次，以获得可靠的触发率，然后进行 5 轮迭代改进。
  • 根据保留测试集的分数选择描述（60% 训练集，40% 测试集），以避免对已知查询过拟合。

这是一套评估流程，而不是凭空猜测。大多数人凭感觉写描述后就结束，而 Anthropic 将其视为产品。

一览：假设与实践的对比

在全部 17 个官方技能中，逐行对比的差距如下：

常见假设

官方语料库的实际做法

SKILL.md 应控制在 500 行以内

docx 有 590 行，且文档补充“如有需要可超出”

描述只需说明何时使用该技能

必须写得“强势”：真正的风险是触发不足

你应拆分为 references/ 和 scripts/（渐进式披露）

17 个技能中有 11 个是单文件；当拆分时，主要拆分为 scripts/

你在描述中添加限制（“NOT for”）以避免错误触发

几乎从不添加：领域互不重叠，它们最大化触发

好的描述凭感觉编写

通过测量优化：20 个查询，每个运行 3 次，5 轮迭代循环，在保留测试集上评分

需要记住的要点

真正的教训不在于规则列表，而在于规则与实践之间的差距。文档提供清晰的启发式方法，而语料库展示的是有能力的人在实际需求下如何灵活调整。阅读这 17 个技能比阅读文档页面更有价值，因为你能看到真实的权衡：当内容需要时突破 500 行、三分之二的情况下不进行拆分、推动触发而非限制触发。

如果你只记住一件事：风险不在于你的技能触发过多，而在于它根本不会触发。编写描述时要让它容易被找到。

🧩 我的技能，可安装

我根据这些模式，从自己的真实工作流中构建了一个 Claude Code 技能市场。在 Skills 页面 上浏览并安装它们，其中包括一个 skill-builder 技能，它浓缩了这些原则。要构建代理上下文，还可参考 CLAUDE.md contexts。

常见问题

SKILL.md 应该有多少行？

目标是控制在 500 行以内，但这不是硬性规定：官方 docx 技能有 590 行。关键在于正文不要拖带本应放在脚本或引用文件中的细节。如果必要内容需要超出，就超出，然后添加指向侧文件的指针。

为什么我的技能没有触发？

几乎总是描述的问题。Claude 默认会触发不足，只有在非简单任务时才会调用技能。将描述写得更具包容性和“强势”（“无论何时……即使用户没有明确说……”），并包含真实的触发短语。然后进行测试：单步任务永远不会触发技能，这是正常的。

我需要 references/ 和 scripts/ 文件夹吗？

默认不需要：17 个官方技能中有 11 个仅为单个 SKILL.md 文件。当领域较为复杂时再进行拆分，且主要拆分为 scripts/ 以处理确定性工作（文件操作、验证等）。只有在大型多变体领域时，references/ 才有存在的价值。

技能、CLAUDE.md 还是 hook？

技能 = 由其描述在需要时触发的能力。CLAUDE.md = 始终为特定项目加载的上下文。Hook = 在事件发生时由 harness 强制执行的确定性自动化，而非模型决定。如果是“总是执行 X”，那应该是 hook 或 CLAUDE.md，而不是技能。