如何编写 Skill，有什么规范流程？

核心回答

编写 Skill，是把一类任务中可复用的方法整理成能被发现、按步骤执行、结果可检查的能力包。我会按下面的顺序做：

1. 选定任务和成功标准：明确处理什么输入、输出什么结果，先用实际例子找出需要补充的业务知识和步骤。
2. 写好触发描述：在 SKILL.md 的元数据里给出清楚的名称和适用场景，让 Agent 能判断什么时候使用。
3. 写可执行的正文：说明输入要求、默认步骤、工具或资源用法、结果格式，以及缺信息或执行失败时怎样处理。
4. 按需拆资源：长资料放参考文件，稳定操作可封装脚本，模板放资源目录；主文件写清何时使用它们。
5. 在目标宿主验证并迭代：分别检查该不该触发、是否按流程执行、产物是否符合要求，再根据具体失败调整。

简单任务从一个清楚的 SKILL.md 开始就够了，不需要一开始搭完整平台或堆很多目录。

展开说明

1. 从真实任务提取方法，先确定输入和产物

例如设计一个“接口测试用例生成”Skill，可以先取一份接口说明和一个有代表性的需求，明确希望得到正常、边界和异常用例。每条用例至少应能说明前置条件、输入、操作和预期结果，预期结果要对应接口或业务规则。

观察普通提示下有哪些问题：是漏掉边界值、不知道业务口径，还是输出格式不便执行？Skill 针对这些缺口补充规则，比写一整套泛泛的“测试专家”介绍更有用。

任务范围也要清楚。设计测试用例和运行自动化测试是相关但不同的任务；如果本次只要求设计用例，就不应顺带调用真实业务接口或修改测试环境。

2. 元数据解决“什么时候用”，正文解决“具体怎么做”

按 Agent Skills 格式，一个目录至少包含 SKILL.md，文件以 YAML frontmatter 开头，必需字段是 name 和 description，后接 Markdown 指令。名称要符合命名约定并与目录名一致；正文没有统一必填标题，组织清楚即可。

下面是放在 api-test-design/SKILL.md 中的精简设计示例：

---
name: api-test-design
description: 根据接口文档或需求设计测试用例。用户要求生成、补全或审查接口测试用例时使用。
---

# 接口测试用例设计

1. 阅读输入的接口说明，提取参数、约束和业务规则。
2. 按正常、边界和异常场景设计用例，标明各自验证的规则。
3. 缺少业务口径时列出待确认项，避免自行编造预期结果。
4. 输出用例编号、前置条件、输入、操作、预期结果和依据。
5. 检查重复项、遗漏的必要约束，以及预期结果是否有依据。

更复杂时，再补充如何处理多接口依赖、怎样使用模板、哪些失败可以重试。指令应给出默认方法和必要分支，例如“解析不到表格时保留原文件并说明缺口”，比“保证解析高质量”更便于执行。

3. 资源有明确用途，操作由实际工具执行

长字段说明、业务规则和案例可以放在 references/，输出模板放在 assets/，稳定的数据整理或格式检查可放在 scripts/；这些目录都不是必需的。

主文件需要写明“何时读哪份参考资料、何时运行哪个脚本、输入和结果是什么”。相对路径从 Skill 目录解析，不能假定模型会主动遍历所有附件。脚本还要说明依赖、参数、错误输出以及是否会修改文件。

Skill 提供方法，模型据此提出工具调用，宿主执行工具并返回结果。对于必须严格执行的校验，适合用程序实现；对于需要根据内容作判断的步骤，保留相应决策空间。不要用加长提示词替代真实执行逻辑。

4. 既验证触发，也验证最终行为

先确认宿主能发现正确目录、解析元数据，并在需要时加载正文和资源。再用少量有代表性的输入检查：明确要求设计用例、隐含地要求补齐测试覆盖，以及只解释接口而不需要生成用例的情况。

产物检查则回到成功标准：是否覆盖必要规则、预期结果有无依据、格式能否被下游使用。遇到问题，区分选错 Skill、说明不清、资源未读、脚本失败和模型执行偏差，针对原因修改，不只是不断加“必须”。

修改后回看原失败样例及相近场景，记录版本和变更，避免修好一个输入却损坏其他任务。跨宿主使用时，还要确认工具名、目录发现、资源访问和依赖环境确实兼容。

常见追问

Skill 和写一个长 Prompt 有什么不同？

Skill 仍依赖提示指令，但增加了可发现的元数据、可复用的目录及按需资源。模型通常先看到能力描述，任务需要时才读取完整方法。关键收益是任务知识能够独立组织和复用，具体加载机制由宿主实现。

文件写入、删除型 Skill 怎样避免误操作？

正文先明确操作对象和范围，但可靠限制要落到执行程序：把操作类型和目标路径作为明确参数，校验实际解析后的路径及授权范围，限制进程或文件系统可访问的资源。重要操作还可先生成具体变更清单或采用可恢复处理。提示词和 Skill 名称本身不构成文件系统隔离。

一定要包含脚本、固定章节和很多测试吗？

不需要。格式规范主要约束元数据和目录，正文围绕任务需要组织。纯写作或审查任务可能只有说明与样例；涉及稳定转换和严格校验时，脚本才更有价值。验证规模也应与复杂度和风险相称，重点是用代表性输入确认行为。

对应教程

参考资料