agent-skills我是怎么把智能体从“会聊天”调教成“能干活”的做智能体Agent开发这段时间“agent-skills”这个方向我踩了不少坑也沉淀了不少东西。说白了skills 解决的是一个特别现实的问题大模型能力强但“使唤不动”。你说让模型自由发挥它可能跟你聊得天花乱坠但真让它去查个数据库、调个接口、算个指标它要么编数据要么把参数传错。问题不在模型本身而在于我们没给它一套清晰、可复用、可校验的“干活技能”。所以就有了 agent-skills 这套思路把智能体需要执行的每一项能力从“随口吩咐”改造成“模块化技能”。每个技能有明确的名称、描述、参数定义、执行逻辑、返回格式。智能体遇到任务时不是靠猜而是靠“检索调度”把对应技能匹配出来按固定的方式执行。这样一来同样一件事不管用户怎么说智能体都知道该走哪条链路结果也稳定得多。项目面向的人群很明确正在做智能体应用开发的工程师、想把大模型接入业务系统的技术负责人还有对 AI Agent 内部机制好奇、想动手实践的学习者。下面我把整个项目从设计思路、字段规范、编写实操、注册调度到排障实录完整拆开讲一遍。这不是官方文档式的介绍是我自己动手做的时候理清的思路和踩过的坑。1. 整体思路为什么“技能”比“提示词”更扛得住事1.1 从“让模型自由发挥”到“给模型定义技能”最开始做智能体的时候我采用的是最朴素的方案写一个系统提示词System Prompt把业务规则、工具列表、输出格式全塞进去然后让模型自己判断什么时候用什么工具。看起来挺灵活实际一测就发现问题提示词越长模型越容易“选择性遗忘”。尤其是工具一多、参数一杂模型经常调错工具、漏传参数或者在某个分支上纠缠太久。同样是“查一下上个月销售额”它有时候调报表接口有时候直接开始编数字完全看心情。这里要解释一个核心现象大模型本质上是一个“下一个词预测器”它对所有指令的理解都是概率性的。提示词写得再详细也只是“提高了理解对的可能性”并不能保证每一次执行都稳定。而agent-skills 的思路是把“理解”和“执行”拆开。理解层仍然交给大模型让它从技能库里匹配最合适的技能执行层则完全交给确定性代码。模型只负责判断“该用哪个技能”不负责“自己去想怎么执行”。判断错了顶多是技能选错执行结果却一定是确定的、可校验的。打个比方这就像带新人。你让新人“看情况处理客户问题”纯提示词他大概率手足无措但你给他一套 SOP客户投诉→先道歉→再记录→再确认处理时间技能库他按流程走效果就稳定多了。skills 就是 Agent 的 SOP把模糊的要求变成可复用的流程模块。1.2 agent-skills 的边界技能、工具和知识库到底是什么关系新手经常把三个概念混在一起工具Tool、知识库Knowledge、技能Skill。我在项目里把它们做了严格区分这个区分直接影响架构设计。工具是最底层的原子能力比如“调用 HTTP 接口”“执行 SQL 查询”“读取文件内容”。工具本身没有“业务判断”只负责执行。知识库是静态信息的容器比如产品手册、历史数据、规范文档。它的特点是“内容固定、供查询”不产生行动。技能是“工具判断逻辑”的组合。它规定了在什么场景下、按什么顺序、调用哪些工具并对工具返回结果做二次加工。技能是面向任务的比如“查销售报表并生成分析摘要”里面可能要调用查询工具、格式化工具还可能查一下知识库里的指标口径。这个划分非常重要。如果只做工具层每个工具之间没有协同模型还是不知道什么时候用哪个如果只做知识库模型只能“查资料”不能“执行动作”。而agent-skills 正好补上了中间这个执行编排层技能定义任务边界、编排工具调用顺序、固定输出格式让智能体真正能完成一个完整的业务动作。2. 技能结构设计一个可复用的技能模块到底长什么样2.1 技能的核心字段拆解一个技能要能被大模型准确识别、被代码稳定执行字段设计是关键。我在 agent-skills 里沿用了社区里比较成熟的 schema 结构直接看示例name: sales_report_query description: 根据部门、时间范围和指标查询销售报表并生成精简摘要。适用于任何与销售额、订单量、目标达成率相关的询问。 enabled: true category: data_analysis version: 1.2.0 author: platform-team parameters: - name: start_date type: string required: true description: 查询起始日期格式 YYYY-MM-DD - name: end_date type: string required: true description: 查询结束日期格式 YYYY-MM-DD不能早于 start_date - name: department type: string required: false default: all description: 部门名称支持销售部、市场部、运营部默认查全部 - name: metrics type: array required: false default: [sales_amount, order_count] description: 需要返回的指标列表可选值见指标字典 trigger_examples: - 上个月销售部卖了多少 - 查一下Q3的订单量和销售额 - 最近7天哪个部门目标完成率最高 execution: type: workflow steps: - tool: validate_date_range args: [start_date, end_date] - tool: query_sales_report args: [start_date, end_date, department, metrics] - tool: format_summary args: [__last_result__, report_typebrief] output_schema: type: object properties: summary: { type: string } data: { type: array } generated_at: { type: string }字段看起来多每个都是必要的。name是技能的唯一标识建议用小写加下划线便于检索。description是最关键的一个字段它直接决定大模型能不能命中这个技能必须写清楚“什么场景下用”“解决什么问题”。trigger_examples是给大模型的“示例锚点”有这几个例子模型匹配的准确率会明显提升。参数定义部分同样重要。每个参数要有明确的类型、是否必填、取值范围。我在required之外还会加default和description这是血泪教训换来的没有默认值、描述含糊的参数模型经常传错。例如metrics如果不限定可选值模型就会自由发挥传一个[money]进来代码根本解析不了。2.2 为什么描述要“场景化”而不是“功能化”很多人在写技能描述时喜欢写成功能说明“执行销售报表查询”。我改用场景化描述之后命中率提升非常明显。比如功能化描述查询销售数据并返回结果场景化描述根据日期范围和部门查询销售额、订单量、目标完成率。当用户询问销售业绩、订单情况、目标达成进度时使用。两者的差异在于功能化描述描述的是“你是什么”场景化描述描述的是“什么时候用你”。大模型在做技能匹配时拿到的是用户问题它需要用问题去匹配技能描述。描述越贴近口语场景、包含越多的业务词汇匹配就越准确。这一点项目初期容易被忽略但实测下来收益最大强烈建议优先优化。2.3 关于版本管理和禁用开关技能不是一次性写完就结束的。业务口径变了、指标定义改了、接口参数升级了技能都要跟着改。我在每个技能里都加了version字段并且保留历史版本。调度层可以按版本灰度先让 10% 的流量走新版技能观察输出质量和报错率再逐步全量。enabled开关则用于紧急止血。比如某个数据源故障了直接把相关技能置为enabled: false智能体就不会再调度到它比改代码、发版快得多。3. 核心细节解析写技能时最容易翻车的几个环节3.1 参数校验与其让模型猜不如让代码拦技能执行的第一步不是调接口而是参数校验。项目中的validate_date_range就是一个典型例子。用户问“查一下去年销售情况”模型把start_date2024-01-01、end_date2024-12-31传进来看着没问题但用户说“查一下最近三个月”模型可能会把日期算错传成start_date2025-03-20、end_date2025-06-20结果查出来的数据根本对不上。所以在execution.steps里我永远把validate_*类工具放在第一位。校验工具负责做三件事格式检查是不是 YYYY-MM-DD、逻辑检查结束日期不早于开始日期、范围检查不能查未来数据。校验不通过直接返回错误信息给大模型让它重新理解用户意图并修正参数。这个设计把“模型可能出错”的风险控制在第一步避免把错误参数传给下游业务系统。同理其他技能里的参数也要做类似兜底。比如查报表时用户问“看一下华东大区”系统里跟这个名称对不上但能模糊匹配到“华东销售中心”校验层就做了同义词映射。这一步是常规文档里很少提到的但在真实场景中几乎每天都能遇到。3.2 输出格式固定让大模型的“口胡”失效技能执行完之后返回的结果也不是直接丢给用户。我会在output_schema里固定输出的结构比如 summary 是给用户的简要回答 data 是明细数据 generated_at 是生成时间。大模型拿到执行结果后进行“最后一步表述”但它只能基于结构化数据润色语言不能修改数值。这样才能有效防止模型“一本正经地编数据”。如果你允许模型在最终回答里自由发挥它极有可能因为上下文丢失或者用户追问自己脑补一个不存在的数字。有了固定结构模型只能把已有的data转成自然语言数字从哪里来、格式是什么都被锁死了。要理解这一点技能输出数据是“证据”模型只负责翻译证据不负责创造证据。3.3 技能描述里不要写“怎么做”这也是一开始常犯的错误。写技能描述时总想解释清楚内部逻辑比如“该技能会先校验日期再调用接口再格式化”。实际上description字段不是给人看的是给模型的匹配器看的。它不需要知道内部步骤只需要知道“什么场景用”。内部逻辑全部由execution.steps定义如果描述里写了内部实现反而会干扰匹配判断。我自己的标准是描述里只保留三类信息——任务对象查什么、业务场景什么时候用、关键限制不能做什么。其他一律不写。4. 实操过程从零实现一个可落地的技能模块以下用一个具体技能“查询招聘网站职位数据”为例走一遍完整实现链路。这个技能在真实项目里很典型因为它涉及外部接口调用、参数过滤、结果截断三个常见需求。4.1 第一步定义技能目录与基础文件每个技能在项目中有独立目录通常命名为skills/职位查询/包含SKILL.yaml描述文件和handler.py执行代码。目录级别的拆分让技能可以独立测试、独立部署也方便多个开发者并行维护。# SKILL.yaml name: job_position_query description: 根据关键词、城市和薪资范围查询在招职位。当用户提到找工作、查职位、了解某个城市的岗位机会时使用。 enabled: true category: recruitment parameters: - name: keyword type: string required: true description: 职位关键词如 Java、产品经理、数据分析 - name: city type: string required: false default: 全国 description: 城市名称如 北京、上海、杭州 - name: salary_min type: integer required: false description: 最小月薪单位千元低于该值的职位不返回 execution: steps: - tool: http_get args: url: https://api.example.com/jobs params: [keyword, city, salary_min] - tool: truncate_results args: [__last_result__, max_items10]4.2 第二步实现执行逻辑执行代码的职责很简单接收来自调度层解析好的参数调用外部 API对返回结果做清洗。核心部分如下import requests def run(params): keyword params.get(keyword) city params.get(city, 全国) salary_min params.get(salary_min) query_params { query: keyword, city: city, } if salary_min: query_params[salary_min] salary_min * 1000 resp requests.get(https://api.example.com/jobs, paramsquery_params, timeout10) resp.raise_for_status() data resp.json() jobs [item for item in data.get(jobs, []) if item[status] open] return {summary: f找到 {len(jobs)} 个在招职位, jobs: jobs[:10]}这里有一个细节在params传入之前调度层已经做过参数校验和类型转换。比如salary_min是整数型调度层保证它不可能是字符串执行层不需要再解析。代码看起来简单但它只做几件事没有业务判断利于维护。位置、行业、排序等复杂规则请放到校验层或额外步骤不要堆在这个函数里。4.3 第三步注册技能到技能库写好的技能需要注册到全局技能库注册过程其实是在构建技能的索引。运行时匹配器根据用户问题计算与每个技能description的语义相似度挑出分数最高的候选技能。注册数据除了 YAML 内容还要预生成一个快速检索用的向量索引。这一步直接关系到性能。技能库如果只有几十个技能每次实时把用户问题和所有描述过一遍模型也行但技能多了以后检索耗时会明显上升。我采用的做法是离线对每个技能的description和trigger_examples做向量化存入本地向量库查询时先用向量召回 Top-K再做精排。这样既能控制延迟又能保证命中率。4.4 第四步配置调用权限和审计日志技能不能无条件被调用。尤其是涉及外部数据、写操作、内部系统的技能必须有权限控制。在 agent-skills 中每个技能可以配置allowed_roles比如只有管理员角色才能触发“删除用户数据”这类高风险技能。这个配置放在技能调用链路的入口层由统一的调度器拦截校验。同时每个技能调用都会记录完整的调用日志传入参数、调用结果、耗时、由哪次会话触发。有一次线上反馈“某个技能总是返回慢”排查后发现是外部接口在特定时段超时因为日志里有完整的耗时分布很快就定位了问题。没有日志你根本没法复盘一次失败到底是模型选错了技能还是技能执行出了问题。5. 常见问题与排查技巧实录5.1 模型迟迟不选择技能反复“绕圈子”这是最常见的现象。用户问“帮我查一下北京的前端岗位”模型没有直接触发job_position_query而是先反问“请问您想查找哪方面的工作”或者在对话里打转。排查时先看是不是技能的description写得太窄。如果描述里只提了“查询职位”没提“北京”“前端”这些高频业务词模型匹配不到很正常。解决办法是把常见口语表达加进trigger_examples每加一条实际验证一条命中率会逐步提升。另一个原因是技能库里存在描述相似的技能匹配器给出了多个候选模型反而犹豫了。这种情况下要拉开技能描述之间的差异性让每个技能的业务定位更明确。5.2 参数传错、传漏模型把city传成了城市代码比如beijing而不是北京或者把必填的keyword漏掉。这种问题靠“提示模型认真一点”没用得靠调度层的解析器兜底。我在调度层维护了一套参数纠错规则值映射把 common 城市名、代码、别名统一归一化为系统标准名称类型纠正模型传了字符串的薪资范围自动转成整数缺失补偿必填参数缺失时返回带提示的错误信息引导模型补充而不是自己猜一个填上这样处理后表面上模型“犯的错”少了实际上错误被拦截在了执行层之外。5.3 上下文太长导致技能命中率下降对话轮次多了之后技能命中率会明显下降。原因是用户当前问题与历史上下文混合匹配器算相似度时被“噪声”干扰了。我试过把整个对话历史都塞给匹配器效果很差。解决办法是匹配技能时只用“当前用户问题”最多带上最近一轮的追问理解不要带历史对话。把上下文还给下游的对话生成层技能检索保持“独立且短小”。这也是 agent-skills 项目里一个重要的设计原则技能选择只对当前请求负责不背历史包袱。5.4 执行超时、外部接口不稳定外部接口不稳定是常客。为了不让技能调用拖垮整个对话我在调度层做了超时控制和降级策略。每个技能的默认超时时间设 5 秒超时后走降级分支重试一次还是失败就返回友好提示让模型转入人工兜底流程。这需要技能执行层与调度层约定一套统一错误码比如TIMEOUT、INVALID_PARAM、UNAUTHORIZED模型能识别这些错误码给出适当话术。5.5 常见问题速查表现象可能原因排查与解决技能从未被触发description 写得过于通用或狭窄重写 description扩充 trigger_examples加场景化词汇多个相似技能都能匹配描述彼此重叠边界不清明确技能边界突出各自的适用场景和限制条件参数总是缺或错参数描述不清或缺少枚举值给每个参数补充描述、默认值、可选值校验层做归一化返回结果与用户问题不符技能选对了但内部步骤逻辑有问题单测技能本身确认 execution.steps 的每一步输出是否符合预期调用频繁超时外部接口慢或依赖链路长缩短超时时间、加缓存、降级到兜底提示切换技能版本后行为异常新旧版本参数或口径不一致对比版本差异用灰度流量逐步切换保留回滚开关6. 从技能库到技能生态agent-skills 后续还能怎么扩展我目前最常用的扩展方向有三个技能自动生成、技能组合编排、技能评测回流。技能自动生成是指利用大模型分析历史对话中那些模型“搞不定”的请求自动生成候选技能模板。比如系统发现用户经常问“对比一下 A 和 B 两个职位的薪资”这类请求反复出现就自动生成一个compare_jobs技能草案。人只需要审核微调不用从零写。技能组合编排则更进一步。单个技能解决单一任务但实际业务往往是多个技能串联。比如“帮我筛选出合适候选人并发面试邀请”这个流程至少需要两个技能候选人筛选、创建面试单。我在这套体系里加入了技能编排层它支持定义简单的 DAG 流程指定步骤之间的依赖关系和数据传递。实现起来不算复杂但很依赖流程稳定、数据格式统一的基础。这值得在核心技能库稳定之后再考虑。评测回流是我最近在补的一块建立技能评测集定期用真实历史问题和对应的期望技能跑一遍看命中率、执行成功率有没有回退。技能升级后立刻跑评测避免“改一个技能炸三个场景”。对我个人来说这个评测集比文档管用多了能时刻提醒自己哪些改动破坏了稳定性。回到最开始的核心问题怎么让智能体真正“能干活”我的答案就是这套agent-skills 工程化思路——把模糊的需求翻译成确定的执行模块把大模型从“什么都想自己来”变成“只做判断不瞎执行”。智能体稳定性的关键从来不是提示词写得有多华丽而是你有没有给它一套足够清晰、边界明确、可验证的技能体系。如果你也在做类似的 Agent 项目不妨从梳理第一个技能开始试试慢慢就会发现整套系统的变化。