最近团队在搭 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的选项开启后模型会在输出末尾附加“本人使用了哪些步骤、从文本中抽取了哪些关键段落”的说明。这个功能调试时能帮你快速看清模型的判断逻辑上线后关掉即可。我靠着这个开关解决了不少“一眼看起来输出没问题但就是不对劲”的疑难杂症。如果你正在写自己的第一个技能不用想太多找一个重复性最强的场景按这篇的流程动手写一版哪怕一开始粗糙也没关系。跑起来你就会有感觉。