1. 从“会调 API”到“会写 Skills”这一步到底差在哪先说个我自己的感受。两年前我刚开始接触 Agent 开发时觉得 Skills 不过是给模型写一段提示词、塞几个函数定义而已。直到某次做一个跨平台系统的项目需要在 Agent 里集成文档解析、表格提取和邮件发送三个能力我才发现真正难的不是把功能跑通而是让 Agent 在复杂场景里稳定地、准确地把这些能力组合起来用。那段时间我看了大量开源项目参考了不少 Skill 定义自己也踩了不少坑才逐渐琢磨出一套相对系统的设计方法。如果你也正在做 AI Agent 开发大概率已经发现一个问题市面上关于“怎么写 Prompt”的内容很多但关于“怎么把一个能力封装成高质量 Skill”的体系化资料其实很少。很多人写完一个 Skill丢给 Agent 用结果要么调用参数一塌糊涂要么模型根本不知道什么时候该用这个能力要么输入输出结构混乱解析频频出错。这不是模型不行而是 Skill 本身的设计有问题。这篇文章就是我基于自己从 0 到 1 设计和编写 Skills 的经验总结。我不打算讲太多玄乎的理论重点放在一个 Skills 到底应该包含哪些部分、每个部分该怎么设计、有哪些决策需要考虑、我在实际项目中踩过哪些坑。适合正在做 Agent 开发、或者准备把业务能力封装成 Agent 可调用工具的同学参考。不管你是刚入门的新手还是已经写过几个 Skill 但觉得不够稳定的人这篇文章应该都能给你一些可落地的启发。2. 动手之前先想清楚Skill 的本质是“能力封装”不是“功能堆砌”2.1 一句话说清楚 Skill 是什么说白了一个 Skill 就是让 Agent 具备某项能力的最小封装单元。它不只是“一段提示词”也不只是“一个函数”而是三样东西的组合触发条件什么时候用、执行方式怎么用、入参出参用成什么样算成功。我在某图像处理 Demo 的项目里做过一个很典型的对比试验。同一个“图片压缩”功能方案 A 是把功能说明写在一段很长的系统提示词里方案 B 是封装成一个 Skill。实测下来方案 B 的调用成功率高出一截因为模型不需要在冗长的系统提示词里去“找”能力边界而是通过 Skill 的描述、参数定义、示例输出快速判断“这个场景符合我的调用条件”。这个区别非常关键。Agent 的能力不是越全越好而是越清晰越好。一个 Skill 写得是否高质量直接决定了 Agent 在真实场景中的行为稳定性。2.2 很多人会搞混的三个概念我经常看到有人把 Skill、插件、工作流混在一起用。在这里我做一次清晰的区分概念本质典型使用场景Skill单点能力的封装图片处理、文档解析、天气查询Plugin插件多个 Skill 的组合打包一套完整的 CRM 集成方案Workflow工作流固定顺序的能力编排从数据抓取到报告生成的全链路搞清楚这三者的区别你才不会在架构设计时选错粒度。我在某跨平台系统里见过一个反面案例把“读取文件”和“解析文件内容”分别写成两个 Skill又用工作流把它们串起来。看起来像是“解耦”实际上增加了调度的复杂度模型经常不知道该先调用哪一个白白多走一次工具调用。正确的做法是把“读取 解析”合并成一个 Skill一个入参拿到路径直接返回结构化结果。2.3 高质量 Skill 的三个核心要素根据我自己反复迭代的经验一个 Skill 要算得上“高质量”至少得满足三件事第一职责单一。一个 Skill 只做一件事。拿“文档解析”举例不要塞进去“解析完顺手总结一下”这种功能那应该是另一个 Skill 或下游步骤的事。职责一旦超出边界模型的判断就会飘。第二触发条件明确。Skill 描述里要写清楚什么情况下应该调用它什么情况下不应该调用。很多新手会在描述里含糊其辞比如只说“解析文档”结果模型在用户要求写文章时也试图调用这个 Skill这就是描述写得太宽泛导致的误触发。第三参数定义严谨。每个参数的类型、必填性、取值范围、示例值都要交代清楚。这不是为了好看而是因为模型的 token 推理能力是有限的参数定义越清晰它越不容易编造值。3. Skill 设计清单我每次动手前必过的 6 个项目3.1 明确 Skill 的“触发器”和“非触发器”这一条我把优先级放在所有设计步骤之前。很多 Skill 写出来不是不能用而是“乱用”。触发器写得好不好直接影响模型是否能正确决策。以我写的“表格信息抽取” Skill 为例我在描述里明确写了触发器用户要求从图片、PDF 或网页中提取表格数据结构化输出。非触发器用户只提及“表格”但并未要求提取用户提供的数据已经是结构化格式CSV、Excel。这一小段文字拯救了我无数次。因为模型在没有明确边界时倾向于“宁可错杀不可放过”看到任何和表格沾边的内容都尝试调用抽取功能。这会导致两个问题一是额外的工具调用增加了响应延迟二是错误调用后生成的输出常常是模型“硬转”出来的和数据源完全不符。3.2 一句话定义“输入输出契约”在写任何代码之前先把输入和输出定义好。这是整个 Skill 设计的骨架。输入部分要写清楚每个参数的名字、类型、是否必填参数之间的依赖关系比如“file_path 和 file_url 二选一”参数的取值范围和边界条件输出部分要给出明确的结构。我是强烈建议输出使用 JSON 结构的因为 Agent 后续还需要继续推理一个结构混乱的纯文本输出会让后续步骤很难处理。用“文档解析”举个例子我会把输出定义成这样{ status: success, metadata: { source: example.pdf, page_count: 8 }, content: [ { type: heading, text: 第一章概述, level: 1 }, { type: paragraph, text: 这里是正文内容... } ] }这个结构既保住了文档的层级信息又让 Agent 可以直接基于结构化内容做摘要、改写或信息提取。3.3 给每个参数配一个“人类看得懂的示例”这个细节看着简单做的人很少。很多 Skill 定义里的参数说明写的是“文件路径”然后就没了。我实测下来给参数配一个具体的示例值模型在选择参数时的准确率会明显提升。因为在模型眼里“file_path: 文件路径”和“file_path: 例如 /data/reports/2024年销售报表.pdf”是完全不同的信息量。还有一个小技巧参数名本身也要起得“有语义”。用source_file比用file好用output_format比用format好。因为模型在推理时会从参数名本身获取大量语义信息参数名太泛反而不利于它理解该传什么。3.4 写清楚“成功”和“失败”的画面这一条是我自己在踩过坑之后才加进设计清单里的。很多 Skill 只写了“能做什么”却没有写“做不了什么”或者“失败时会怎样”。后果就是当 Skill 执行失败时Agent 常常陷入困惑要么向用户输出一段乱七八糟的报错要么尝试用一个不可能成功的方式重试。我的做法是在 Skill 描述里专门加一个“常见失败场景”段落。比如我的“PDF 解析” Skill 里会写注意如果 PDF 是扫描版且未包含任何文本层解析结果将为空。此时应主动告知用户该 PDF 需要先做 OCR 处理不要反复尝试解析。就是这么一句话把可能出现的死循环和无效重试直接掐掉了。3.5 定义“Skill 之间的关系”当项目体量变大Skill 数量变多模型在多个 Skill 之间做选择就会变得困难。这时候Skill 定义里加一段“与相关 Skill 的关系说明”就显得很重要。举个例子我在某跨平台系统里同时有“表格抽取”和“文档结构解析”两个 Skill。如果不在定义里说明“表格抽取 是 文档结构解析 的子能力当用户需要表格数据时可直接调用 表格抽取”模型就可能把两个 Skill 都调一遍白费一轮工具调用。你在设计时要主动给模型“指路”。这就像一个新员工入职你光给他一堆工具是不够的你还要告诉他这些问题该找哪个同事、什么情况下别麻烦别人。3.6 预留“扩展后门”最后一点是关于架构的。Skill 设计不要写死给后面的迭代留一点空间。比如输出结构里加一个extension字段或者参数设计时允许某种程度的宽松匹配。这个不一定每个 Skill 都要用但一旦后续有新的需求你会发现预留了这个口子改动成本会小很多。4. 手把手写一个完整 Skill从想法到落地全程4.1 需求描述一个“会议纪要整理” Skill拿一个我近期真实做过的项目来演示。某团队需要一个 Agent 能力上传一段会议录音的文字稿自动整理成结构化的会议纪要。这个需求听上去不复杂但真做起来里面有好几个关键设计点。先看最终交付的 Skill 定义我精简过保留核心{ name: meeting_minutes_formatter, description: 将会议录音转写后的原始文本整理为结构化会议纪要。触发条件用户提供会议转写文本并要求生成纪要、总结、行动项或决定。不触发场景用户仅询问会议相关的一般性问题无原始文本输入。, parameters: { type: object, properties: { transcript_text: { type: string, description: 会议转写全文应为未经整理的原始文本。, minLength: 10 }, language: { type: string, enum: [zh-CN, en], description: 纪要输出语言默认与转写文本一致。, default: zh-CN }, format_options: { type: object, description: 可选的格式偏好, properties: { include_decision_log: { type: boolean, description: 是否单独列出决策记录, default: true }, action_item_owner_required: { type: boolean, description: 行动项是否必须标注负责人, default: true } } } }, required: [transcript_text] } }这段定义的优点在于参数极少且每个参数都有明确的语义。transcript_text是整个 Skill 的唯一必填项其他都是可选配置。这会让模型调用时的负担非常小。4.2 内部处理的 5 个阶段光有外壳还不够Skill 的核心逻辑要能真正跑出高质量结果。我在实现这个 Skill 时把内部处理流程分成了 5 个阶段第一段落分割。把转写文本按话题边界切分成多个语义块。这一步我用的是基于换行和话题词的双重判断效果比单纯按行切分好很多。第二发言者归一化。转写文本里的说话人可能很混乱有时候是“A”有时候是“甲”有时候直接是“——”开头。归一化后统一为“发言人1、发言人2”或者按实际名字映射。第三信息分类。把归一化后的内容映射到五个类别议题、决定、行动项、待办风险、悬而未决问题。这一步是整个 Skill 最见功力的一部分。第四结构化输出。按预设的 JSON 模板输出纪要。结构大致是会议概要、议题明细、决定记录、行动项列表、遗留问题列表。第五质量检查。检查输出中是否包含“之后再说”“下次讨论”这类悬而未决的表述如果有自动补到遗留问题区去。这个小设计避免了很多遗漏。4.3 参数为什么这样设计逐个说清楚可能有人会问format_options这种嵌套参数加了真的有用吗我自己的实测体会是有用但要注意使用频率。模型不会每次都主动携带嵌套参数调用大部分时候它会用默认值。这其实正好——那些需要细致格式控制的场景用户会主动提出模型才会去调整参数。另一个很多人会忽略的点是底层服务的超时和失败反馈。我习惯在任何 Skill 里加一个_meta字段记录调用耗时和异常信息。这个字段不会展示给终端用户但它对排查问题非常有价值。当你发现某个场景下 Agent 频繁调用同一个 Skill 但结果总是不对时这个_meta就是你第一手的数据。4.4 用最少的代码把这个 Skill 跑通Skill 定义只是“说明书”真正要被 Agent 调用的是背后的执行函数。我这里用一个简单的 Python 示例演示核心处理流程import json import re def format_minutes(transcript_text, languagezh-CN, include_decision_logTrue, action_item_owner_requiredTrue): # 阶段1段落分割 segments segment_by_topic(transcript_text) # 阶段2发言者归一化 normalized normalize_speakers(segments) # 阶段3信息分类 categories classify_information(normalized) # 阶段4结构化输出 minutes { summary: generate_summary(categories), topics: categories[topics], decisions: categories[decisions], action_items: categories[action_items], open_questions: categories[open_questions], } if not include_decision_log: minutes.pop(decisions, None) if action_item_owner_required: validate_owners(minutes[action_items]) return json.dumps(minutes, ensure_asciiFalse, indent2)这个函数有个很有意思的细节如果action_item_owner_required为真我会在返回之前校验每个行动项是否都有负责人。如果缺不是直接报错而是触发一次“补充问答”逻辑主动询问用户某个行动项该指派给谁。这个交互设计能让最终纪要的质量提升一大截。4.5 写好提示词内嵌逻辑Skill 不是只靠代码很多开发者犯了一个认知错误觉得 Skill 的逻辑全靠代码写死和提示词没什么关系。大错特错。Skill 最终是给模型用的模型需要在调用工具后继续推理。如果函数返回的内容格式混乱、语气僵硬模型后续处理时往往会把这种混乱延续下去。我会在函数的返回值里加入一些隐式的“模型提示”比如在summary字段里直接给出一句可用于向用户展示的流畅总结而不是返回一堆零散数据让模型自己再组织语言。这样能显著降低模型的二次处理成本最终用户的阅读体验也好很多。5. 工具选型与 Parser 选择这些决策不能拍脑袋5.1 不同解析器之间的取舍现在主流的 Agent 框架里Skill 参数解析通常有几种方式基于 JSON Schema 的严格解析、基于函数调用的原生解析、以及基于自然语言的宽松解析。这三者有明确的适用场景。解析方式优点缺点适用场景JSON Schema 严格解析参数结构可控、可校验对模型生成要求高参数固定、业务逻辑清晰的场景原生函数调用解析调用链路短、稳定依赖框架实现绝大多数规范化开发场景自然语言宽松解析模型自由度大输出不可控创意类、开放式任务我在做严肃业务时几乎只用前两种宽松解析只在原型验证阶段才会考虑。原因很简单不可控的输出会在后续环节连环引爆问题排查成本远大于一开始写清楚 Schema 的成本。5.2 什么时候该用自定义 Parser如果你遇到的是高度专业化的输入格式比如医疗影像报告、法律文书或者多语言混合文本那通用解析器可能不够用。这时候自定义 Parser 是值得投入的。我自己有个判断标准当通用解析器在真实流量下的失败率超过 5%就值得花时间去写自定义解析。5% 看起来不高但在高频调用场景里每 20 次就错一次的用户体验会很糟糕而且 Agent 链式调用时错误会被放大最后生成的结果可能在业务上完全不可用。自定义 Parser 可以从三处着手一是参数预处理清洗异常值二是容错修正对常见模型输出偏差做矫正比如把 “True” 和 “true” 归一化三是结构重组把模型输出的嵌套结构拍平或重新分组。5.3 我推荐的最小依赖方案很多人写 Skill 时有一个迷思一定要用某个重量级框架。其实不然。Agent 的 Skill 本质上是“模块 定义 运行时”。你可以用一个非常轻量的运行时定义文件用 JSON 或 YAML执行逻辑用单文件 Python 函数参数校验用内置的jsonschema库不做额外封装直接在框架里注册这种最小依赖方案的好处是任何框架都能接不会有绑定风险。等业务量大了需要平台化再把 Skill 迁移到插件体系里也不晚。我见过太多项目一开始就上了重型框架结果被框架的约束牵着走Skill 本身的设计反而被忽略。6. 测试与调试高质量 Skill 是“泡”出来的6.1 建一个属于你自己的“语料测试集”这是我最想跟各位分享的一条实操经验。Skill 写完后一定要建一个测试语料集而且要贴近真实输入。我在每个 Skill 项目里都会维护一个test_cases/目录里面放着20 个正常输入样本5 个边界输入样本比如空文本、超长文本5 个异常输入样本比如格式混乱、字段缺失每次改动 Skill 后把整个测试集跑一遍记录通过率。这个习惯让我在一次参数结构大调整后及时发现了 16 个回归问题避免了线上故障。6.2 用“分层测试”替代“只测最终结果”很多人在测试 Skill 时只看“最终调用成没成功”。太粗了。我会拆成三层来测触发层模型在正确场景下是否调用了这个 Skill错误场景下是否没有调用参数层模型生成的参数是否符合 Schema有没有漏填、类型错误执行层真正的函数执行是否返回了预期结果这三层任何一层出问题优化手段都完全不同。触发层要调描述文本参数层要调 Schema 定义和示例执行层要调底层逻辑。不分层的话你会到处试越试越乱。6.3 实测现场一次调参定位的全过程分享一次印象深刻的实测过程。某次我给“会议纪要整理” Skill 加了一个detect_action_items的新开关参数默认值为true。上线后我发现一个诡异问题模型在用户没有明确要求行动项时也会在纪要中加入“行动项”板块。第一反应是参数没生效。查了执行层日志发现detect_action_items确实接收到了默认值true。问题出在模型对“要求行动项”的理解用户说“帮我总结一下会议”时模型觉得总结本身就隐含了行动项提取。修复办法不是把默认值改成false而是在 Skill 描述里明确写上行动项是参会人员明确认领或承诺的具体任务。如果转写文本中没有明显认领关系不要编造行动项此时 action_items 字段返回空列表即可。在这段描述加上之前模型在约 30% 的测试用例里会编造行动项。加上后这个比例降到了 12%。后来又进一步在 Schema 里对action_items增加了minItems: 0的注解模型才开始真正理解“没有就是没有”。这件事给我的启发是修 Skill 的行为问题百分之八十靠的不是改代码而是改描述、改示例、改边界条件。7. 常见坑与避坑策略这些坑我替你踩过了7.1 参数太多把模型“吓住”了新手最容易犯的毛病是把所有可配置项全部列成参数。比如“会议纪要整理” Skill有人会设计出 8 个参数是否包含议题、是否包含决定、是否包含风险项、是否标注重急、是否包含参会人名单……看起来灵活实际上模型每调用一次都要消耗大量 token 来理解这些参数而且经常传错、漏传。我的经验是任何 Skill 的参数控制在 3 个以内其中必填项不超过 2 个。多出来的配置需求用默认值覆盖。模型只有在用户明确提出时才会去调整可选参数本来就很低频。参数一少误传率立刻下降调试也容易得多。7.2 返回值太复杂模型“接不住”有些 Skill 返回一个包含 10 个字段的 JSON其中 5 个字段在后续逻辑中根本用不到。你是把数据留全了但模型面对这些多余字段时会把部分垃圾信息带进自己的推理过程中。我的建议是在 Skill 返回给模型之前加一个“精简层”。只保留模型后续需要用到的字段其余信息放到日志或缓存里。比如“文档解析” Skill模型后续只需要正文内容和文档属性就不用把每一页的原始坐标、字体信息都带出来。精简后不仅 token 少了推理准确率也会提上去。7.3 描述里用词模糊触发频繁失控“尽量”“可能”“相关”这类词在 Skill 描述里我一律禁用。原因很简单模型对模糊词的理解和人不完全一样你写“处理相关文档”它会以为任何文档都相关。描述里必须用明确的动作词提取、生成、转换、校验、汇总。每个动词背后都是一个可以被精确判断的边界。7.4 对“失败”没有预案Agent 容易死循环如果 Skill 执行失败后不返回结构化的错误码只返回一句 “Error: cannot parse file”Agent 大概率会再调一次同样的参数重试陷入死循环。正确的做法是错误码 建议动作。比如{ code: PARSE_FAILED, message: PDF 内容无法解析可能为扫描版, suggestion: 建议用户先进行 OCR 处理再重新提交 }这个suggestion字段是我后来加的加之后线上重试率明显降下来了。Agent 不再盲目重试而是直接把建议动作转述给用户用户体验判若云泥。7.5 没有版本管理改坏了回不去Skill 也会有“改崩了”的时刻。我强烈建议每个 Skill 定义和实现都要纳入 Git 管理并且用语义化版本号标记大版本变化代表接口不兼容小版本变化代表参数新增或描述调整补丁号对应纯 bug 修复。这样你在迭代多个 Skill 时心里始终有底。8. 从“单个 Skill”到“一组 Skills”的架构思考8.1 Skill 之间的“互斥”与“依赖”当你超过 5 个 Skill 时你就会发现 Skill 之间不是孤岛。两个 Skill 可能针对同一类输入这时候必须在描述里写明边界让模型能做出区分。比如“图像分类”和“图像标签”看起来相近实际完全不同如果描述不够清楚模型会随机选一个导致任务执行结果不可预期。依赖关系也一样。有些 Skill 必须在另一个 Skill 执行之后才有意义。比如“数据分析” Skill 依赖“数据清洗” Skill 的输出。这种依赖最好用约定式的输出结构来表达而不是在 Skill 内部去硬解析上游结果。保持每个 Skill 的单点独立性会让整个系统更健壮。8.2 全局描述页的重要性当 Skill 数量多了我强烈建议你在 Agent 的全局上下文里维护一张“能力地图”。不用写很长就一张表每个 Skill 的名字、一句话说明、与其他 Skill 的边界。这能大幅降低模型在多个 Skill 之间的决策失误率实际效果非常明显。我自己维护过一张包含 12 个 Skill 的能力地图模型的任务路由准确率从 74% 提升到了 89%。这张能力地图不是一次写完就完事每次新增或修改 Skill都要同步更新。9. 认知之外的扩展多语言、多模态、多分支场景9.1 让 Skill 在中文和英文场景下都稳定很多 Skill 在单一语言下表现良好换到另一种语言就频繁出错。原因通常是描述和示例的语言风格过于单一模型对跨语言的指令泛化不足。我的习惯是所有 Skill 描述都提供中英双语且示例值也做双语版本。这样在用户切换语言场景时模型的触发率不会有断崖式下跌。9.2 多模态输入的 Skill 设计差异如果输入不仅是文本还包含图片、表格、音频Skill 的参数定义就要重新想。比如用户要“提取图片里的表格”传参就不能只有text还得考虑image_base64或者file_url。而且你要为模型写清楚是完全依赖视觉模型识别还是用 OCR 先抽取再结构化。这个选择会直接影响 Skill 的返回质量和速度。9.3 单元测试和回归测试质量门槛不能省最后不管你的 Skill 多简单不要略过测试。每次改动后跑一遍测试集是我个人看来最低成本的质量保障手段。我现在写每个 Skill 时会内置一组最小测试用例至少覆盖“正常输入”“边界输入”“异常输入”三类。这是一种习惯更是一道基本的安全网。后面规模大了这批测试用例一定会帮你兜住不少低级错误。10. 收尾一点判断标准供你自查如果要我给“高质量 Skill”下一个更容易操作的定义我会用四个维度触发准确、参数稳定、失败得体、扩展方便。写完一个 Skill拿这四个维度各打一遍分基本就知道哪里还需要迭代了。这也是我一个人来回改了很多版 Skill 之后的真实体会。每个 Skill 背后真正需要反复打磨的往往不是代码逻辑而是对模型行为边界的理解。写 Skill 这件事本质上不是写功能而是在调教 Agent 的行为。想清楚这个认知你写出来的 Skill 跟别人写的差距就已经拉开了。