如何创建高质量 Skill
掌握创建 Skill 的最佳实践，把经验转化为高质量的技能
打造高质量的 Skill 的整个过程其实与我们在梳理 SOP， 制定操作流程，编写培训手册，或者总结工作经验时的思路是类似的。 你需要把那些零散的、隐性的经验和知识，系统化、结构化地整理出来，形成一份清晰、易懂的操作指南。
只不过由于使用的对象是 Agent，而不是人，所以在编写 Skill 的时候，我们需要更多地考虑它的理解和执行方式，确保它能够正确地理解我们的指令，并且按照预期的方式去执行。
在与 Agent 的交互中识别 Skill 的要素
最好的开始方式，不是一来就上手写 Skill， 而是先与 Agent 交互，在与 Agent 携手完成任务的过程中，识别出那些可以被反复使用的元素。
比如：
- 任务步骤：被你拆分出来可以被 Agent 稳定执行的操作流程；
- 调整与纠错：为完成任务你对 Agent 行为做出的调整，比如告诉它使用工具 A 而不是 B、注意特殊情况 C、或者在某个环节需要特别注意 D；
- 输入输出标准：那些能提升产出质量的输入格式，你期待的输出形式；
- 你提供的上下文：那些 Agent 不知道但完成任务所必须的事实或约束。
充分利用手里已有的东西
无论是个人，还是组织，通常都已有一些沉淀出来的资料，比如操作手册、培训材料、SOP说明、以及在流程中的的调整、批复和沟通记录。 这些都是非常宝贵的资源，完全可以拿来作为创建 Skill 的材料。
需要注意的是，筛选材料的标准，一定要是与完成任务高度相关，那些通用的，相关性不高的材料不要一股脑地赛给 Agent。
找找看你是否已经有了下面的这些材料
- 内部培训材料
- 操作手册
- 相关的 SOP 文档
- 完成某个任务的沟通记录（比如邮件、聊天记录、会议纪要等）
- 各种规范文件，比如编码规范、设计规范
如果有的话，恭喜你，你已经有了创建 Skill 的原材料了！ 你要做的，就是把他们喂给大模型，让它帮你先合成一个初版 Skill。
合理使用上下文
新手在创建 Skill 的过程中，最常见的一个问题是不清楚 Agent 知道什么，不知道什么，从而拿不准哪些信息需要提供给它。 由于 Skill 被使用时，SKILL.md 的所有内容都会被加载到上下文中， Skill 每个 token 都会与上下文中的其他 token 争抢 Agent 的注意力。 如果你提供了无意义的内容，不仅费钱，还会干扰 Agent 的理解。
只提供 Agent 不知道的
哪些是 Agent 不知道的呢？ Agent的决策靠大模型， 前面我们提到过， 大模型训练的时候接受的是通识教育，所以大模型就像一个大学生。 你可以尝试问自己哪些知识大学生是知道的。
比如，大学生通常知道 PDF, Word, Excel 这些常见的文件是什么。所以下面示例中的内容就没有必要
# 从 PDF 中提取文本
PDF（便携式文档格式）文件是一种常见的文档格式，其中包含文本、图像和其他内容。要从 PDF 中提取文本，你需要使用一个库。推荐使用 pdfplumber，因为它能够很好地处理大多数情况。更好的版本应该是默认 Agent 已经知道 PDF 是什么了，直接告诉它如何提取文本：
# 从 PDF 中提取文本
使用 pdfplumber 提取文本。对于扫描文件，可使用 pdf2image 和 pytesseract。
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
```这个示例中，我们将关注点放在了告诉 Agent 使用什么工具来操作，以及如果 pdf 是扫描件这种情况该如何处理，同时我们还提供了示例代码。
这是不是很像我们和大学生的沟通方式？经管不是非常严谨， 但作为一种判断依据，在创建 Skill 时，可以时常问自己哪些是大学生知道的，哪些是他们不知道的。
边界清晰，能力内聚
如何确定一个 Skill 的能力范围直接影响它的质量。 如果技能划分得过细，就会导致完成一个简单任务时需要同时调用多个技能，不仅增加系统开销，还容易出现指令冲突；但如果技能范围过大，又会让调用变得不够精准，难以在合适的时机触发，甚至执行起来也不稳定。
举个例子： “页面 SEO 诊断，呈现结构化报告”是一个能力比较内聚的 Skill， 因为完成了一个清晰的任务，输入输出明确。但如果是“页面 SEO 诊断，呈现结构化报告, 并修复诊断出的所有问题”，就过于宽泛了， 因为它还包含了修复 SEO 问题的能力。
有几个关键的判断点可以参考：
- 一句话描述这个 Skill 的能力，如果描述里出现多个动词且彼此独立，大概率过宽
- 输入和输出是否“单一且稳定”？
- 执行过程中 Agent 的角色是否发生了转变？ 比如从一个分析者变成了一个执行者，这通常是能力过宽的信号。
一个简单的总结公式： 一个好的 Skill = 一个清晰目标 + 一种角色 + 可预期的输入输出
“适度细化”，而不是面面俱到
技能描述过于全面，往往弊大于利——Agent在其中难以抓住真正相关的信息，甚至可能被一些并不适用于当前任务的指令带偏，走向低效甚至错误的路径。
相比之下，简洁、分步骤的说明，加上一个可参考的示例，通常比事无巨细的文档更有效。
当你开始试图覆盖各种边界情况时，可以停下来想一想：这些情况，是否真的需要在技能中明确规定，还是更适合交由 Agent 自行判断处理。
下面是几个需要警惕的过度细化信号：
“主路径”被淹没
先问一个很直接的问题：一个新人能不能在 10–20 秒内看懂“这个 Skill 的基本用法”？ 如果不行，那就说明主路径可能被大量例外、分支、注意事项淹没了
“例外“占比过多
- 主逻辑：核心步骤 + 正常输入输出
- 边界情况：各种 if / 特殊处理 / 限制说明
如果边界情况的篇幅 ≥ 主流程的篇幅，那就要警惕了。
大量“替模型做判断“
如果技能中有大量的“如果 A 则执行 B，否则执行 C“、“在以下5种情况下分别处理……“，这往往是在把模型当执行器，而不是决策者。
比如
如果产品是电子类且价格高于 1000 元，则强调性能和参数；
如果是服装类且面向女性用户，则强调设计和穿搭；
如果是食品类，则强调口感和成分；
如果用户年龄在 18–25 岁之间，则语气更活泼，否则偏正式；
如果产品有促销，则在结尾加入优惠信息，否则不提……更好的方式是：规则只保留“硬约束”，判断交给模型
请根据产品信息生成一段产品描述，要求：
* 结构清晰，突出核心卖点
* 语言符合目标用户的阅读习惯
* 避免虚假或无法验证的表述
* 控制在 100–150 字去掉一半细节后仍然可用
如果拿不准，尝试让 Agent 帮你去掉一半细节，看技能是否仍然能稳定输出，若果可以，保留精简后的版本。
对大型 Skill 采用“渐进式展开”的结构
如果一个 Skill 的内容的确比较多，精简后也超出了官方建议的 500 行、5000 tokens 的标准。应该将 Skill 的内容进行合理的拆分，把一些参考内容、模板放到独立的文件中。
尤其是条件性的内容，或者一些边界情况的处理，往往不适合直接放在 SKILL.md 里。 你可以把它们放在 references 文件夹中的单独 Markdown 文件里，然后在 SKILL.md 中通过链接引用它们。
比如：
当 API 返回非 200 状态码时，读取 references/api-errors.md
通过明确的条件，而不是一句笼统的“详情见 references/ 目录”，引导 Agent 在需要的时候准确获取到内容。
控制 vs 放权
按风险调节
什么时候“控制”，什么时候“放权”，是企业管理中的一个重要决策，也是 Skill 设计中的一个重要考量。
在 Skill 设计中，“控制“还是“放权“ 与任务的“脆弱程度“有关。所谓“脆弱程度”，指的我们对结果的“容忍程度“， 当一个任务存在多种可行路径、且我们对结果的差异容忍度较高时，应给予 Agent 更多自由度。因此在设计 Skill 时，我们会倾向于“放权“， 让 Agent 根据实际情况灵活调整执行路径；反之，如果任务的结果对我们来说非常重要，我们就需要“控制“，通过明确的步骤、规则和限制来确保 Agent 的行为符合预期。
比如客户沟通邮件，我们对结果差异容忍度是很高的，适合只保留关键约束，把具体的措辞、结构等交给 Agent 来判断；而对于退款处理，我们对结果的准确性要求很高，就需要在 Skill 中明确每一步的操作细节，甚至提供示例代码来确保 Agent 的行为可控。
## 客户邮件撰写
在撰写客户邮件时，请遵循以下要求：
- 清楚传达关键信息（如进展、问题或下一步）
- 语气与客户关系和场景相匹配
- 表达专业、礼貌，避免引起误解
- 内容简洁，重点突出## 退款处理流程
请严格按照以下步骤执行：
1. 判断是否符合退款条件：
- 是否在7天内
- 是否未使用服务
- 是否提供有效订单信息
2. 如果【全部满足】：
- 返回：同意退款
- 使用模板A说明退款流程
3. 如果【任一不满足】：
- 返回：不予退款
- 使用模板B说明原因
4. 不得自行新增或修改判断条件减少选择
有时候，完成一个任务可以有多种工具和路径可以选择。比如说，提取 PDF 文本，既可以使用 pdfplumber，也可以使用 PyMuPDF；又比如说，生成客户邮件，可以选择不同的模板，或者完全不使用模板。
遇到这种情况，最好的方式是：提供默认值，然后再给出其他选择， 而不是把有选择平等地提供给 Agent;
## 图表渲染
请根据数据生成图表，可选类型：
- 折线图
- 柱状图
- 饼图
- 散点图
请选择最合适的一种## 图表渲染
默认使用柱状图展示核心指标。
如果数据强调趋势变化，可采用折线图；
如果需要展示占比结构，可采用饼图。
···授人鱼不如授人以渔
一个好的 Skill 应该教会 Agent 如何解决一类问题，而不是只针对某一个具体场景给出答案。
举个例子，如果我想做一个旅行规划的 Skill， 就不能在技能中绑定某次具体旅行相关的细节（比如目的地、时间、预算等），而应该告诉 Agent 旅行规划的一般步骤，和在每个步骤中需要考虑的因素。 这样，当我下次需要规划一次不同的旅行时，Agent 就可以根据这个 Skill 来指导它完成新的任务，而不是只能在之前那个特定的场景下使用。
下面的这个示例的问题就在于它把旅行规划这个 Skill 绑定在了一个特定的旅行上了， 这就限制了它的适用范围，导致它只能在这个特定的场景下使用。
## 旅行规划
请帮我规划一次巴黎5天旅行：
- 时间：10月1日出发，共5天 <--时间被限定
- 预算：总预算控制在1.5万元以内 <--预算被限定
- 偏好：以经典景点和美食为主
要求：
1. 每天安排2–3个巴黎核心景点（如埃菲尔铁塔、卢浮宫、凯旋门等） <--地点被限定
2. 行程节奏偏轻松，避免过于紧凑
3. 住宿统一安排在市中心（如1区或7区）
4. 输出按天拆分的详细行程而下面的这个示例则是更好的版本， 因为它总结了旅行规划的一般步骤和需要考虑的因素， 这样它就可以被反复使用在不同的旅行规划任务上了。
## 旅行规划
1. 明确旅行目标：放松度假 / 深度探索 / 打卡景点 / 美食体验等
2. 根据用户输入确定关键约束：时间、预算、出发地、同行人数
3. 选择目的地：结合预算、季节、签证难度和兴趣偏好筛选
4. 规划行程结构：按天分配主题（如城市探索、自然风景、休闲）
5. 安排交通与住宿：优先考虑时间效率与地理集中度
6. 为每天设计具体活动：景点、餐饮、休息时间合理搭配
7. 做风险与备选方案：天气变化、交通延误、景点拥挤等
8. 输出清晰结构化结果（如按天的行程表 + 预算概览）