最近团队在搭 Agent 应用，好几个同事不约而同跑来问我同一个问题：网上到处都在讲 Skills、Skills，到底怎么落到自己的项目里？我翻了一下手头的代码和文档，发现大家卡住的点其实不是“不会写 Prompt”，而是缺少一套把零散经验变成“标准化技能包”的方法。这篇就把我自己的操作流程完整拆出来，包括概念、设计、封装、测试和踩坑记录，给正准备动手的人一个可以直接照做的模板。
这篇文章适合两类人：一类是在做 AI 应用开发，想把重复性工作封装成可复用能力的工程师；另一类是重度 AI 用户，希望通过“技能化”来约束模型输出、提高稳定性的产品经理或运营。不涉及复杂的框架源码，重点讲清楚“怎么想、怎么设计、怎么写”。
1. 到底什么是“Skills”？先想清楚再动手
1.1 Skills 不是插件，也不是普通 Prompt
很多人一听到 Skills 就以为是“可以插到某个系统里的插件包”，这个理解有一定道理但不准确。在我的实践里，Skills 更像是一个“能力单元”：它把某个领域的知识、判断逻辑、输出格式打包成一个独立文件，让大模型在需要时自动激活并使用。
打个比方：传统软件里的函数是给程序员调用的，函数接收参数、返回结果；而 Skills 是给大模型调用的，它接收一段自然语言输入，按照你预先写好的方法论文案去处理，再按约定的格式吐出结果。区别在于，函数是确定性的，而 Skills 的执行过程是大模型在“发挥”，所以 Skills 的核心工作不是写代码，而是把“怎么做”这件事用模型能理解的方式说清楚。
1.2 “定位描述技能”和“编程技能”有什么不同
我在实际项目里会把 Skills 分成两类，设计思路完全不同：
- 定位描述技能（Declarative Skill）：本质是一份结构化的说明文档，告诉模型“面对什么情况、按什么步骤、产出什么格式”。这类技能很灵活，模型会用自身推理能力补全细节，但代价是结果有一定随机性。
- 编程技能（Imperative / Code Skill）：技能本体是一段可执行代码，模型负责解析用户意图、填充参数、触发代码运行，再由代码完成确定性操作（比如请求 API、读写数据库、做计算）。这类技能稳定，但前期成本高，只适合逻辑固定、不容出错的场景。
一个成熟的技能体系通常是两者组合。比如我做“数据分析助手”时，数据清洗部分用编程技能保证结果一致，分析结论部分用定位描述技能让模型结合上下文灵活输出。
1.3 什么样的场景才值得做成 Skills
这不是所有工作都值得封装成技能。我给自己定了一个“三个月原则”：如果三个月后这个任务还会反复出现，且每次处理方式高度相似，那就值得做；如果是一次性任务、或者需要大量人工主观判断，那直接用普通对话更合适。
适合做成 Skills 的场景通常有三个特征：
- 重复性高：比如周报汇总、会议纪要、竞品信息整理、日报生成，每周都在做。
- 方法论明确：团队里已经有“标准做法”，只是每个人执行得参差不齐。
- 需要统一输出口径：多个团队成员同时使用，希望产出格式一致，方便后续处理。
不适合的也有三类：涉及敏感决策的（比如给患者诊断建议）、合规边界模糊的（比如自动生成合同条款）、高度依赖当下灵感的（比如创意文案）。
2. 设计一个高质量 Skill 的四步法
2.1 第一步：先定“接口”，再写内容
很多新手上来就写 Prompt，写到一半发现模型给出的结果千奇百怪，然后不断往提示词里补约束，最后变成一坨没人看得懂的文本。我的习惯是反着来：先明确输入和输出。
所谓“接口”，就是回答四个问题：这个技能接收什么信息？哪些信息是必填的？哪些可选？最终产出的格式长什么样？
推荐直接用 JSON Schema 定义输入。举个例子，设计一个“会议纪要整理助手”，我会这样定义输入字段：
{ "input": { "transcript": { "type": "string", "description": "会议录音转写全文", "required": true }, "topic": { "type": "string", "description": "会议主题", "required": false }, "participants": { "type": "array", "items": { "type": "string" }, "description": "参会人名单", "required": false }, "output_language": { "type": "string", "enum": ["中文", "English"], "description": "输出语言", "required": false } } }这个阶段不需要写任何具体指令，光是定义清楚“要什么、给什么”就能避免一半的返工。我们团队早期吃过亏：技能描述写了一大段，但输入字段定义模糊，模型经常把“参会人”理解为“发言人列表”，把“待办事项”理解为“讨论要点”，结果整个输出结构崩塌。字段定义清晰，模型才知道去哪里取信息。
输出端也一样，我会定义一个固定的结构。比如会议纪要必须包含：会议概述、讨论要点、结论决议、待办事项、风险提示，五个部分缺一不可。这个输出结构写进技能描述里，模型就不会自由发挥。
2.2 第二步：把“专家经验”变成“可执行步骤”
接口定好后，最重要的一步是把隐性经验转化为显性步骤。这一步的难点不在于写，而在于“拆”：你要把自己脑子里处理这个任务的潜意识动作一点点挖出来。
以会议纪要整理为例，我脑子里其实是有完整流程的：
- 通读全文，划掉寒暄和无关闲聊。
- 识别讨论主线，通常一场会议会有 2 到 5 个核心议题。
- 对每个议题提取：背景、各方观点、最终结论。
- 从全文抽取所有“谁在什么时间点之前完成什么”的表述。
- 整理风险点和未决事项。
- 按固定模板输出。
这个流程在技能描述里必须明确写出来，而且要写“先做什么、再做什么、最后做什么”，让模型按顺序执行。很多人写技能描述时只写了“请整理会议纪要”，然后加一堆“注意要突出重点”之类的要求，这种做法效果很差，因为模型不知道“重点”是什么，只能靠猜。
我在写这步时有个技巧：把每个步骤用祈使句开头，动词前置。比如“先识别全文中的核心议题，通常按议题出现频次和讨论时长判断”——这样模型会更明确行为指令。
2.3 第三步：明确触发条件和退出条件
Skills 的触发条件比大多数人想象中更重要。一个技能如果随意触发，会造成资源浪费和输出干扰；如果触发太严，又得不到使用。
触发条件要分成两种：
- 显式触发：用户明确说“帮我整理纪要”“用纪要模板”，模型必须激活技能，不得用普通对话回应。
- 隐式触发：用户在闲聊中提到了会议内容，但没有明确要求整理，模型可以根据上下文判断是否值得激活。
过度设计会导致混乱。我的经验是：第一版先只支持显式触发，稳定后再考虑隐式触发。我在一次内部工具开发中加了过强的隐式触发，结果用户随便聊一句“昨天开了个会”就被判定为要整理纪要，反复打扰，最后还是关掉了。
退出条件也很关键。技能不能只要激活就一直执行到底。我通常会写明：“如果输入内容不足 100 字，或者明显不是会议记录，直接拒绝执行并提示用户提供有效输入。”一句话就能避免很多误触发。
2.4 第四步：设计异常处理和降级方案
任何技能都会遇到处理不了的输入，与其让模型硬着头皮输出一版乱码，不如提前设计好“优雅失败”的路径。
异常处理我一般分三层：
- 缺字段：必填字段缺失时，技能应该主动追问，而不是用空字符串填充。
- 内容不符合预期：输入内容格式和技能描述严重不匹配（比如把菜谱文本传给了纪要技能），直接说明“当前输入无法处理”。
- 模型输出异常：输出结构不符合约定格式时，需要校验机制。
最后这点很多人会忽略。技能执行完后，如果有一个轻量的“输出校验器”跑一遍结构检查，发现缺字段就自动触发一次修正，整体可靠性会提高非常多。我们团队后来把校验器做成了一段小代码：解析模型输出，检查必填字段，不通过就带着错误信息重新生成一次，成功率提升明显。
3. 实操过程：从0到1封装一个“会议纪要整理助手”
3.1 定义元信息和输入参数
理论说了一堆，直接上一个完整案例。这个案例是我团队内部在用的“会议纪要整理助手”，结构比较典型，适合作为模板。
技能文件整体由三部分组成：元信息、指令体、校验规则。元信息的作用是让模型知道“这个技能叫啥、干啥用的、啥时候该调”。
{ "name": "meeting_minutes_assistant", "description": "将会议转写文本整理为结构化会议纪要。当用户提到整理会议记录、会议纪要、会议要点时使用。", "version": "1.2.0", "input": { "transcript": "会议转写全文，必填", "topic": "会议主题，选填，若缺失则从文本中推断", "participants": "参会人列表，选填，若缺失则从文本中推断", "output_language": "输出语言，默认中文，可选中文或English" } }这个部分的关键是 description 要写得 “可被匹配”。我在多个模型中测试过，模型判断“该不该使用技能”主要靠 description 和当前用户消息的语义匹配程度。所以 description 里一定要包含至少三个同义触发词，比如“整理会议记录”“生成会议纪要”“提取会议要点”，单写一个“纪要整理”命中率会低很多。
参数定义尽量给默认值。用户不会每次都给你主题和参会人，但你可以在指令里要求模型“从转写文本中推断”，这样 output 完整性更高。
3.2 编写技能指令体（Prompt）
指令体是整个 Skills 的灵魂。我下面给出一版可以直接抄的完整指令，然后逐段解释每块文字的意义。
你是专业的会议纪要整理助手。 【执行前检查】 - 如果输入内容少于100字，或内容显然不是会议对话记录（如菜谱、代码、闲聊），回复：“当前输入无法整理为会议纪要，请提供会议转写文本。” - 如果缺少会议主题，从对话中推断并在结果中注明“推断主题”。 【执行步骤】 第一步：通读全部转写文本，过滤寒暄语、口头禅、重复表达。 第二步：识别文本中出现的所有核心议题，按重要程度排序。判断标准：议题讨论篇幅占比最高、或明确作为“结论”出现。 第三步：对每个核心议题，提取以下要素： - 讨论背景：该议题是在什么情况下被提出的 - 各方观点：围绕该议题出现了哪些不同意见，若有分歧需写明分歧点 - 最终结论：是否形成定论，定论内容是什么 第四步：扫描全文中所有与“时间点、责任人或负责人、具体动作”相关的语句，抽取为待办事项。 第五步：识别存在异议、尚未解决或需要领导决策的内容，归纳为风险与待决议题。 第六步：按固定模板生成纪要。 【输出格式】 严格按以下Markdown结构输出，不得增删章节： ## 会议概述（2-3句话概括会议目标） ## 讨论要点（按议题分条，每条包含背景、观点、结论） ## 决议事项（列出明确形成的结论） ## 待办事项（表格：事项描述 / 负责人 / 截止时间） ## 风险与待决事项（逐条列出，若没有写“无”）这版指令我打磨过很多次，有几个很关键的细节想单独说明。
第一步要求“过滤寒暄语”，是因为转写文本里经常有大量“喂喂听得到吗”“我先说一下哈”这类无效信息，如果不加这一句，模型会把它们也当成讨论要点放进纪要。第三部要求“按重要程度排序”，是为了防止模型按文本顺序流水账式输出。判断标准我写得尽量具体，好让模型有据可依。
输出格式里特别用了“固定 Markdown 结构 + 表格”。直接告诉模型“用表格输出待办事项”，比简单说“清晰一点”有效得多，因为模型对格式名词的响应远好于对抽象形容词的响应。
3.3 测试与调优：至少跑三组用例
写完技能不能直接上线，“拿来就用”的结果一定打脸。我每次都会跑三组测试用例：
第一组“标准用例”：给一段干净、结构清晰、有明确结论的会议转写文本，预期输出高质量纪要。这个用例帮我看清技能的主流程有没有问题。
第二组“边界用例”：给一段极短文本（比如朋友间的一句问候），预期触发拒绝逻辑，输出“当前输入无法整理”。这个用例帮我看清触发和退出条件是否生效。
第三组“脏数据用例”：给一段包含大量口语、无结论、多人同时抢话的转写文本。这个最贴近真实情况，也最能发现问题。
我贴上真实测试时的一段结果对比。用标准用例时输出很好，五个章节齐全，表格工整，结论表达也准确。问题出在脏数据用例：模型把一段激烈的讨论识别成了“决议事项”，但实际上只是几个人在争论，并没有形成结论。我发现后对指令第三步做了微调，加了一句“只有出现明确同意、确认、拍板等表述时，才能判定为决议”，重新测试后输出就正常了。
这个调试过程建议至少做三轮。第一轮修指令，第二轮修输入输出定义，第三轮修触发条件。后面你会发现主要工作变成了积累测试用例集，而不是改文字。
3.4 发布与版本管理
技能也会有版本迭代，这一点很多人完全没意识到。我在团队里强制要求每个技能文件头部必须带 version 字段，说明如下：
- 改动内容：变更了哪些指令、为什么要变。
- 评估结论：上一版本在哪些用例上表现不达标，本版本是否解决。
发布时建议采用灰度策略。先在一个小范围内开放新版本，观察 2 到 3 天日志中的触发率和失败率，再决定是否全量推送。我曾经跳过灰度直接全量更新，结果新描述把另一个技能的触发抢走了，用户体感明显变差，花了大半天才定位到原因。
4. 常见问题与排查技巧实录
4.1 技能不触发，消息被普通对话接走
这是最容易遇到的问题。排查思路有先后顺序：先看 description 里的触发词是否覆盖用户的实际表达；再看是否有其他技能的 description 与之语义重叠；最后看触发条件是否写得过于严格。
| 常见问题 | 可能原因 | 解决方案 |
|---|---|---|
| 技能不触发 | description 触发词与用户表达不匹配 | 补全同义触发词，在 description 中增加示例句式 |
| 技能不触发 | 多个技能描述语义重叠 | 调整描述，明确各技能的边界场景 |
| 技能不触发 | 设置了过严的隐式触发条件 | 优先支持显式触发，隐式触发后置 |
| 技能触发过度 | description 过于宽泛 | 加入“仅当用户明确表达……”的限制条件 |
我自己的排查经验是：把用户真实会话记录拉出来，看模型明明应该用技能却没用时，模型当时回复了什么。模型没调用技能的原因往往不是没看到描述，而是感觉当前消息“不值得调用”，这时候你就能反向定位描述中缺失的关键词。
4.2 输出格式混乱，章节经常缺失
这个问题几乎都出在指令体写得不够死。模型是很擅长“发挥”的，你只写“输出会议纪要”，它就能给你十个版本。
解决办法是把格式从“建议”改成“约束”。我习惯用“严格按以下模板输出，不得增删章节”这种语气。实测下来，这类强约束对格式稳定的帮助非常明显。如果还是不行，可以考虑加一层输出校验器，做结构化检查，缺少必填章节就带着错误信息重新生成。
这里分享一个我自己琢磨的技巧：把输出结构写在指令的“最后一段”，不要写在前面。模型对越靠近输出位置的指令遵守度越高，这是注意力分布导致的。把格式放末尾，比放在“你是助手”那种开场部分效果好得多。
4.3 幻觉严重，凭空生成不存在的“结论”
模型在整理会议纪要时，最让人头疼的行为就是“脑补”——明明没有说“同意”，它写出来一个“会议一致同意”；明明没有指定负责人，它写“由张三跟进”。
我在指令中加了三个层面的防御：第一层，写“所有结论必须能在原文中找到对应表述，禁止主观推断”；第二层，要求“如果没有明确提及负责人或截止时间，待办事项对应位置填‘待确认’”；第三层，在末尾加一个自检步骤，让模型回看输出并标注哪些内容是基于原文、哪些是推断。
这套“三层防御”不能 100% 消灭幻觉，但能把幻觉频率降到一个可以接受的水平。我实测在含 30 条无效信息的长转写文本上，无防御时会出现 4 到 5 处无中生有，加了防御后通常能控制在 1 处以内。
4.4 上下文越来越长，调用成本飙升
技能描述越长，模型每次调用消耗的 token 就越多。如果技能数量多，光是一块技能定义就能吃掉几千 token。
我给自己的限制是：单个技能指令体尽量控制在 800 字以内，核心逻辑优先，锻炼出来的经验是“与其把话写全，不如把话写准”。如果你的技能指令超过 2000 字，大概率是设计思路出了问题，需要重新拆解而不是继续增加文字。
另一个思路是，把技能按使用频率拆分。高频技能保持精简，低频场景使用完整版。我给“快速纪要”和“深度纪要”准备了两个版本，前者用于日常，后者用于重要会议，体验好很多。
4.5 排查技巧：日志要带技能名和耗时
这条整体上是通用的工程经验。给 Agent 程序加日志时，除了记录输入输出和 token 消耗，务必记录“本次使用了哪个技能、技能版本是多少、执行耗时是多少”。没有这份日志，后续所有问题排查都是瞎子摸象。
我有一阵子一直困惑为什么同样一段文本，换一个模型版本后输出质量波动很大，直到查日志才发现是模型在触发条件上的判断发生了变化。没有日志，这个原因可能要排查很久。
5. 最后再分享一点我的实操体会
技能体系这个东西，做的时候一定要克制。第一次动手时，很多人会想把所有流程都技能化，这个冲动我也有过，但实践下来最有效的做法是：先挑一个重复频率最高、痛点最明显的任务做第一个技能，让它完整跑完“定义接口 — 写出指令 — 测试调优 — 发布灰度”的闭环，再复制方法论到下一个场景。
另一个习惯是定期给技能库做“瘦身”。技能不是越多越好，我在季度回顾时经常发现有些技能已经三个月没用过了，但还在每次调用时占着上下文窗口，最后会统一归档。不要舍不得删，没用过的技能留着只会增加模型判断的负担。
最后分享一个小技巧：给每个技能留一个“调试模式”开关。在技能输入参数里加一个debug: true的选项，开启后模型会在输出末尾附加“本人使用了哪些步骤、从文本中抽取了哪些关键段落”的说明。这个功能调试时能帮你快速看清模型的判断逻辑，上线后关掉即可。我靠着这个开关解决了不少“一眼看起来输出没问题但就是不对劲”的疑难杂症。
如果你正在写自己的第一个技能，不用想太多，找一个重复性最强的场景，按这篇的流程动手写一版，哪怕一开始粗糙也没关系。跑起来，你就会有感觉。
