1. 从“skills”这个词说起它到底指什么“skills”这个词看起来简单但放在不同语境里含义差别很大。有人看到它想到的是招聘JD里的“技能要求”有人想到的是游戏里的“技能树”还有人想到的是AI领域里越来越火的“Agent Skills”——也就是让大模型调用外部工具、执行具体任务的能力模块。我这次要聊的是最后一种也是目前技术社区里讨论热度最高的那个方向。简单来说Agent Skills是一套让AI从“只会聊天”变成“能干活”的机制。你可以把它理解成给一个聪明的实习生配了一整套工具箱他本身脑子好使但光有脑子不够还得有螺丝刀、扳手、万用表才能真正把活干出来。Skills就是这些工具的定义、调用规范和组合方式。这个内容适合谁看如果你正在做AI应用开发想让模型不只是回答问题而是能查数据库、调API、生成文件、操作表格那这套东西你绕不开。如果你只是对AI感兴趣想搞清楚“为什么别人的AI能自动干活我的只能聊天”那这篇文章也能帮你把底层逻辑捋清楚。我会从设计思路、核心细节、实操过程到常见坑一层层拆开讲尽量让不同基础的人都能跟上。2. 整体设计思路为什么是Skills而不是别的方案2.1 从“提示词工程”到“技能工程”的转变早两年大家做AI应用主流思路是提示词工程——把需求写清楚把示例给足让模型照着输出。这个方法在纯文本任务上确实有效但一旦涉及“帮我查一下上个月的销售数据然后生成图表再发到群里”提示词就力不从心了。模型再聪明也没法凭一段文字就完成跨系统的操作。于是就有了Function Calling也就是让模型输出一个结构化的调用请求由外部程序去执行。这个思路已经接近Skills了但Function Calling有个问题每个函数都要单独定义参数格式、调用逻辑、错误处理全得自己写项目一大就乱成一锅粥。Skills的出现本质上是在Function Calling之上加了一层封装和编排。它把一组相关的操作打包成一个“技能”比如“数据处理技能”里可能包含读取、清洗、计算、导出四个子步骤。模型只需要知道“我要用数据处理技能”具体怎么调、按什么顺序调由技能内部自己管。这样做的好处很明显模型不用记那么多细节开发者也不用重复造轮子。2.2 为什么选择“技能”这个抽象层级有人可能会问为什么不直接做“工作流”把每一步都写死答案是灵活性。工作流适合流程固定的场景比如审批流但AI应用面对的需求往往是不确定的。用户今天问“帮我分析销售趋势”明天问“帮我对比两个产品的用户评价”你没法提前把所有流程都画出来。Skills的抽象层级刚好卡在中间比函数粗比工作流细。一个技能可以包含多个函数也可以根据输入动态选择执行路径。比如“数据分析技能”收到“趋势分析”就调时间序列模块收到“对比分析”就调分组统计模块。这种“半结构化”的设计既保留了灵活性又避免了每次都要从零编排。2.3 核心架构三层结构我实际落地时把整个系统分成三层技能注册层负责管理所有可用技能包括技能名称、描述、参数 schema、依赖关系。这一层相当于一个“技能目录”模型通过它知道“我有哪些本事”。技能执行层负责实际调用。收到模型的技能请求后解析参数、校验输入、按顺序执行子步骤、处理异常、返回结果。这一层是真正的“干活层”。技能编排层负责多技能协作。当一个任务需要多个技能配合时比如“先查数据再分析再生成报告”编排层决定调用顺序和传递方式。这三层分开的好处是各司其职。注册层只管“有什么”执行层只管“怎么干”编排层只管“按什么顺序干”。改一处不影响其他维护成本大幅降低。提示不要一上来就搞三层。如果技能数量少于5个直接用一个字典管理就够了。三层结构是给技能数量上规模后准备的过早抽象反而增加复杂度。3. 核心细节解析技能定义、参数校验与执行引擎3.1 技能定义怎么写才不容易出错技能定义是整个系统的入口写得好不好直接决定后续调用顺不顺。我踩过的坑是一开始把描述写得太简略模型根本不知道什么时候该用这个技能。后来总结出一个模板包含四个必填项name技能的唯一标识用英文小写加下划线比如query_sales_data。不要用中文不要用驼峰避免解析时出幺蛾子。description一句话说清楚“这个技能能做什么什么时候用”。比如“当用户需要查询指定时间范围内的销售数据时使用此技能”。描述里要包含触发条件模型才能判断该不该调。parameters参数列表每个参数要有类型、是否必填、描述。类型尽量用JSON Schema标准比如string、number、boolean、array。returns返回值说明。虽然模型不直接看这个但编排层需要知道返回什么格式才能决定下一步怎么处理。一个实际的技能定义长这样{ name: query_sales_data, description: 当用户需要查询指定时间范围内的销售数据时使用此技能。支持按地区、产品类别筛选。, parameters: { type: object, properties: { start_date: { type: string, description: 开始日期格式YYYY-MM-DD }, end_date: { type: string, description: 结束日期格式YYYY-MM-DD }, region: { type: string, description: 地区筛选可选值north, south, east, west, enum: [north, south, east, west] } }, required: [start_date, end_date] }, returns: { type: array, items: { type: object, properties: { date: {type: string}, amount: {type: number}, region: {type: string} } } } }这里有个细节enum一定要写。模型有时候会自己编一个不存在的地区值加上enum后校验层可以直接拦下来避免脏数据进到执行层。3.2 参数校验别让模型传什么你就收什么模型输出的参数永远不要直接信任。我见过太多次模型把日期写成“2024年1月1日”而不是“2024-01-01”把数字写成字符串“100”而不是100。如果执行层不做校验轻则报错重则写脏数据。我的做法是在执行层前面加一个校验中间件按顺序做四件事类型检查参数类型是否匹配定义。不匹配就尝试转换转换失败直接返回错误。必填检查required列表里的参数是否都传了。缺了就返回“缺少必要参数xxx”。枚举检查如果参数定义了enum检查值是否在允许范围内。范围检查数字参数检查是否在合理区间字符串检查长度是否超限。校验失败时返回给模型的错误信息要具体且可操作。比如“日期格式错误请使用YYYY-MM-DD格式”就比“参数错误”好得多。模型看到具体错误后下一轮往往能自己纠正。注意校验不要做太严。比如日期格式除了YYYY-MM-DD也允许YYYY/MM/DD然后在内部统一转换。太严的校验会让模型频繁失败用户体验很差。3.3 执行引擎同步、异步与超时处理执行引擎是真正调用外部服务的地方。这里的关键决策是同步还是异步。同步执行调用后一直等结果适合快速返回的操作比如查内存缓存、简单计算。优点是逻辑简单缺点是如果外部服务慢整个链路都卡住。异步执行调用后立即返回一个任务ID后续通过轮询或回调获取结果。适合耗时操作比如调用外部API、生成大文件。我的经验是默认同步超时切异步。给每个技能设置一个超时阈值比如3秒。3秒内返回就同步处理超过3秒就转成异步任务返回任务ID让上层轮询。这样既保证了简单场景的响应速度又避免了长耗时操作阻塞整个系统。超时处理还有个细节超时后要取消底层调用。不然外部服务还在跑资源白白浪费。Python里可以用asyncio.wait_for配合CancelledError来实现Node.js里可以用AbortController。import asyncio async def execute_skill(skill_func, params, timeout3.0): try: result await asyncio.wait_for(skill_func(**params), timeouttimeout) return {status: success, data: result} except asyncio.TimeoutError: task_id create_async_task(skill_func, params) return {status: pending, task_id: task_id} except Exception as e: return {status: error, message: str(e)}这段代码是我实际项目里简化出来的核心就是wait_for加异常捕获。注意create_async_task要把任务丢到后台队列里不能直接await否则又变同步了。4. 实操过程从零搭一个可用的Skills系统4.1 环境准备与依赖选择我用的技术栈是 Python FastAPI Pydantic。选这套的理由很简单Python生态好数据处理、API调用、文件操作的库都全。FastAPI自带异步支持写接口快文档自动生成。Pydantic做参数校验和序列化和JSON Schema天然兼容省得自己写校验逻辑。安装依赖就三行pip install fastapi uvicorn pydantic httpxhttpx是用来调外部API的支持异步比requests更适合高并发场景。4.2 技能注册与发现机制技能注册我用了装饰器模式。定义一个skill装饰器挂在函数上自动把技能信息注册到全局字典里。SKILL_REGISTRY {} def skill(name, description, parameters, returns): def decorator(func): SKILL_REGISTRY[name] { name: name, description: description, parameters: parameters, returns: returns, func: func } return func return decorator skill( namequery_sales_data, description查询指定时间范围内的销售数据, parameters{...}, returns{...} ) async def query_sales_data(start_date, end_date, regionNone): # 实际查询逻辑 pass这样做的好处是定义和使用在一起改技能的时候不用到处找配置文件。注册完以后通过SKILL_REGISTRY就能拿到所有技能的定义生成给模型看的技能列表。4.3 模型调用与技能路由模型调用这块我用的是两阶段路由第一阶段把用户输入和技能列表一起发给模型让模型输出一个JSON包含skill_name和parameters。提示词大概是这样你是一个技能调度器。根据用户输入从以下技能中选择最合适的一个并提取参数。 可用技能 {skill_list} 用户输入{user_input} 请输出JSON格式{skill_name: ..., parameters: {...}}第二阶段拿到模型的输出后先校验skill_name是否在注册表里再校验parameters是否符合定义。都通过后调用对应的函数执行。这里有个坑模型有时候会输出多个技能。比如用户说“查一下销售数据然后生成图表”模型可能返回两个技能。这时候就需要编排层介入按顺序执行。我的做法是让模型输出一个数组编排层遍历执行前一个的输出作为后一个的输入。4.4 结果返回与错误处理执行完技能后结果要格式化后返回给模型让模型生成自然语言回复。格式我统一用{ status: success, data: {...}, skill_name: query_sales_data }如果出错返回{ status: error, message: 具体错误信息, skill_name: query_sales_data }模型看到error后可以选择重试、换技能、或者直接告诉用户“这个操作失败了原因是xxx”。实测下来给模型具体的错误信息比给一个笼统的“失败”要好得多模型自己就能纠正很多问题。实操心得错误信息里不要暴露内部堆栈和敏感路径。我一般会把原始错误记到日志里返回给模型的是经过脱敏的简短描述。5. 常见问题与排查技巧实录5.1 模型不调用技能只聊天怎么办这是最常见的问题。模型明明看到了技能列表但就是不用直接用自己的知识回答。原因通常有三个技能描述不够具体模型不知道什么时候该用。解决办法是把描述写得更“场景化”比如“当用户询问具体销售数字时使用”而不是“查询销售数据”。提示词里没强调必须用技能可以在系统提示里加一句“如果可用技能能回答问题优先调用技能不要凭记忆回答”。技能太多模型挑花眼如果技能超过20个模型的选择准确率会下降。解决办法是分组先让模型选组再选具体技能。5.2 参数提取错误怎么排查参数错误分两类格式错误和语义错误。格式错误好办校验层直接拦。语义错误麻烦一些比如用户说“上个月”模型提取成“2024-01-01”到“2024-01-31”但实际“上个月”可能是“2024-02-01”到“2024-02-29”。这种需要在技能内部做二次校验比如检查日期范围是否合理不合理就返回错误让模型重新提取。我一般会在技能描述里加一句“日期请使用YYYY-MM-DD格式不要使用相对时间”减少这类问题。5.3 技能执行超时或卡死超时问题前面提过用wait_for加异步任务解决。卡死通常是外部服务无响应这时候除了超时还要加重试机制。我的重试策略是最多重试2次每次重试间隔1秒、2秒指数退避重试仍失败则返回错误重试只对幂等操作有效比如查询。如果是写操作重试可能导致重复写入要谨慎。5.4 多技能编排时的数据传递多技能编排最容易出的问题是数据格式不匹配。技能A返回一个数组技能B期望一个对象直接传就报错。解决办法是在编排层加一个适配器负责在技能之间转换数据格式。我的做法是让每个技能定义里加一个input_mapping字段描述“我的输入可以从哪些字段来”。编排层根据这个映射自动从上一个技能的输出里提取数据。这样技能之间就解耦了改一个不影响另一个。5.5 常见问题速查表问题现象可能原因排查方向解决办法模型不调用技能描述不具体/提示词没强调检查技能描述和系统提示补充场景化描述加“优先调用”指令参数格式错误模型输出不规范查看模型原始输出加强校验返回具体错误让模型重试参数语义错误相对时间/模糊指代检查用户输入和提取结果技能内二次校验描述里限制格式执行超时外部服务慢/无响应查看日志中的耗时超时切异步加指数退避重试多技能数据不匹配返回格式和输入格式不一致检查技能间的数据流加适配器定义input_mapping技能选择错误技能太多/描述重叠查看模型选择的技能分组路由合并相似技能6. 进阶技巧让Skills系统更稳、更快、更好维护6.1 技能版本管理技能一旦上线就不能随便改。改了参数调用方可能就挂了。我的做法是给技能加版本号比如query_sales_data_v1、query_sales_data_v2。新版本上线后旧版本保留一段时间等所有调用方迁移完再下线。版本号放在技能名里模型调用时指定版本。如果模型没指定默认用最新版。这样既保证了兼容性又给了迁移缓冲期。6.2 技能缓存有些技能是幂等且结果稳定的比如“查询城市列表”“获取汇率”。这类技能的结果可以缓存减少重复调用。我用的是内存缓存加TTL简单场景够用。如果技能数量多、缓存需求大可以上Redis。缓存键的生成规则要小心把技能名和所有参数拼起来做哈希。参数顺序不同但内容相同的情况要先排序再哈希避免缓存击穿。6.3 技能监控与告警生产环境里技能调用必须监控。我关注四个指标调用次数每个技能被调了多少次找出高频和低频技能。成功率成功调用占比低于95%就要查。平均耗时超过阈值的技能要优化。错误分布哪类错误最多针对性修复。这些指标用Prometheus加Grafana就能搞定FastAPI有现成的中间件可以用。6.4 技能文档自动生成技能定义本身就是文档。我写了一个脚本读取SKILL_REGISTRY自动生成Markdown格式的技能文档包含名称、描述、参数表、返回值示例。每次技能更新后跑一下脚本文档自动同步省得手动维护。这个脚本还能生成给模型看的技能列表格式和文档一致保证模型看到的信息和开发者看到的一致。7. 我个人在实际操作中的几点体会这套Skills系统我在几个项目里落地过最大的感受是技能粒度比技术选型更重要。一开始我把技能拆得太细一个“查数据”拆成“连数据库”“执行查询”“格式化结果”三个技能结果模型调用时经常漏步骤。后来合并成一个技能内部自己管流程调用成功率立刻上去了。另一个体会是错误信息要写给模型看不是写给人看。人看到“KeyError: start_date”知道是缺参数模型看到这个就懵了。改成“缺少必要参数start_date请补充后重试”模型下一轮就能自己补上。最后分享一个小技巧定期用真实用户输入做回归测试。把历史调用记录拿出来重新跑一遍看技能选择、参数提取、执行结果是否和预期一致。我一般每周跑一次能提前发现模型行为漂移的问题。这个习惯帮我避免了好几次线上事故。