AI Skill 完全教程：从零到一，为你的 AI 打造专属技能（万字实操指南）#

1.1 一个直观的理解#

先忘掉所有技术术语，想象一个场景。

你是一家公司的老员工，带了一个新同事。这个新同事非常聪明、学得很快，但他刚入职，什么都不懂。你手头有一件做了几百次的例行工作，比如”处理客户投诉邮件”。你打算怎么教他？

选项 A：什么都不教，直接让他上手。结果他大概率会把投诉邮件回复得乱七八糟——因为”处理投诉”这件事里面有太多你不知道但默认知道的细节：要先看客户等级、要区分物流问题和质量问题、语气要诚恳但不能承诺赔偿、超过金额要走审批……

选项 B：你写一份《客户投诉处理手册》，里面写清楚：第一步干什么、什么情况走什么流程、哪些话术可以用、哪些红线不能碰、处理完要登记在哪。然后告诉新同事：“以后遇到客户投诉，先看这份手册。“从此他处理投诉的水平，就和你亲手做八九不离十。

Skill 就是那份手册。

Skill 是一份结构化的指令文档，描述”某类任务应该怎么被 AI 完成”。它通常包含：这个技能是干什么的、什么时候该用、怎么用、用的时候要注意什么、有哪些步骤、有哪些边界和禁忌。AI Agent 在运行时，会扫描自己可用的 Skill 列表，根据当前任务匹配最合适的 Skill，然后按照 Skill 里的说明去执行。

1.2 Skill 的三个核心组成#

一个完整可用的 Skill，通常由三部分组成：

1. 说明书（SKILL.md）：一份 Markdown 文档，用自然语言+少量结构描述”这个技能怎么用”。这是 Skill 的灵魂，AI 主要靠它理解任务。
2. 辅助资源（可选）：与技能相关的模板文件、参考文档、示例数据、配置文件等。比如一个”周报生成”技能，可以附带一份《周报模板.md》。
3. 脚本或工具封装（可选）：技能需要调用外部能力时，可以携带脚本（Python/Shell 等）或封装好的工具函数，AI 按说明书调用它们完成实际操作。

重要认知：Skill 的精华在”说明书”，不在代码。 哪怕没有任何脚本，只要说明书写得好，AI 也能用现有工具完成很多任务。脚本只是”锦上添花”，说明书才是”雪中送炭”。

1.3 Skill 的本质：给 AI 的”情境记忆”#

AI 模型本身不知道”你们公司处理投诉的流程”——这是私有知识，训练数据里没有。但 AI 有一个强大的能力：给它一段高质量的指令和上下文，它就能按图索骥地执行。

Skill 的本质，就是把”完成某类任务所需的私有知识、经验、流程、边界”，从你的脑子里、从文档堆里，翻译成 AI 能直接读取的指令。它不是模型参数的一部分，而是运行时注入的上下文——用的时候加载，不用的时候不占地方。

这也解释了为什么 Skill 如此灵活：你可以给 AI 装一个”博客发布技能”，它就学会了你的发布流程；装一个”数据清洗技能”，它就学会了你惯用的清洗规则；装一个”合规审查技能”，它就学会了你们公司的红线。每一个 Skill，都是一段被固化的经验。

2.1 Skill 与 Tool（工具）#

工具是”手”，Skill 是”用法说明”。

• Tool（工具）：AI 可以调用的一段程序，比如”读文件""发请求""执行命令""打开浏览器”。工具解决的是”能不能做”的问题——没有读文件工具，AI 就读不了文件。
• Skill（技能）：告诉 AI”什么时候该用哪个工具、按什么顺序用、用到什么程度算完成”。技能解决的是”会不会做、做得好不好”的问题。

举个例子：你有”读文件""写文件""执行命令”三个工具，也有 Python 环境。但如果你不告诉 AI 怎么发布博客，它面对”帮我把这篇稿子发到网站”依然手足无措——是先跑构建还是先提交？提交到哪个分支？要不要验证？这就是 Skill 发挥作用的地方。

所以两者不是替代关系，而是协作关系：Skill 调度工具，工具执行动作。一个 Skill 可以只用一个工具，也可以编排十几个工具完成复杂流程。

2.2 Skill 与 Plugin（插件）#

Plugin 是更早一代的产品形态（以 ChatGPT 插件为代表）：一个插件 = 一段后端服务 + 一份 API 描述，AI 通过调用插件提供的接口获得外部能力。

区别在于：

• Plugin 偏”服务”：通常部署在远端，AI 只能按你暴露的接口来调用，改功能要改服务端。
• Skill 偏”指令”：本质是一份文本说明书，随 Agent 本地加载，你随时可以编辑、迭代、组合，改起来零成本。

Skill 更轻、更透明、更易迭代，这也是它被主流 Agent 框架青睐的原因。

2.3 Skill 与 MCP#

MCP（Model Context Protocol）是 Anthropic 提出的”AI 应用连接外部数据的开放协议”，可以理解成 AI 世界的 USB 接口标准：一个 MCP Server 提供若干工具，任何支持 MCP 的客户端都能直接使用。

• MCP 解决”连接”：它让”给 AI 接一个外部系统”变得标准化。接了 MCP，AI 就能调用该服务器暴露的工具。
• Skill 解决”使用”：它让”AI 知道怎么用好这些能力”变得可沉淀。

实践中两者经常叠加：一个 Skill 的说明书中，可能会指导 AI 去调用某个 MCP Server 提供的工具。你可以把 MCP 想象成”工具库”，把 Skill 想象成”使用手册”。

2.4 一张表看懂区别#

记住一句话：工具给 AI 手，Skill 给 AI 脑子里的流程。 有了 Skill，AI 才从”什么都能干一点”变成”你交代的活干得专业”。

3.1 价值一：稳定——把”发挥”变成”标准”#

直接让 AI 干活，同一个任务今天做和明天做，结果可能天差地别。因为模型输出有随机性，而你给的上下文每次也不完全一样。

写了 Skill 之后，AI 每次都按同一份说明书执行：同样的步骤、同样的格式、同样的检查点。结果从”看运气”变成”可预期”。这对任何生产级任务都至关重要。

3.2 价值二：省 token——把”长篇大论”变成”一行引用”#

你可能已经发现：每次让 AI 干一个复杂任务，都要把背景、要求、格式、禁忌重新讲一遍，非常费 token（也费钱）。

Skill 的加载机制通常是按需引用：AI 看到任务，先加载对应的 SKILL.md，而不是把全部技能塞进每次对话。任务相关的指令集中存放、按需加载，长期看能省下大量重复输入的 token。

3.3 价值三：传承——把”个人经验”变成”团队资产”#

你的经验值钱，但它目前存在你脑子里。同事问你怎么处理某类需求，你得现场讲；你休假了，工作就停摆。

Skill 把经验显性化、文档化：写进 SKILL.md 的那一刻，它就从”你脑子里的东西”变成了”谁都能加载的资产”。新同事接手、AI 换型号、换框架，技能依然在。

3.4 价值四：进化——把”踩过的坑”变成”防坑手册”#

每个人都在坑里摔过跤：发布忘了清缓存、处理数据忘了处理空值、发邮件忘了抄送……这些教训如果不记录，下次还会摔。

Skill 是最好的”防坑手册”：把踩坑教训写进 SKILL.md 的”注意事项”里，AI 下次执行时就会主动避开。每踩一个坑，你的技能就强一分。

3.5 价值五：组合——把”技能”变成”积木”#

写好的 Skill 可以自由组合：一个”博客发布”技能 + 一个”图片压缩”技能 + 一个”SEO 检查”技能，组合起来就是一个完整的”内容发布流水线”。

Skill 是”积木式”的：单个技能解决单类问题，组合技能解决复杂业务。 这种能力是裸对话完全不具备的。

4.1 一份典型的 SKILL.md#

1
---
2
name: weekly_report
3
description: 生成团队周报。当用户提到"周报""周工作总结""本周汇报"时使用。
4
---
5

6
# 周报生成技能
7

8
## 使用时机
9
当用户要求生成周报/周总结时使用本技能。
10

11
## 步骤
12
1. 询问或确认本周时间段（默认本周一到今天）。
13
2. 读取指定目录下的工作记录文件。
14
3. 按模板整理：本周完成 / 进行中 / 问题与风险 / 下周计划。
15
4. 输出 Markdown 周报，交给用户确认。
16

17
## 模板
18
### 本周完成
19
-
20

21
### 进行中
22
-
23

24
### 问题与风险
25
-
26

27
### 下周计划
28
-
29

30
## 注意事项
31
- 数据必须来自实际文件，不要编造。
32
- 周报总字数控制在 500 字以内。
33
- 用户确认前不要发送给任何人。

4.2 逐块拆解#

块一：Frontmatter（元信息）

文件开头的 --- 包裹区域是元信息，AI 和框架靠它做”技能检索”：

• name：技能名。简短、小写、用下划线或短横线连接，如 weekly_report。
• description：最重要的字段。它描述”这个技能是干什么的、什么时候该触发”。AI 会拿用户请求和所有技能的 description 做匹配，description 写得越准，技能被正确触发的概率越高。
• 其他常见字段：version（版本号）、author（作者）、when_to_use（触发条件）、dependencies（依赖）等，按框架支持度添加。

块二：正文标题与”使用时机”

正文开头的 # 技能名 和”使用时机”小节，是为了让 AI 在加载技能后再次确认：现在这个任务到底适不适合用本技能。这是双保险——description 负责”被找到”，正文负责”被正确使用”。

块三：步骤（Step by Step）

这是技能的核心。把任务拆成清晰的、有顺序的步骤。好步骤的特征：

• 可执行：每步都是 AI 能直接做的动作，而不是含糊的描述。
• 有顺序：步骤之间用数字编号，必要时说明分支条件。
• 有产出：每步说明”做完得到什么”，最后一步说明”交付什么”。

块四：模板 / 示例

给 AI 提供输出格式的参考。模板、示例、话术都可以放这里。给一个”对的样子”，胜过描述十句”要什么风格”。

块五：注意事项 / 边界

写清楚红线：哪些不能做、哪些必须做、遇到什么情况要停下来问用户。这是技能”专业感”的来源。

4.3 什么是好的 description（重点）#

description 是技能被正确调用的关键，写它有两个原则：

1. 包含触发词：把用户可能用的说法都写上。比如”周报""周总结""本周工作汇报""weekly report”。
2. 说明不做什么：如果技能有明确边界，写清楚。比如”本技能只负责生成周报，不负责发送邮件”。

反面例子：description: 周报技能——太短，AI 可能该用的时候想不到用。 正面例子：description: 生成团队周报。当用户提到"周报""周工作总结""本周汇报""weekly report"时使用。仅生成内容，不发送。

4.4 正文长度：宁精勿滥#

SKILL.md 不是越长越好。太长会让 AI 抓不住重点、浪费 token。经验值是：

• 简单技能：200-500 字正文足够。
• 中等技能：500-1500 字。
• 复杂技能（含多步骤流程、分支判断）：1500-3000 字，且要用清晰的结构组织。

核心原则：每个字都服务于”让 AI 把这件事做对”。与任务无关的废话一律删掉。

5.1 第一步：明确”这件任务到底长什么样”#

把任务写下来，回答四个问题：

1. 输入是什么？ 用户会给什么信息？（一段文字、一个文件、一个 URL、一个需求描述）
2. 过程是什么？ 完成它需要哪些中间步骤？（读文件、查资料、计算、生成、校验）
3. 输出是什么？ 交付物的形态？（Markdown 文档、代码、表格、一段消息、一个文件）
4. 边界是什么？ 哪些情况不该处理？哪些红线不能碰？

这四个问题答案写清楚，Skill 就完成了一半。

5.2 第二步：判断”这件事值不值得做成 Skill”#

不是所有任务都值得做成技能。判断标准：

• ✅ 值得：高频（每周至少用几次）、步骤固定、有私有经验加成、结果要稳定。
• ❌ 不值得：一次性任务、纯闲聊、每次需求都完全不同的开放性任务。

记住：Skill 是给”重复发生的、有固定打法的事”准备的。 低频任务直接对话即可，做成技能反而是负担。

5.3 第三步：决定”技能的粒度”#

粒度问题是新手最容易犯的错：

• 粒度太粗：一个”全能助理”技能，什么都能干，等于什么都没教，AI 还是无从下手。
• 粒度太细：一个”把 1 加 1 算出 2”的技能，纯属浪费。

好的粒度参考：一个技能 = 一类业务动作。“生成周报”是合适的粒度，“生成周报并同时处理考勤和报销”就太粗了（应该拆成三个技能）。

5.4 第四步：想好”技能的触发方式”#

技能如何被触发，主流有三种：

1. 自动匹配：AI 根据 description 和用户请求的相似度自动加载。最常用，但要求 description 写得好。
2. 关键词触发：用户说特定词（如 /report）就触发。适合用户主动发起的场景。
3. 强制/手动：在配置里指定某任务必须用某技能。适合流程固定的生产场景。

设计时想清楚主要靠哪种触发，然后围绕它优化 description 或关键词设置。

6.1 需求描述#

用户经常需要：把一段杂乱的会议录音转写文本，整理成结构化的会议纪要。要求：提取决议、任务、负责人、截止时间；按模板输出；不确定的信息标注。

6.2 设计四问#

• 输入：一段会议转写文本（或文件路径）。
• 过程：识别发言人 → 提取主题 → 提取决议 → 提取任务清单 → 标注不确定项。
• 输出：结构化会议纪要（Markdown）。
• 边界：不补写会议中没提到的内容；不确定就标注”待确认”。

6.3 编写 SKILL.md#

1
---
2
name: meeting_minutes
3
description: 把会议录音转写文本整理成结构化会议纪要。当用户提供会议转写、要求"整理会议纪要""会议总结""meeting notes"时使用。
4
---
5

6
# 会议纪要整理技能
7

8
## 使用时机
9
用户提供会议录音转写文本，要求整理成结构化纪要时使用。
10

11
## 输入
12
用户可能直接粘贴文本，或提供文件路径（此时先读取文件）。
13

14
## 步骤
15
1. 通读全文，识别发言人和大致议题。
16
2. 提取会议主题、时间（如有）、参与人（如有）。
17
3. 逐段整理：按议题分组，保留关键讨论内容（压缩为要点）。
18
4. 提取"决议"：明确通过的决定，逐条列出。
19
5. 提取"行动项"：每条含 任务内容 / 负责人 / 截止时间；原文没写的标"待确认"。
20
6. 按下方模板输出纪要。
21

22
## 输出模板
23
# 会议纪要：{主题}
24

25
- 时间：{时间，未知则写"未记录"}
26
- 参与人：{列表，未知则写"未记录"}
27

28
## 议题与讨论
29
1. **{议题}**
30
   - {要点}
31

32
## 决议
33
- {决议内容}
34

35
## 行动项
36
| 任务 | 负责人 | 截止时间 |
37
|---|---|---|
38
| {任务} | {负责人} | {时间} |
39

40
> 注：标"待确认"的项请用户补充。
41

42
## 注意事项
43
- 只整理原文出现的内容，不臆造细节。
44
- 口语化内容转为书面语，但不要改变原意。
45
- 行动项必须逐条列全，不要遗漏。

6.4 验证与试用#

写完不是结束，要试。给 AI 一段测试文本，看输出是否符合预期。重点检查：

1. 技能有没有被正确触发（description 匹配是否成功）。
2. 输出是否严格按模板。
3. 边界是否生效（不确定项有没有标”待确认”）。

不达标就回到 SKILL.md 修改，再试。一个技能通常要迭代 3-5 轮才稳定，这很正常。

7.1 场景#

你的工作流里经常要把 Markdown 转成 Word（.docx）发给客户。AI 本来就有能力处理，但直接让它做，每次都要解释一遍格式要求：标题层级怎么设、要不要目录、页边距、字体……把这些要求固化成一个技能。

7.2 SKILL.md#

1
---
2
name: md_to_docx
3
description: 将 Markdown 文档转换为排版规范的 Word 文档。当用户要求"转成 Word""生成 docx""导出文档"时使用。
4
---
5

6
# Markdown 转 Word 技能
7

8
## 使用时机
9
用户要求将 Markdown 内容或文件转换为 Word 文档时使用。
10

11
## 步骤
12
1. 确认源文件路径和输出目录；没有源文件则先创建 Markdown。
13
2. 阅读源文档，识别标题层级（# 到 ######）。
14
3. 使用文档转换工具生成 .docx，并按下方"排版规范"设置样式。
15
4. 生成后检查：目录、标题层级、表格、图片是否正常。
16
5. 把文件路径交给用户确认。
17

18
## 排版规范
19
- 一级标题：黑体 22pt，居中
20
- 二级标题：黑体 16pt，左对齐
21
- 三级标题：黑体 14pt，左对齐
22
- 正文：宋体 12pt，1.5 倍行距，首行缩进 2 字符
23
- 表格：自动套用"网格"样式，表头加粗
24
- 超过 3 个一级标题时，在文档开头插入自动目录
25
- 页面：A4，页边距上下 2.54cm、左右 3.17cm
26

27
## 注意事项
28
- 文档中的图片需嵌入而非外链。
29
- 转换前先确认源文档无乱码、无损坏。
30
- 输出文件名与源文件保持一致，仅替换扩展名。

7.3 这个案例说明了什么#

• 零代码交付：整个技能就是一份说明书，AI 用自己的工具完成转换，你只需要把”排版标准”写清楚。
• 把隐性知识显性化：字体、字号、行距这些”你心里有数但没说出口”的要求，全部写进了技能。
• 可复制：换个人、换个环境，加载这个技能，产出标准一致。

实操提示：这类技能写完，建议把一份”标准输出样例”也放进技能目录（作为辅助资源），AI 转换时可以直接对照样例校准格式，效果更好。

8.1 场景#

你想让 AI 每天早上九点帮你把当天的待办事项整理好、推送到工作群。这需要：读取待办清单 → 按紧急度排序 → 生成推送文案 → 按计划触发发送。

8.2 SKILL.md#

1
---
2
name: daily_todo_push
3
description: 每天早上整理当日待办并推送到群聊。当用户要求"每日待办推送""每天早上提醒我待办""daily todo"时使用。
4
---
5

6
# 每日待办推送技能
7

8
## 使用时机
9
用户要求设置"每日待办推送"或询问该任务状态时使用。
10

11
## 能力依赖
12
- 定时任务系统（用于创建每日触发的计划）
13
- 群聊/渠道消息发送能力
14
- 待办清单存储（文件或数据库）
15

16
## 步骤
17
1. 确认推送时间（默认每天 09:00）、推送渠道、待办清单来源。
18
2. 创建定时任务：每天触发一次。
19
3. 任务触发时执行：
20
   a. 读取待办清单（文件/数据源）。
21
   b. 按优先级排序：紧急且重要 > 重要 > 紧急 > 一般。
22
   c. 过滤掉已完成的项，标记今日到期项。
23
   d. 生成推送文案（见模板）。
24
   e. 发送到指定渠道。
25
4. 发送成功后记录日志；失败则重试一次并告警。
26

27
## 推送文案模板
28
【每日待办】{月}月{日}日
29
今日共 {n} 项待办：
30
1. {任务}（截止：{时间}）
31
2. ...
32
🔔 今日到期：{到期项}
33

34
## 注意事项
35
- 待办清单为空时，发送"今日无待办"而非跳过。
36
- 文案不要包含敏感信息（如密码、密钥）。
37
- 定时任务创建后，向用户确认"已设置，每天 {时间} 推送"。

8.3 这个案例说明了什么#

• 技能编排多工具：一个技能内部协调了定时系统、文件读取、消息发送三个能力。
• 把”触发条件”写进技能：技能描述里写清楚”用户要求设置推送时使用”，AI 就能把”设置定时任务”这个动作和”每日推送”这个技能关联起来。
• 异常处理也是技能的一部分：失败重试、空清单处理，这些边界写进”注意事项”，AI 执行时才不会卡壳。

9.1 场景#

你需要定期去某个后台系统导出报表，然后存到本地。这个操作涉及登录、导航、点击导出、等待下载、文件重命名——步骤多且每次一样，非常适合做成技能。

9.2 SKILL.md#

1
---
2
name: export_report
3
description: 从业务后台导出报表并保存到本地。当用户要求"导出报表""下载后台数据""export report"时使用。
4
---
5

6
# 后台报表导出技能
7

8
## 使用时机
9
用户要求从业务后台导出报表时使用。
10

11
## 能力依赖
12
- 浏览器自动化能力
13
- 文件系统读写能力
14

15
## 步骤
16
1. 打开后台系统地址。
17
2. 登录（优先使用已保存的会话；若无，则提示用户手动登录，不要尝试自动破解验证码）。
18
3. 进入"报表中心"菜单，定位目标报表。
19
4. 设置时间范围（默认上月）和导出格式（默认 CSV）。
20
5. 点击导出，等待下载完成。
21
6. 将下载文件移动到指定目录，按"报表名_日期"重命名。
22
7. 向用户汇报文件路径和内容概要。
23

24
## 注意事项
25
- 遇到验证码、二次验证等人工步骤时，停下来交回用户处理，不要尝试自动化。
26
- 导出失败时检查：登录态是否过期、时间范围是否为空数据。
27
- 不要修改后台任何非导出相关的数据。
28
- 涉及敏感数据的报表，导出后提示用户注意保存安全。

9.3 这个案例说明了什么#

• 技能要写明”人工边界”：验证码、2FA 这些必须由人完成的步骤，技能里要明确”停下来交回用户”，这是负责任的设计。
• 把操作细节标准化：默认时间范围、默认格式、命名规则，这些细节写进技能，每次导出结果都统一。
• 安全边界：提醒敏感数据注意安全、禁止修改无关数据——技能越专业，越要写清楚”什么不能做”。

10.1 好技能的五个维度#

维度一：触发准确

好技能在”该用时必用、不该用时不用”。测试方法：给 AI 十个相关请求和十个无关请求，看触发率。如果相关请求漏触发，说明 description 不够；如果无关请求误触发，说明 description 太宽。

维度二：步骤清晰

好技能的步骤像菜谱：每一步可执行、有顺序、有产出。测试方法：找个没参与过编写的人读一遍，问”你知道该怎么做吗”——如果对方需要反问，说明步骤不够清楚。

维度三：输出稳定

好技能同一输入多次执行，输出结构一致。测试方法：同一测试用例跑三遍，对比输出结构。不稳定就检查：模板是否明确、步骤是否含糊。

维度四：边界明确

好技能清楚知道”什么情况停下来”。测试方法：故意给出边界外的请求（如”顺便帮我把周报发出去”，而技能说明不发送），看 AI 是否正确地拒绝或询问。

维度五：可维护

好技能好改。结构化清晰、无冗余废话、字段完整。测试方法：过一个月再回来改它，如果你还看得懂、改得动，就是好技能。

10.2 坏技能的典型特征（避坑清单）#

1. description 敷衍：一句话带过，导致技能永远不被触发。
2. 步骤含糊：“整理一下""处理一下”这种无法执行的动词。
3. 没有模板：输出格式全靠 AI 自由发挥，结果每次都不一样。
4. 没有边界：不知道什么该停，乱承诺、乱执行。
5. 内容臃肿：废话连篇，AI 抓不住重点，还浪费 token。
6. 一次性任务硬做成技能：明明只用一次，却花一小时写技能。
7. 不测试就上线：写完直接丢给 AI 用，出了问题才知道。

10.3 快速自检表（写完后过一遍）#

• description 是否包含触发词和边界？
• 步骤是否每条都可执行、有顺序？
• 是否有输出模板或示例？
• 是否写清了注意事项/红线？
• 是否有冗余内容可以删？
• 是否用测试用例验证过触发和输出？
• 是否在真实场景试用过至少一次？

全部打勾，这个技能才算合格。

11.1 调试的三种场景#

场景一：技能没被触发

现象：用户提了相关需求，但 AI 没加载这个技能。

排查顺序：

1. description 里有没有包含用户可能用的说法？（中文、英文、缩写都写上）
2. description 是否太泛，导致被其他技能抢了匹配？
3. 技能的目录/命名是否符合框架要求（框架会不会扫描到它）？

场景二：触发了但执行不对

现象：技能加载了，但 AI 没按说明做。

排查顺序：

1. 步骤是否足够明确？（把”处理一下”改成”提取标题、汇总要点、按模板输出”）
2. 是否给了输出模板？（AI 有模板照着填，比自由发挥靠谱得多）
3. 正文是否太长导致 AI 忽略关键步骤？（试试精简，把关键步骤放前面）

场景三：输出了但质量不行

现象：结构对，但内容不符合预期。

排查顺序：

1. 有没有给”好与坏”的对比示例？
2. 边界是否写清？（比如”不要编造数据""不确定标待确认”）
3. 是不是该把判断标准也写进技能？（“摘要控制在 100 字内""结论必须给出依据”）

11.2 迭代节奏：小步快跑#

不要试图一次写完美。推荐节奏：

1. 第一版：写个 60 分的版本，能用就行。
2. 试用：真实场景用三次，记录问题。
3. 修一次：针对最痛的问题改一次（一次只改一个点，便于判断效果）。
4. 再试用：验证修复是否生效。
5. 循环：直到稳定。

经验法则：一个技能从初稿到稳定，通常要改 3-5 轮。 每一轮只改一个问题，改完立刻测，别攒着一起改。

11.3 用”回放”方式调试复杂技能#

复杂技能出错时，AI 已经执行完了一堆步骤，很难定位问题。技巧是：要求 AI 在每一步执行后输出简短日志（做了什么、结果如何），这样失败时你能看到卡在哪一步。

技能里可以加一句：“执行过程中，每完成一步输出一行进度日志，格式：[步骤名] 结果。“这会让调试容易十倍。

12.1 为什么需要版本管理#

技能会不断迭代。没有版本管理，你改着改着就分不清”上一版为什么能跑，这一版为什么不行”。给技能加版本号，是成本最低的保障。

做法很简单：在 Frontmatter 里加 version: 1.2.0，每次有实质修改就升版本号（小改升第三位、加功能升第二位、大重构升第一位）。还可以在技能目录里放一个 CHANGELOG.md，记录每次改了什么、为什么改。

12.2 用 Git 管理技能库#

如果你的技能比较多，强烈建议用 Git 管理整个技能目录：

• 每次修改都有提交记录，可以回滚。
• 可以开分支试验新写法，稳定了再合并。
• 多设备之间可以同步。
• 后续分享给别人也方便。

12.3 分享与复用#

技能是纯文本 + 资源文件的组合，天生适合分享。分享时的注意事项：

1. 脱敏：检查技能里有没有写死的敏感信息（账号、路径、密钥），分享前替换成占位符。
2. 写清依赖：技能依赖哪些工具、哪些环境，在 README 里写清楚。
3. 带测试用例：附上 2-3 个输入输出示例，接收方可以立刻验证。
4. 说明适用场景和边界：让对方判断这个技能适不适合自己。

12.4 技能库的整理#

技能多了之后，要像整理代码库一样整理技能库：

• 命名规范统一：全部小写、下划线连接、一眼看出功能。
• 目录结构清晰：按领域分目录（写作类、运维类、数据类……）。
• 定期清理：废弃的技能及时归档或删除，避免”技能污染”（太多技能反而干扰匹配）。

提醒：技能不是越多越好。几十个高质量技能，好过几百个没人维护的僵尸技能。

坑一：description 写成”功能说明书”而不是”触发器”#

❌ 错误：description: 本技能用于生成周报，包含本周完成、下周计划等字段。 ✅ 正确：description: 生成团队周报。当用户提到"周报""周总结""本周汇报"时使用。

记住：description 的职责是让 AI 决定”该不该用”，不是介绍功能。

坑二：让 AI 做它没有能力做的事#

技能写得再详细，AI 没有对应工具也做不了。写技能前先确认：完成这个任务需要的工具，AI 环境里都有吗？没有就要么加工具，要么在技能里明确”此任务需要 XX 能力，不具备时告知用户”。

坑三：把”人工步骤”硬塞进技能#

验证码、扫码登录、付费确认、法律签署——这些必须真人完成的步骤，不要试图自动化。正确做法：技能里写明”遇到 XX 时停下来，把操作步骤交给用户”。

坑四：技能里写死”过时的事实”#

技能里的地址、路径、版本号会过时。建议：关键事实让 AI 执行时动态确认（比如”检查 XX 目录是否存在，不存在则询问用户”），而不是写死一个迟早失效的值。

坑五：不区分”私有知识”和”通用知识”#

通用知识（如何写 JSON、Markdown 语法）不用写进技能——AI 本来就会。技能里应该放私有知识：你的流程、你的标准、你的偏好、你的红线。写技能前问一句：“这件事的哪些细节，是 AI 不问我、不看文档就不知道的？“把答案写进去。

坑六：忽略了”输出确认”环节#

很多技能失败在最后一步：AI 直接交付，用户不满意又得重来。好技能应该在关键节点加确认：“生成初稿后，先展示给用户确认，再继续下一步。“多一次确认，少十次返工。

坑七：测试用例太”善良”#

测试只用理想输入，问题全被掩盖。测试要包括：边界输入（空内容、超长内容）、异常输入（格式错误、数据缺失）、越界请求（要求技能做不该做的事）。把这三类用例跑一遍，技能才扛得住真实世界。

14.1 参数化：让技能更灵活#

固定模板的技能用起来有局限。进阶做法是参数化：在 SKILL.md 里定义技能接受的参数，让 AI 根据用户需求填充。

示例（会议纪要技能加参数）：

1
## 参数
2
- `format`: 输出格式（markdown / 表格 / 摘要），默认 markdown
3
- `level`: 详细程度（详细 / 精简），默认精简
4
- `include_tasks`: 是否提取行动项（true / false），默认 true

AI 加载技能时，先确认参数取值，再执行。这样同一个技能可以应对”要详细版""只要摘要""只要行动项”等不同需求。

14.2 输入校验：防止 AI 乱接活#

技能里可以加”输入检查”步骤：

1
## 输入检查
2
1. 用户是否提供了必要信息？（没有则先询问）
3
2. 输入格式是否符合预期？（不符合则先转换或说明）
4
3. 任务是否在本技能范围内？（不在则明确告知，不硬做）

这三问能挡住大部分”AI 拿到不完整需求硬干”的问题。

14.3 输出校验：交付前自检#

给技能加一个”交付前检查清单”，让 AI 在输出前过一遍：

1
## 交付前检查
2
- [ ] 内容是否全部来自真实数据，无编造？
3
- [ ] 是否按模板输出，格式完整？
4
- [ ] 敏感信息是否已脱敏或提醒？
5
- [ ] 是否已向用户确认最终结果？

把质检环节写进技能，等于给 AI 装了一道质量门。

14.4 安全设计：技能的安全红线#

技能涉及外部操作时，安全必须写进设计：

1. 最小权限：技能只做任务需要的操作，不顺手做别的。
2. 确认机制：破坏性操作（删除、覆盖、发送、支付）前必须向用户确认。
3. 敏感信息保护：技能不读取、不输出密钥/密码/隐私数据；需要时提示用户自己操作。
4. 外部交互谨慎：发邮件、发帖、公开发布前，技能应明确”先给用户确认内容”。
5. 异常上报：技能执行中遇到异常（工具失败、数据缺失），如实报告，不编造结果。

一句话原则：技能能力越大，边界越要写清楚。 安全红线不是限制，是保护——保护用户，也保护你自己。

15.1 单 Agent：技能就是”工具箱”#

最简单的模式：一个 Agent 挂载多个技能，根据任务自动选用。这是个人助理最常见的形态——写作、查资料、发消息、管文件，各配一个技能，一个 Agent 全搞定。

15.2 多 Agent：技能就是”岗位说明书”#

进阶模式：多个 Agent 各管一摊，每个 Agent 用技能定义自己的”岗位职责”。

• 写作 Agent：加载”文章撰写""配图生成”技能。
• 运维 Agent：加载”日志分析""服务器巡检”技能。
• 客服 Agent：加载”工单处理""话术模板”技能。

当任务需要跨领域时，主 Agent 把任务分派给对应 Agent，各 Agent 用各自技能执行。技能在这里扮演了”岗位说明书 + 培训手册”的双重角色。

15.3 技能组合：流水线模式#

复杂业务往往是多个技能的组合。比如”内容发布流水线”：

1. “选题分析”技能：确定主题。
2. “文章撰写”技能：生成初稿。
3. “排版校对”技能：格式化、检查错别字。
4. “发布上线”技能：构建、部署、验证。
5. “收录检查”技能：发布后检查搜索引擎收录。

每个技能独立可测、可替换，组合在一起就是完整业务。这就是”积木式”协作的魅力。

15.4 技能之间的引用#

技能之间也可以互相引用。一个技能可以在步骤里写”如需生成配图，参考 image_gen 技能”。AI 会按需加载被引用的技能。注意控制引用深度，避免 A 引用 B、B 又引用 A 的循环。

16.1 当前生态#

Skill 的理念正在被越来越多的框架和平台采纳。你可以看到：

• 各大 Agent 框架内置技能机制，支持用户自定义技能。
• 开源社区出现大量共享技能库，覆盖写作、编程、运维、营销等场景。
• 平台开始提供”技能商店”，让创作者分享技能、获取收益。
• 技能与 MCP、插件等生态相互打通，连接能力越来越强。

16.2 未来的趋势#

从趋势看，Skill 会沿着三个方向演进：

方向一：更智能的调度。 未来框架会更好地理解技能之间的依赖与优先级，自动编排复杂任务，减少人工配置。

方向二：更标准化的交换。 技能描述格式有望进一步统一，让同一份技能在不同框架间无缝迁移，“一次编写、处处运行”。

方向三：更丰富的内容形态。 技能不再只是文本说明，会包含多模态示例、交互式教学、自动评测等，让技能”可教学、可验证、可进化”。

16.3 给你的建议#

无论生态怎么变，有一件事不会变：把经验沉淀成可复用资产的能力，永远值钱。

• 从今天开始，把你最常让 AI 做的那件事，写成第一个技能。
• 每次踩坑，都回去更新技能。
• 定期整理你的技能库，淘汰无用的、打磨有用的。