1. 为什么Agent需要独立的“技能层”1.1 从“临时调用”到“技能沉淀”做Agent开发的朋友应该都有过这种体验在原型阶段你给大模型写了一大堆工具函数tool/function每个函数用一句话描述用途然后让模型在对话过程中自行选择调用。demo跑得挺顺看起来智能体已经“会干活”了。但一旦把任务复杂度提上来——比如从“查天气”变成“帮我做本月复盘并生成下月计划”问题就全暴露了。模型开始频繁选错工具、参数传错、链式调用逻辑混乱甚至同一个操作在不同对话里表现忽好忽坏。你有的时候甚至怀疑这Agent到底是怎么“理解”手里的工具的这里其实藏着一个关键问题你没有给Agent一套“技能体系”而只是丢给它一把散装工具。工具Tool解决的是“我能调用什么”技能Skill解决的是“我该以什么方式、按什么顺序、为了什么目标去调用”。当任务从单步变成多步从固定流程变成开放探索后者才是决定Agent能否稳定干活的分水岭。这套能力沉淀下来就是标题里说的“agent-skills”。它不是某个具体框架的名字而是一种工程思路把Agent会做的事情从临时拼凑的工具调用升级为一套可定义、可复用、可评测、可迭代的技能资产。就像程序员不会把每个功能都写在main函数里而是要拆函数、抽模块、做抽象一样Agent的技能也需要分层、命名、定义输入输出才能被可靠地调度。1.2 技能层要解决的真实问题我见过不少团队在Agent项目跑通POC之后都会陷入同一个困境单个场景演示满意一旦横向扩展就变成“每个新场景都要重新写一套提示词pipeline”。这不是大模型能力不够而是你的Agent缺少“技能沉淀”这一层。具体来说技能层要解决这几类真实问题。第一消除行为随机性。同样的任务今天用这个步骤跑明天换了上下文就换一套步骤结果不可控。把标准做法固化成技能后只要触发条件一致Agent执行路径就大体一致可复现性明显提升。第二降低编排复杂度。多步任务本质是一个决策树先做什么、后做什么、什么情况下走分支、什么情况下需要找用户确认。如果这些逻辑全部写在系统提示词里提示词会膨胀到几千字模型反而抓不住重点。把编排逻辑拆成“技能路由”每个技能只负责一件事系统提示词就可以精简到“你是一个调度器负责选择技能并组织参数”。第三让能力可度量。埋点、日志、成功率、耗时这些只有落在“技能”这个粒度上才有意义。你说“我的Agent不错”那是哪里不错是任务分类分得准还是数据库查询写得好还是结果摘要生成得漂亮把能力拆成技能后每一项都可以单独评测、单独优化不用每次改一个细节就全量回归。我在实际项目中感受最深的一点是技能层设计得好不好决定了Agent是“看起来聪明”还是“真的稳定”。前者靠模型发挥后者靠工程兜底。而做工程的人都知道稳定性永远比惊喜更重要。2. 技能分层与定义规范2.1 三层技能体系原子技能、复合技能、决策策略既然技能要体系化第一步是分层。我这里推荐一个经过多个项目验证的三层结构分成原子技能Atomic Skill、复合技能Composite Skill和决策策略Policy。原子技能是最小的可执行能力单元对应一个明确的工具调用或API操作。比如“查询用户订单”“发送邮件通知”“计算两个日期之间的工作日天数”。原子技能的判断标准是输入输出都定义得足够清晰内部没有任何需要“思考”的分支。它就是工具箱里的一把螺丝刀单一用途拿到就能用。复合技能是把多个原子技能按特定顺序编排成的高阶能力。比如“生成周报”这个复合技能内部可能依次调用“汇总本周工作记录查询”“识别重点事项分析”“按模板生成周报生成”。复合技能的价值在于把“怎么做”固化下来调用者不需要关心内部过程只要告诉它目标它会自己安排步骤。决策策略是最高一层它不直接执行具体操作而是负责判断“当前该启用哪套复合技能”。一套好的决策策略通常包含触发条件什么意图、什么上下文下启动该技能、前置条件需要哪些输入参数、需要哪些上下文、终止条件什么情况下中断或转人工。在实现上决策策略可以是一段提示词约束也可以是一个小型的规则引擎甚至是微调过的分类模型。这三层的关系可以理解成写代码决策策略是入口的main函数负责根据用户意图路由复合技能是封装好的业务模块内部调用多个函数原子技能就是最底层的API函数。调用链清晰每一层可以独立维护、测试和替换。2.2 技能Schema的关键字段与设计意图把技能落到工程代码里核心是为每个技能定义一个结构化的Schema。我建议至少包含这些字段。字段含义设计意图name技能唯一标识全局唯一供路由层引用description技能能力描述供LLM语义匹配决定是否被选中input_schema入参定义声明每个参数的名称、类型、是否必填、含义说明output_schema出参定义声明返回结构便于下游技能消费skills依赖的子技能列表复合技能专用声明内部调用的原子/子技能steps执行步骤和顺序定义编排逻辑可选规则、循环、条件分支allowed_models可用模型列表部分技能对不同模型适配度不同timeout_ms超时阈值防止技能卡死拖垮整体流程retry_policy重试策略定义失败后重试次数、退避策略、降级方案这里面有两个容易被忽视但极重要的字段description和input_schema。description是给LLM看的不是给人看的。它要写清楚“这个技能在什么场景下用、能解决什么问题、有哪些限制”。很多团队用一句话糊弄比如“查询订单”模型遇到用户说“帮我看看我昨天买的东西到哪了”时根本不会联想到这个技能。更好的写法是“当用户需要查询已购买商品的物流状态、订单进度、发货信息时使用。支持按订单号或时间段查询。仅支持已下单用户。”描述越具体语义路由命中率越高。input_schema不仅要声明参数类型更要写清楚“参数的语义”。比如date_from这个参数不能只写“string类型”要写“查询起始日期格式YYYY-MM-DD默认为七天前”。这一步是给LLM做参数抽取slot filling用的。参数描述不清模型就猜一猜就容易传错。我习惯在写好Schema之后用几条真实用户query做一次“干跑”测试只输入query不看日志直接让模型输出它想调用的技能和参数。这一步能筛掉大部分描述含糊的问题。等描述改到能稳定命中正确技能再接入实际执行链路。这就是后面要讲到的“技能评测”的雏形。3. 从零搭建一个可复用的Agent技能库3.1 场景拆解与能力边界实操之前先选定一个场景。我用一个比较典型的“个人知识库助理Agent”举例这类Agent的核心任务是接收用户的问题从知识库中检索相关内容综合多个来源给出结构化回答并在必要时主动追问。为什么选这个场景因为知识库问答包含检索、重排、内容生成、澄清追问等多个环节技能拆分的层次感比较明显方便展示设计思路。而且这个场景对工程化能力要求不低——从RAG检索增强生成到多轮记忆再到评估每一步都值得仔细打磨。拿到场景后第一步不是急着写代码而是把用户可能提出的问题做一次穷举和归类。我一般用一个简单的四象限按“问题复杂度简单/复合”和“是否需要额外操作纯查询/需处理”两个维度交叉。纯查询型简单问题比如“我上周记的笔记里提到过XX吗”直接检索回答即可需要处理的复合问题比如“把知识库里关于MCP的资料整理成一份给新人的入门文档”涉及检索、筛选、归类、生成四个动作就要走复合技能编排。做完归类你自然会发现Agent的能力边界在哪、哪些过程可以标准化成技能、哪些环节必须保留给模型自由发挥。这里有个重要的原则能标准化的尽量标准化不能标准化的才交给模型临场发挥。标准化带来稳定性和可测性临场发挥只留给真正需要“理解力”的部分比如意图识别、内容重写。3.2 第一版技能目录按照上面三层结构我给这个知识库助理设计了一份技能目录先不要追求大而全第一版跑通闭环才是关键。原子技能层retrieve_from_kb从向量库检索相关内容入参query、top_k、过滤条件rerank_by_model对检索结果做精排入参query、候选doc列表fetch_full_doc按doc_id获取文档完整内容summarize_text对文本做摘要入参content、max_wordsask_clarification向用户提问澄清入参question、options复合技能层answer_simple_query简单问答retrieve rerank 组织回答answer_compound_query复合问答多轮检索 交叉对比 综合回答create_summary_doc生成专题文档检索 - 筛选 - 按结构生成决策策略入口判断用户query是简单查询还是复合任务检索失败策略检索结果相关性低于阈值时先ask_clarification补充信息而不是硬答这份目录的每个技能都要按第2节的Schema格式写完整定义。我实际写的时候会把YAML文件和加载代码放在同一个技能目录下每个子目录一个技能结构大概是skills/ ├── answer_simple_query/ │ ├── skill.yaml │ └── execute.py ├── retrieve_from_kb/ │ ├── skill.yaml │ └── execute.py └── ...skill.yaml存放Schema定义execute.py存放可执行逻辑。这样每个技能都自带完整说明新同学接手不用猜也能直接在技能库里独立开发调试。3.3 路由与编排的核心判断逻辑有了技能目录下一步是让Agent知道“什么时候该调用哪个技能”。这一层在代码里通常体现为一个路由函数但它的核心判断逻辑要靠一套“决策提示词”驱动。我常用的做法是给决策层单独写一套精炼的提示词系统提示词只做框架约束技能判断交给具体的路由模块。路由提示词的关键结构大概是这样的你是Agent的技能调度器。根据用户意图从以下技能中选择合适的技能执行并确保输出合法JSON。 可用技能 - answer_simple_query适用于用户问题指向明确、只需要一次知识库检索即可回答的场景 - answer_compound_query适用于用户问题涉及多个主题、需要多轮检索与交叉对比的场景 - create_summary_doc适用于用户要求根据知识库内容形成一份结构化文档的场景 输出格式 {skill: 技能名, params: {...}}这里有个细节技能描述的顺序也会影响选择命中率。实践来看把高频技能放在前面低频和兜底技能放在后面命中表现会更好。没有科学依据纯经验但值得一试。路由拿到模型输出的JSON后要严格校验参数再执行技能。参数校验这一步很多人偷懒觉得模型不会传错但一旦传错错误信息一团乱麻排查成本极高。我在项目里都是先用JSON Schema对自己的input_schema做一遍校验不通过就直接进入澄清流程让模型根据校验错误向用户补充提问。这不仅提高了稳定性还天然实现了“遇到歧义主动追问”的产品体验。4. 技能上线后常见的5类问题与排查4.1 技能描述互相打架第一个常见问题是技能之间的description语义重叠。比如你既有一个“查询订单”技能又有一个“查询物流”技能用户说“我的东西到哪了”模型在两个技能之间反复横跳今天选这个明天选那个。解决思路有两个一是做描述互斥明确边界二是把重叠的语义收敛到更高的技能层。比如“查询订单”和“查询物流”合并不了的情况下可以增加一个“查询订单全流程信息”的复合技能把两个原子技能收编进去路由层只需要面对一个入口。实战经验是路由层需要“看到”的技能数量越少越好理想情况是每个意图只对应一个入口技能。4.2 Agent死活不调用某个技能另一个高频问题某个技能明明定义好了模型却总是不选它宁可给你编一个答案。排查方向按顺序走先看description是否具体、是否覆盖了用户的常见问法再看是否有其他技能描述“抢了”它的语义最后看这个技能的“使用门槛”如果它的入参要求特别多模型觉得太麻烦也可能选择绕过。还有一个容易踩的坑是参数filled的引导不到位。比如技能需要date_from但用户只说了“最近”模型不知道怎么补默认值就干脆不调用了。我现在的做法是在input_schema里把每个可选参数的“默认值推导规则”写清楚比如“date_from未指定时默认为今天往前推7天”。“让模型有规可循”这句话放在技能设计里永远适用。4.3 技能内部报错难排查技能执行出错传统的print日志方式在Agent这种异步、多步、上下文交织的场景里很容易看出不关联。我习惯在每次技能调用时打印一份结构化日志时间、技能名、入参快照脱敏、耗时、出参摘要、错误信息、调用链ID。调用链ID尤其重要它能把一次用户请求涉及的所有技能串起来排查时顺着ID把所有节点日志捞出来一眼就能定位问题。另外技能执行一定要设超时和重试。我这里给一个可参考的经验值原子技能超时3000ms复合技能超时8000ms两个数值根据业务调整但必须存在。而且重试策略不能盲目扩大最多重试一次避免把下游服务打爆。4.4 评测与回归技能库迭代一段时间后最容易出现“改好一个技能搞崩另一个技能”的回归问题。所以每个技能都必须有一组“评测样例集”。样例集不用很大但要有代表性每个技能准备15-30条真实用户query标注期望调用的技能名和期望参数。每次改动技能描述或编排逻辑都跑一遍这套样例看命中率变化。我自己的执行标准是核心技能命中率低于90%不能合并代码整体命中率低于85%就需要回滚检查。额外提醒一句评测样例要随真实用户反馈持续更新。那些模型答错了、用户反复追问的case都要及时沉淀进样例集这一条比任何高级评测框架都管用。4.5 版本管理与多Agent共享技能库做大以后会变成多个Agent共用的资产。这个时候版本管理就要跟上。我一般用git按技能目录管理每个技能的skill.yaml和execute.py独立提交Version字段递增在Agent的配置里指定“用哪个技能版本”而不是默认拉最新。理由是线上稳定优先。技能升级有风险必须经过评测、灰度才能全量放开。我自己是先在评测环境跑一遍样例集再挑一个低流量Agent灰度观察一两周确认没有异常才把默认版本切过去。这个过程看着繁琐但它能帮你避免“半夜被线上问题叫起来”的尴尬。5. 一点个人经验做技能工程这段时间我最深的一个体会是Agent项目的复杂度不在于模型而在于工程。一个使用Claude或GPT这类通用模型实现的Agent能力上限通常不会差太多真正拉开差距的是技能定义、路由设计、评测机制、日志体系这些工程细节。我踩过最痛的一个坑是一开始把大量逻辑写进系统提示词希望让模型“变得更聪明”结果提示词越来越长模型行为越来越飘。后来把能标准化的步骤全部拆成了技能提示词精简到只描述角色和约束系统反而稳定很多。这件事让我彻底理解了那句话Agent的智能一部分来自模型另一部分来自严谨的技能构架。最后再分享一个小技巧技能库和技能描述可以阶段性拿给团队里非技术的同学看请他们用“第一直觉”判断这个技能会被哪些问题触发。如果他们猜不到说明描述还不够自然。我试过几次每次都能捞出一些“只有作者本人看得懂”的僵硬描述。Agent技能工程是一个会持续迭代的方向后续可以继续做技能自动组合、技能效果评估数据联动、跨Agent技能共享协议等等。先把基本功练扎实后面的事情会顺很多。