做Agent开发这一年多我最大的感受是让大模型开口说话已经不难了难的是让它“知道该干什么、知道该怎么干、干完知道自己干得对不对”。最开始我写客服Agent模型回复倒是文从字顺但该调订单接口的时候不调不该调的时候瞎调同一个问题能绕三圈。后来我把自己踩过的坑整理了一遍才发现问题根本不在模型而在“技能”——也就是agent-skills。这个标题听起来像是一个GitHub仓库名实际上它代表了一整套思路把Agent能做的事拆成一个个独立、可描述、可装载、可评测的技能单元再按需组合。写这篇东西是想把我在agent-skills设计上的完整思考、代码级的落地方式以及半年多实战中踩出来的坑一次性讲清楚。不管你是刚入门想做第一个Agent还是已经在生产环境被工具调用折磨过几轮这篇文章应该都能给你一些可以马上抄作业的东西。1. agent-skills到底在解决什么问题为什么你的Agent总在“答非所问”先从一个现象说起。很多人第一次写完Agent demo之后都会觉得“这不就是个套壳的API调用吗把Prompt写清楚把工具接上去完事了。”但一旦把任务复杂度提上去问题立刻成堆出现。模型该用工具的时候不去用宁可自己编一个答案也不查数据库工具用错了还嘴硬任务做到一半突然忘了前面在干什么。这些现象表面上是模型能力问题实际上是技能设计问题。1.1 从“会说话”到“会干活”之间隔着一整层技能设计一个只会对话的模型和一个能独立完成任务的Agent中间差的不是模型参数而是一整套“技能的显式化表达”。举个例子你可以在Prompt里写“当用户询问订单状态时调用get_order_status接口”这算是最原始的技能定义了。但一旦你的Agent需要处理退换货、物流跟踪、客服转接、工单创建、优惠计算等几十个能力时全写在Prompt里模型很快就“忘”了后面几条或者在触发条件重叠时选错工具。我在项目里把agent-skills定义成一组带有明确语义边界的可执行能力单元每个技能都有自己的名称、触发条件、输入输出结构和失败处理策略。这跟纯粹写死Prompt有本质区别Prompt是在和模型说话技能定义是在给Agent搭建一套可寻址、可检索、可组合的行为库。1.2 没有技能体系的Agent项目为什么会快速失控我见过太多项目在早期快速上线三个月后彻底跑不动。本质原因是技能逻辑散落得到处都是。有的写在system prompt里有的写在业务代码里还有的直接让模型自己猜。结果就是——产品经理改了一个需求你根本不知道要去改Prompt还是改服务端逻辑线上模型行为异常你无法定位是哪个技能出了问题新同事接手项目光读配置就看了一周。agent-skills的价值在于它给了Agent开发一个工程化的抓手。每个技能有独立的名字有清晰的参数契约有对应的测试用例。技能之间可以组合可以单独升级可以按角色分组。这套东西放到工程语境下本质上是把“模型行为”当成可管理的代码资产来处理而不是一盘散沙。2. 技能集合的四层结构一张可落地的Agent技能地图整个依赖链可以概括为底层依赖与能力组件、工具与能力接口、以及执行与操作系统三层。这种分层设计在当时还只是为了让代码少重复后来我越做越觉得agent-skills的结构本质上也可以按这个思路分层。我现在更习惯把技能分成四层基础能力、感知获取、动作执行、反思进化。每一层解决不同性质的问题。2.1 基础能力层任务拆解、上下文与行为边界基础层是Agent的“立身之本”对应的是不依赖外部工具也能完成的内部推理技能。最重要的三项是任务拆解、上下文管理、行为边界控制。任务拆解不是简单把需求列表化我通常把拆解的产物定义为“可执行原子任务序列”每个原子任务都对应一个后续技能或终止动作。上下文管理技能负责控制注意力。比如长会话中模型容易被早期信息干扰就需要有意识地压缩、归档、提取关键记忆。行为边界技能决定“什么坚决不做”例如明确拒绝超出权限范围的操作请求。这些技能在实现层面常常体现为System Prompt里的规则段落但它们和普通Prompt的区别是它经过了结构化设计每条规则都有明确的触发逻辑和冲突优先级。2.2 感知获取层检索、读取与信息判定第二层解决的是“Agent怎么获取自己不知道的信息”。这是Agent从“一个会聊天的模型”变成“一个能干活的系统”的关键跃迁。感知层的技能包括关键词检索、语义检索、网页读取、数据库查询、文件解析、API状态探测等。这一层最容易犯的错误是把所有信息源全部暴露给模型。正确的做法是为每个信息源设计标准的描述接口这个技能返回什么样的数据格式、更新频率是多少、失败时的兜底策略是什么。我习惯给感知类技能加一个“信息置信度评估”数据源返回结果后会附带来源和时效性标签模型可以根据这个标签决定回答时的把控程度。2.3 动作执行层工具调用、API对接与代码执行第三层是把决策转化为真实世界影响的部分。动作执行技能包括但不限于发送HTTP请求、写数据库、操作文件系统、执行代码沙箱、发送邮件、调用第三方服务。这一层的核心问题不是“能不能调”而是“怎么安全地调怎么正确地调”。我在动作技能里强制要求三件事输入校验、幂等设计、失败回滚。举个例子一个“创建工单”的技能如果模型误传了重复参数能不能自动去重如果下游服务超时会不会导致重复创建这些都是靠技能定义可以提前规避的。动作技能还需要明确“影响范围”。发一封邮件给客户的技能和发一封内部通知的技能权限等级必须不同Agent不能跨级调用。2.4 反思进化层自我纠错与策略沉淀第四层常常被新手忽略但它决定了Agent的上限。反思进化层的技能包括结果校验、错误识别、自我修正、策略沉淀。结果校验技能要求Agent在执行完一个动作后主动验证结果与预期是否一致。比如发送邮件后Agent应该检查send status而不是直接对用户说“应该发成功了”。错误识别技能让Agent能区分“工具本身报错”和“参数传错了”不同的错误走不同的修复路径。策略沉淀技能则负责把一次成功或者失败的经验转成可复用的行为规则写回技能库里。这个技能组合的价值是Agent会在持续运行过程中变得越来越贴合业务而不是永远靠模型随机发挥。技能层级核心问题典型技能实现载体基础能力层Agent怎么想问题拆解、规划、上下文管理、行为边界System Prompt / 规则引擎感知获取层Agent怎么获取信息检索、读取、查询、解析、状态探测RAG工具 / 查询服务动作执行层Agent怎么影响世界调用API、写库、发消息、执行代码Function / MCP Tools反思进化层Agent怎么变得更好校验、纠错、策略沉淀、自我修正回调逻辑 / 反思提示3. 把技能真正装进Agent三种装载方式与选型取舍技能定义好了下一步就是怎么让它进入Agent的运行循环。当前主流实现方式大致有三种直接写进System Prompt、通过Function Calling/Skill Schema结构化注册、以及运行时技能检索。这三种方式不是非此即彼的关系实际项目里往往是混用的但你要弄清楚每种方式的边界和代价才能做出合理选型。3.1 System Prompt直灌小技能快上线但会快速撑爆上下文最原始也最直接的方式把所有技能说明以文本形式写在System Prompt里。优点不用多说——不用改代码结构迭代快大模型对Prompt的直接指令遵从度最高。对于技能数量少于10个、技能逻辑相对固定的场景我仍然推荐这种简单方案。但它有两个硬伤一是上下文占用会快速膨胀一个包含详细参数说明和示例的技能描述动辄几百token30个技能塞进去光技能描述可能就占了几千token二是技能多了之后模型对技能的“注意力”会分散后面声明的东西经常被忽略。我遇到过一个真实案例技能列表超过25个后模型开始频繁混淆两个功能相似的技能并且不是偶发是系统性倾向。所以当技能数量上了两位数你就要考虑下一种方式了。3.2 结构化注册Function Calling / MCP让模型“看得见”可调用项第二种方式是使用大模型的原生Function Calling机制或者遵循MCP协议进行结构化注册。把技能定义成一个带名称、描述、参数JSON Schema的条目模型在决策时会自行判断是否调用以及用什么样的参数调用。形式类似这样{ name: query_order_status, description: 根据订单号查询订单的实时状态。仅当用户询问订单进度、物流状态时使用。, parameters: { type: object, properties: { order_id: { type: string, description: 订单号格式为ORD开头加12位数字 } }, required: [order_id] } }这里的知识点在于不仅仅是把API改为Function形式就够了。每个字段都有讲究。name要语义清晰description要写明触发边界什么时候用、什么时候不用parameters里的description要具体到业务含义和格式要求。这三个地方任何一个偷懒模型就会开始给你乱调。MCP作为标准化协议的价值在于它让技能可以被标准化登记工具与服务可以走统一的发现机制尤其适合跨团队协作、技能贡献方与Agent主体分离的情景。3.3 运行时技能检索技能多了之后的必然选择当技能数量超过50个甚至上百个时无论你把它写进Prompt还是全部注册成Function都会遇到上下文和失效边界的问题。这时候更合理的做法是运行时检索Agent先根据当前任务动态检索出最相关的技能子集再把子集装载到上下文中。本质上做成了一层技能检索Rerank的中间层而不是把技能库全量暴露给模型。我在项目里对这套机制的感受是技能检索取代了“全量提示”模型的调用准确率反而提升了也更省Token。它的代价是引入了额外的工程组件与延迟开销但如果你的技能库已经大到一定程度这笔投入完全值得。选型上我建议按技能数量做一个分流少于10个用Prompt直灌10到30个用结构化注册超过30个上检索机制。具体数字因业务和模型而异但这个趋势是通用的。4. 半年实战踩过的六个坑以及对应的解法理论部分讲得再多最后还是要在真实项目里被毒打一遍。以下这些坑每一个都是我花过时间踩进去又爬出来的写出来帮你们省掉这趟路。4.1 技能描述是写给模型看的不是写给同事看的最开始我写技能描述的时候用的是给程序员看的语言——干净、简短、充满术语。比如“获取用户信息”这个技能我当时写的描述是“根据user_id获取用户资料返回DTO对象”。结果模型经常在不需要的时候调用或者在用户已经给了昵称的情况下非要去拿user_id。后来我把描述改成“当用户询问自己的账户信息、会员等级、积分余额时使用此技能获取用户资料昵称不能直接作为参数需先通过检索技能找到user_id”。准确率一下就上来了。这个教训的本质是技能描述最大的读者是模型不是人。它需要包含触发场景、反例、参数获取前置条件这些对程序员来说是“废话”的信息恰恰是模型做决策最需要的信号。我建议每个技能描述都当成“给新员工看的操作手册”来写而不是当API文档来写。4.2 技能之间的边界模糊模型疯狂误调用第二个坑和第一个相关但更隐蔽。当项目里同时有“查询订单状态”和“查询物流轨迹”两个技能时模型很容易在两者之间选错。因为两个技能的触发描述有高度重叠。当时我统计了一下线上40%的误调用都发生在相似技能之间。解法有两层一是物理隔离把确实高度相似的技能合并成一个内部通过参数路由二是语义隔离在描述里写清楚反例边界。比如“查询订单状态”的描述里加上“注意本技能只返回订单的整体状态如果用户需要详细的物流节点信息请使用另一个技能”。语言模型的调用决策非常依赖这种互斥性约束你写得越明确它选错的概率越低。4.3 权限控制跟不上Agent把测试环境搅黄了有一次线上事故让我印象深刻。模型在测试对话中意外触发了“发送批量通知”这个技能而且因为它有“自动重试”的反思逻辑连发了好几轮把测试环境的通知渠道打好几千条。这个事故的本质不是模型“坏”而是技能缺少权限模型。后来我建立了三级权限机制只读类技能直接放行可写类技能需要业务侧二次确认批量和高危类技能不仅需要确认还要走管理员鉴权。另外所有动作执行类技能统一接入操作审计日志谁在什么时间调了什么工具、用了什么参数、结果如何全部留痕。这一步很痛苦但它是Agent能够进入生产环境的底线要求。4.4 技能改一版旧行为立刻失效版本管理的缺失技能不是静态配置它会随着业务需求不断迭代。但技能一变Agent的行为就可能整体漂移。踩过几次坑之后我养成了给技能做版本管理的习惯。每个技能定义都带上apiVersion字段并且技能仓库本身用独立的分支管理。发布流程上新技能版本先在小流量环境中灰度用离线数据回放验证调用准确率不下降后再全量发布。这里我特别想强调一件事技能版本升级的场景和你平时做模型Prompt调优是一样的一定需要评测基线作为门槛后面我会专门讲评测怎么做。没有版本管理你昨天线上还好好的Agent可能因为你早上改了一个技能描述行为就整个变形了而你根本不知道改的是什么造成的。4.5 上下文装载上限技能列得太多反而不会用这是个反直觉的现象你把所有技能都告诉模型模型反而什么都不会用。我做过一次压力测试当注册给模型的技能从十五个增加到三十个时技能调用覆盖面在增加但单技能的调用准确率在下降。那种感觉就像给了人一本五百页的产品说明书遇到具体问题的时候反而不知道该翻哪一页。解决方案就是我前面提到的技能检索。我们提前按业务场景把技能分组运行时根据用户意图快速锁定一到三个技能组只往Prompt上下文里塞这些相关的技能定义。这个策略上线之后调用准确率有了明显的回升Token消耗也降下来了。现在我把上下文压缩当成一个长期优化方向毕竟技能越多这个矛盾就越尖锐。4.6 没有评测基线改技能全靠“感觉还行”最后一个坑也是我感触最深的一个技能体系建设得像模像样之后最大的短板变成了评测。没有评测基线你改一个技能根本不知道是变好了还是变坏了。我后来搭了一套离线评测流程准备一批带标准答案的“技能调度用例”每个用例包含用户输入、期望调用的技能、期望的参数值。任何技能变动先跑一遍这套用例集对比调度准确率和参数准确率。再准备一批端到端评测用例模拟真实对话场景看任务的最终完成率。这套基线看起来不难但它让Agent开发从“拍脑袋调参数”变成了“数据驱动迭代”这是整个项目工程化水平提升的关键一步。5. 从零搭一套自己的agent-skills一条可以直接照抄的落地路线前面四章把原理、结构、装载方式、踩坑经验都说了这一章给一个能直接照着做的落地路线。对于想在自己项目里引入、或者正在做智能体平台建设的团队来说这个步骤顺序是经过验证的照着走能少走弯路。5.1 第一步用一个最小场景跑通技能闭环不要一开始就追求大而全的技能体系。我建议先挑一个真实业务场景比如“查快递进度”或者“帮用户做退款登记”把这个场景完整跑通。完整跑通的定义是用户在对话中表达需求Agent正确识别需求并调用对应技能技能执行成功后返回结果Agent把结果组织成自然语言回复。跑通这一步的目的是让你亲眼看到模型做技能决策的决策链路体会技能描述该怎么写、参数该怎么定义、错误处理该怎么兜底。最快的方式是直接手工做一次推理链路你把用户输入喂给模型看它选的是不是预期技能参数对不对再反过来调整描述。这个循环你亲手跑十遍比看任何理论都管用。5.2 第二步建立技能描述模板与开发规范跑通一个技能之后马上要把第二个技能、第三个技能做出来。做之前先定规范可以极大避免返工。我现在每个技能文档都固定包含六个部分技能名称与别名、触发场景与边界含正例和反例、输入参数说明、输出结果结构、失败处理策略、使用限制与权限等级。一个标准的技能描述通常长这样## 技能名称 query_member_points ## 触发场景与边界 - 触发用户询问积分余额、积分变动明细 - 不触发纯聊积分活动规则不查询个人账户积分时不触发 - 反例用户问“积分怎么攒”不要调用应该使用积分攻略检索技能 ## 输入参数 - member_id: 用户会员ID字符串 - period: 查询时间范围可选默认近30天格式为YYYY-MM-DD至YYYY-MM-DD ## 输出结果 - total_points: 当前总积分 - records: 积分变动明细列表 - expired_soon: 是否即将过期 ## 失败处理 - 9001错误会员ID不存在反馈用户“请先登录” - 9002错误查询服务超时重试一次仍失败则返回“稍后再试” ## 使用限制 - 权限等级只读 - 频控单用户每10秒最多一次这套模板的价值在于技能的写作者和评测者有了统一的沟通语言新技能上线前把这份文档提交评审比直接在代码里加个函数严谨得多。5.3 第三步按角色拆分技能集团队协作的工程化分工技能数量多起来以后我强烈建议按角色分集。比如一个电商平台的Agent可以有“客服助手”“运营助手”“售后专员”三套技能集。每套技能集独立命名、独立管理、独立评测。这样做最大的好处是隔离客服助手的技能变更不会影响运营助手的线上行为。同时不同角色之间可以共享底层基础技能权限控制也天然地分离开来。落到工程上可以做成每个角色对应一个独立的技能配置文件或目录运行时通过角色ID加载对应技能子集。再上层可以做一套“插件化”设计任何内部团队都可以把自己开发的技能作为插件注册进来通过权限审批后进入对应角色。这一步做完agent-skills就从一个个人经验变成了一套可扩展的团队基础设施了。5.4 从OpenAI到开源本地模型的迁移视角技能层是隔离层最后说一个很多人忽略的点技能设计本身是与底层模型无关的。一套设计良好的skills体系天然具备模型可迁移性。我在项目里做过一次迁移测试同一套技能定义、同一套检索逻辑从商业大模型切换到开源本地模型业务逻辑几乎没有改动只是Prompt风格做了微调。因为你所有的技能描述都是标准化的自然语言文档模型只要具备基础的能力就能读懂并执行。这也是我一直坚持技能层独立的原因——它是连接业务与模型的隔离层。模型的迭代不应当推倒技能的重来而技能的优化也不该绑定在某一个模型厂商身上。这个思路放到技术选型上能帮你省掉很多日后替换模型的痛苦。如果你正打算把技能体系引入你的Agent项目我的建议是从一个最小闭环开始把你手上最痛苦的那个场景先跑通然后逐步扩展。这个方向的东西远没有到天花板我也还在持续踩坑但至少到目前为止它是让Agent从不稳定的小玩具走向可靠生产系统最扎实的一条路。