写清 Skill 的名称和触发条件
Name a Skill and describe when to use it
在 Skill 元信息中说明任务与触发条件，再分别检查格式解析和宿主选择。
以下示例和输出是本站编写的教学材料，不是模型实测结果。
使用场景
你要编写一个 PR 代码审查 Skill。运行它的 Agent 支持读取 SKILL.md 开头的 YAML 元信息，而且已配置好 Skill 的发现目录。现在的问题是：名称和用途写得太笼统，Agent 难以判断这份指令是否适合当前请求。
开始前确认宿主支持的文件位置、必填字段和命名规则。下面的目录和名称用于教学；实际安装位置以宿主要求为准。
具体做法
- 在 Skill 目录内创建
SKILL.md，把 YAML 元信息放在文件最前面，用两行---包住。 - 用
name给出可识别的名称；用description写清用户的任务、触发条件，以及容易混淆的另一类请求。 - 在元信息之后写实际审查步骤。元信息帮助发现和选择，正文说明选中后如何工作。
- 先检查格式能否解析，再在支持该格式的宿主中分别试一次审查请求和实现请求。若宿主没有发现该文件，先检查安装位置，不能靠反复改描述解决。
反例
两个版本都用于审查同一份 PR diff，都包含合法元信息和相同正文。下面是完整的反例文件：
---
name: helper
description: 帮助处理代码方面的事情。
---
读取用户提供的 PR diff。报告可以定位到文件和行号的正确性问题，说明触发条件；没有足够信息时列出缺失资料，不修改代码。
“代码方面的事情”既可能指审查，也可能指实现功能。正文再具体，也无法让这段元信息说明何时应该选择它。
改进写法
把同一个文件的元信息改成下面的内容，正文保持一致：
---
name: pr-review
description: 用户要求审查 PR、代码 diff 或待合并变更时，检查可定位的正确性问题。适用于审查请求；用户只要求实现新功能时不要据此选择本 Skill。
---
读取用户提供的 PR diff。报告可以定位到文件和行号的正确性问题，说明触发条件；没有足够信息时列出缺失资料，不修改代码。
套用时，把 pr-review 换成符合宿主命名规则的名称，把描述中的任务和触发条件换成你的 Skill 负责的工作。不要把正文中必需的执行步骤全部塞进描述。
示意交付物是 pr-review/SKILL.md，其解析结果包含 name=pr-review 和上述 description，正文仍是审查流程。
为什么这样改
改进写法把“帮助处理代码”拆成明确的审查任务和触发信号，并说明与实现请求的区别。Agent 在选择 Skill 时有了可比较的信息；正文则继续约束实际审查步骤。这里解释的是选择机制，不能据此声称触发成功率已经提高。
如何验证
先用宿主认可的解析器检查：文件开头是元信息，两处 --- 配对，name 和 description 能被读出。缺字段或格式错误时先修文件。
再分别提出“审查这份 PR diff”和“实现一个导出按钮”。检查宿主提供的 Skill 选择记录：前者应能选择本 Skill，后者不应仅因涉及代码而选中它。若宿主不提供选择记录，记录无法直接观察，不把输出看起来像审查当作触发证据。
适用边界
这只适用于支持该元信息格式和发现方式的宿主。格式检查不等于实际触发验证；描述也不能替代工具权限或强制授权。自定义 YAML 字段只有在宿主明确支持时才有运行意义。