Skill加载正常却从不触发？问题在描述写法

你写了一份 SKILL.md。它在正确的目录下，命名正确，YAML frontmatter 也有效。你开启一个全新会话，发送一个明显在范围内的请求——然而 agent 依然用老办法处理任务，完全忽略了这个 skill。

这不是加载 bug。几乎所有情况下，根源都在 description（描述）上。

description 是 agent 决策的唯一依据

在 agent 使用一个 skill 之前，它必须先选中它——而它用来做选择的唯一参考，是 frontmatter 里的一行文字。不是文件里的流程步骤，不是示例，不是门槛条件，而是 description。如果这一行文字与请求的形态不匹配，那这个 skill 就形同不存在，无论文件其他部分有多完善。

这会产生两种截然不同的失败形态，从外表看一模一样（"skill 没生效"），但修复方法完全相反：

Skill 从不触发。 description 太过模糊或太过狭隘，无法匹配真实请求。

Skill 什么请求都触发。 description 太过宽泛，现在它在与其他本该处理请求的 skill 竞争——而且有时候还赢了。

话题型 vs 触发型

最常见的错误，是写出的 description 描述的是主题，而不是情境：

"Helps with debugging."

这是话题型的。它告诉你这个 skill 是关于什么的，但完全没有给 agent 提供任何可匹配的依据——没有情境、没有时机、没有边界。对比：

"Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes."

这是触发型的。它指明了情境（"encountering a bug"）、时机（"before proposing fixes"），并隐含了边界（不是功能需求，不是样式问题）。Agent 在扫描 description 时，靠这一行就能做出判断。

这个模式可以推广："Use when [情境]" 几乎总是优于 "Helps with [主题]"。

写用户实际会打的字

匹配是针对 incoming request 的措辞进行的，而不是你内部的 skill 命名。如果你内部叫它"验证 skill"，但没人会输入"验证"，那描述就要用用户实际会用的词——"check"、"confirm"、"make sure this is done"，或者你用户真实的措辞。一个用了只有你才懂的术语的 skill，在功能上等同于隐形。

保持一到两句话——而且要让每句都有分量

更长的 description 会被略读；更短的又无法将自己与相邻 skill 区分开来。目标是一到两句话，充分明确：什么情境触发这个 skill，以及（如果重要的话）它明确不覆盖什么。

注意重叠，而不只是模糊

即使 description 写得很好、很具体，如果它与另一个 skill 的触发条件重叠，也一样会失效。当两个 skill 都可能匹配同一个请求时，agent 会在选择时消耗判断力——而且有时候会选错。如果你有两个 skill 在同一种请求上都被触发，那这不是两个有用的 skill，而是一个靠抛硬币决定的 skill。把 description 收窄，直到任意一个给定请求都只有唯一一个 skill 能匹配。

在碰文件里的流程、门槛条件或其他任何内容之前，先问自己：如果把这个 description 贴在这个 agent 可能做的其他五件事旁边，它是否只明显匹配我期望的那些情况？如果你不确定，agent 也不确定——而"不确定"在多数时候的结果是"不触发"。

完整原文（含修改前后对比示例）：https://agentkitworks.com/answers/how-to-write-skill-description