创建高质量 Skill 的常用模式

所谓“模式”，是指在不同场景中反复出现、被证明有效的一类做事方式或结构。

Skill 也有一些被验证有效的模式，合理使用¹这些模式，可以提升任务完成的效率和质量。

避坑提示 （Gotchas）

Gotchas 是对“默认行为”的纠偏：如果不显式说明，系统或 Agent 很可能按错误的方式运行，对很多 Skill 来说，最有价值的部分往往就是这些容易踩坑的点。

比如订机票这个场景，如果没特别说明，Agent 可能会默认价格最低的就是最划算的。但实际情况是，一些“附加条款“也很重要，比如低价票通常不包含行李、不能改签，甚至选座、机上服务要额外付费。所以需要明确指出“价格是一个重要的考虑因素，但其他因素如行李政策、改签政策、座位选择等也很重要，请综合考虑这些因素来推荐机票。”

所以最好在 SKILL.md 中的 Gotchas 章节把这些“避坑点”直接列出来，让 Agent 在真正遇到问题之前就知晓。

格式化呈现采用模板而不是描述

当你需要 Agent 按某种固定格式输出时，最好直接给一个模板，而不是用文字描述的方式来说明。

相比用文字去描述“应该长什么样”，模板更可靠，因为 Agent 更擅长照着具体结构去模仿。

• 简短的模板可以直接写在 SKILL.md 里
• 较长的模板，或者只在特定情况下才用的模板，可以放在 assets/ 目录中
• 然后在 SKILL.md 里说明什么时候需要用这个模板，按需加载

比如下面的菜谱模板，Agent 只需按照结构填充内容就行了。

# [菜名]

## 简介
[一句话描述这道菜的特点或口味]

## 食材（X人份）
- 主料：
  - [食材名称]：用量
- 辅料：
  - [食材名称]：用量
- 调料：
  - [调料名称]：用量

## 做法
1. [步骤1]
2. [步骤2]
3. [步骤3]
4. [步骤4]
n. [步骤n]

## 小贴士（可选）
- [关键技巧或容易出错的点]
- [可替代食材或调整建议]

多步骤采用任务清单

当一个任务需要分多步完成时，给 Agent 一个明确的清单，可以帮助它：

• 跟踪当前进度
• 避免漏掉关键步骤
• 按正确顺序执行（尤其是有前后依赖或需要检查的步骤）

下面是一个内容发布的任务清单示例。

## 内容发布流程

- [ ] 步骤1：理解发布目标（主题、受众、渠道）
- [ ] 步骤2：撰写内容初稿
- [ ] 步骤3：检查内容质量（逻辑是否清晰、是否有错别字）
- [ ] 步骤4：根据规范调整格式（标题、段落、配图说明等）
- [ ] 步骤5：自检是否符合发布要求（字数、风格、合规性）
- [ ] 步骤6：输出最终版本（用于发布）

验证循环

在任务执行过程中，不要让 Agent 一路做到底，而是要让它每完成一轮就自检一次。

基本模式是：做一轮 → 检查结果 → 发现问题就修正 → 再检查 → 直到通过为止

这里的“检查”可以是：

• 一个校验规则
• 一份参考清单
• 或者一次明确的自我检查

仍然用内容发布的例子来说明，Agent 每完成一个步骤，就要检查一下是否符合要求，如果不符合就修正，直到满足要求为止。

1. 完成内容初稿修改
2. 进行检查：
   - 是否有错别字或语病
   - 逻辑是否清晰
   - 是否符合目标读者的理解水平
3. 如果检查未通过：
   - 找出具体问题
   - 修改对应内容
   - 再次进行检查
4. 只有全部检查通过，才进入下一步（发布或交付）

规划 → 验证 → 执行

对于一些批量操作或一旦执行就难以回退的任务，不要让 Agent 直接动手，而是分三步走：

比如说批量发布文章流程

1. 制定发布计划（生成 posts_plan.json）
   - 包含每篇文章的标题、发布时间、发布渠道

2. 校验计划：
   - 是否所有文章都有标题和内容
   - 发布时间是否冲突
   - 渠道是否在允许范围内
   - 选题是否符合标准

3. 如果校验不通过：
   - 找出问题（如“发布时间重复”或“缺少内容”）
   - 修改发布计划
   - 再次校验

4. 校验通过后，才执行发布操作

整个过程的关键在第 2 步： 先用一个“标准”去检查计划本身，而不是直接执行

这个标准可以是：

• 一份规则清单
• 一个校验脚本
• 或一份“正确结构”的参考

当校验失败时，清晰的错误信息（比如“发布时间冲突：第2篇和第5篇”）可以帮助 Agent 快速修正，而不是盲目重试。

用脚本封装能力

在不断优化一个 Skill 的过程中，可以观察 Agent 在不同测试用例里的执行过程。 如果你发现 Agent 每次都在“重复造轮子”，比如反复做这些事情：

• 生成图表
• 解析某种固定格式
• 有序地调用某些工具
• 校验输出是否正确

那就说明，这些逻辑已经是稳定且通用的需求了。

这时候更好的做法是： 把这段逻辑写成一个可靠的工具（脚本），统一放到 scripts/ 里供 Agent 使用。