做了快两年的AI应用开发，我越来越觉得，真正决定一个智能体项目上限的，往往不是接入了多强的模型，而是“agent-skills”的设计质量。什么意思呢？同一个大模型，有人接出来的智能体能力极强，可以稳定完成任务；有人接出来的智能体就像个只会聊天的摆设，遇到真实业务就四处漏风。差别不在模型，而在你怎么给这个智能体定义技能、组织技能、让技能能被模型准确调用。
今天想跟你聊聊我在多个项目里反复打磨总结出来的智能体技能设计方法。无论你是刚开始接触智能体开发，还是已经被技能调用不稳定折磨了几天，这篇文章应该都能给你一些能直接落地的思路。我尽量不说废话，每一个结论背后都是踩过坑换来的。
1. 智能体技能是什么，为什么它决定应用下限
1.1 从“提示词优先”转向“技能优先”
早期做智能体，大家习惯把所有逻辑塞进一个System Prompt里，希望靠模型的“理解能力”来完成所有任务。试过的人都知道，这在Demo阶段很香，一上生产就崩：提示词越来越长、模型开始遗忘前面的要求、调用工具时参数传错、业务规则稍微一变就得重写一大段提示词。
后来我慢慢明白，智能体工程的本质不是“写好提示词”，而是“把能力封装成技能”。所谓agent-skills，就是一组可描述、可调用、可组合的能力单元，每个技能负责一个明确的子任务。比如“查询订单状态”是一个技能，“计算运费”是一个技能，“生成退货标签”也是一个技能。模型充当的是调度者，它需要知道当前任务应该触发哪个技能、传什么参数、技能返回之后怎么解读。
我做过一个某跨平台系统的智能客服模块，第一版把所有客服规则写在一个超长提示词里，结果线上问题频发：用户问个退货流程，模型就开始自由发挥，时对时错。后来我把“售前咨询”“订单查询”“物流跟踪”“售后规则解释”“转人工流程”拆成五个独立技能，准确率直接上了一个大台阶。让我真正坚定“技能优先”信念的，正是这次重构。
1.2 技能、提示词、工具和工作流的关系
很多人分不清工具、技能和工作流这几个概念，我简单理一下：
| 概念 | 含义 | 举例 | 粒度 |
|---|---|---|---|
| 提示词 | 指导模型行为的文本 | “你是客服助手，回答用户问题” | 最细 |
| 工具 | 模型可调用的单个函数接口 | 查询订单、查询物流 | 细 |
| 技能 | 面向某任务的完整能力封装，可包含多个工具调用和决策逻辑 | 处理退货：查订单→校验状态→算运费→生成标签 | 粗 |
| 工作流 | 多个技能的编排组合，按固定顺序执行 | 售后全流程管理 | 更粗 |
我的理解里，技能是中间最关键的一层。工具是“零件”，技能是“部件”，工作流是“整机”。如果只把工具丢给模型，模型往往不知道什么时候该用哪个、用完之后下一步干嘛。而技能把“什么时候触发、内部怎么调用工具、失败怎么办”都封装好了，模型要做的只是选择和执行。
1.3 技能的“可描述性”比“实现复杂度”更重要
在设计技能时最容易犯的错是：把技能接口设计得极其复杂，功能倒是强大了，但模型看不懂什么时候该调用它。
模型判断要不要用某个技能，依赖的是技能描述。描述得含糊，模型就会“乱点兵”。我自己总结了一个技能描述的模板：
- 技能名称：动词加名词，一看就懂
- 适用场景：明确什么情况下使用
- 限制条件：什么情况下不要使用
- 输入说明：需要哪些参数、参数含义和格式
- 返回说明：返回什么内容，有没有特别状态
我在团队里立了一条规矩：技能描述写得不清楚，一律不进主流程。因为模型就像个新来的实习生，你给它一份边界模糊的岗位说明，它就不可能做出稳定的判断。
2. 设计智能体技能的核心方法
2.1 把用户目标逐层拆解成可复用的技能
设计技能的第一步，是拆目标。我建议用逆向拆解法：先想清楚“用户最终想要什么结果”，再倒推出需要在什么环节介入。
比如用户想要“完成售后退款申请”，往前推，你会发现：
- 需要验证订单是否存在、是否在售后期内
- 需要检查商品状态是否符合退款条件
- 需要计算退款金额、扣除相应费用
- 需要发起退款流程并返回单据号
每一步都可能是一个独立技能。拆的时候把握一个尺度：每个技能只做一件事，并且这件事的输入输出能被清晰描述。你不要追求“一步到位”的超级技能，因为技能越复杂，模型调用时越容易传错参数、理解错意图。
2.2 给技能定义明确的输入输出契约
技能接口设计是agent-skills成败的分水岭。我见过太多项目失败在这上面：技能函数写得七扭八歪，参数名是缩写，返回值混着中英文和嵌套对象，模型根本没法正确解析。
一份好的技能接口应该做到以下几点：
- 参数命名要符合业务直觉，比如order_id、refund_reason，不要用a、b、c这种无意义缩写
- 每个参数必须有类型和取值范围说明，尤其是枚举值
- 返回值要结构稳定，必要时加一个status字段表示执行结果
- 错误信息要能直接给模型阅读，方便它做出下一步决策
举个例子，我常用下面这个JSON结构来描述技能：
skill_name: "查询物流轨迹" description: "根据订单号查询物流流转记录，适合用户在咨询快递到哪里时使用" parameters: order_id: type: string description: "平台内部订单号，形如SO20250326234" required: true responses: on_success: status: "success" tracking_list: - time: "2025-03-27 10:12:33" location: "某市分拨中心" message: "快件已到达【某市分拨中心】" on_failure: status: "not_found" message: "未找到该订单的物流信息，请检查订单号"这么设计之后，模型大多数时候能正确传参并解读结果。即使出了错，错误信息也在模型可理解的范围内，不至于卡死。
2.3 技能内部的工具编排与错误处理
技能与工具的区别在于：技能内部可以有编排逻辑。比如“申请售后”技能，内部可能要先调用“查订单”确认有资格，再调用“退款计算”得到金额，最后才调用“发起退款”。
在技能内部做编排时，我认为最需要注意的是异常处理。以前我不太在意，结果一次线上事故教会了我：技能一旦内部报错，不能直接把堆栈信息抛给模型。模型看到一堆系统报错会开始胡言乱语，最后给用户输出一段匪夷所思的答复。
我给技能内部定了几个处理原则：
- 外部接口超时，要重试一次，第二次仍失败则返回“服务繁忙”状态
- 参数校验不通过时，要返回具体哪个参数有问题，而不是只说“失败”
- 业务规则校验不通过时，要把原因返给模型，比如“订单已超过90天，不符合退货政策”
- 禁止把底层堆栈或数据库错误码原样返回给模型
这些处理看起来琐碎，但全部是稳定性的关键。你可以把技能想象成一个接线板，用户和模型只接触插孔，内部线路乱了不能在表面冒烟。
2.4 技能注册与动态选择机制
技能多了之后，下一个问题是：模型怎么从一百个技能里选出当前该用的那一个？
方案一，把所有技能的描述全放进上下文，让模型自己选。这个方案在技能数少于二三十个时勉强能用，技能一多，上下文就爆了，模型选择准确率也会明显下滑。
方案二，做两阶段检索。先把用户问题转成向量，用语义检索从技能库召回最相关的五到八个技能，再把这几个技能的描述交给模型决策。这个方案在实践中表现稳定，我强烈推荐。
方案三，对高频确定性场景，直接用规则路由命中，不走模型推理。比如用户输入里包含“物流”“到哪里了”之类关键词，直接触发物流查询技能，又快又省成本。
我一般用方案三做兜底，用方案二做主要通道，最后再留一个“未命中任何技能”的兜底分支。这样的分层设计让技能选择既快又准。
3. 从零搭建一套可用技能库的完整实操
3.1 领域调研与技能边界划分
开始写代码之前，我强烈建议先做一次“用户意图盘点”。把这套智能体要面对的所有用户问题翻出来，按意图分类，统计频率。
我做过一个企业内部的问答智能体，第一步不是写任何技能，而是把历史工单按“咨询类型”做了标签统计。最后发现高频意图其实就六类：账号登录、权限申请、网络问题、报销流程、设备领用、人员信息查询。低频长尾问题还有几十类，但我先只针对高频六类设计技能，其他让模型根据知识库自由回答。
这个动作给后续省了大量无用功。技能不是越多越好，覆盖了高频场景，你就能解决百分之九十的真实需求。低频场景做成通用知识问答就好，不必硬封装成技能。
3.2 技能接口定义与代码实现
我以某公司的“设备领用”需求为例，演示一套完整的技能实现流程。先做接口定义：
# skills/device_apply.py from pydantic import BaseModel, Field class DeviceApplyInput(BaseModel): device_name: str = Field(description="设备名称，如笔记本电脑、显示器") employee_id: str = Field(description="员工工号，如E10023") reason: str = Field(description="领用原因") class DeviceCheckInput(BaseModel): employee_id: str = Field(description="员工工号")然后实现两个技能：先检查员工是否有权限和额度，再提交领用申请。这里的关键是每个函数名和描述都要写清楚，因为模型依赖这些描述做决策。
def judge_device_application(employee_id: str) -> dict: """基于员工级别、部门库存和申请额度，判断领用申请是否批准。 适用于审批类场景，需要先调用本技能再做其他操作。""" # 业务判断逻辑 ... def submit_device_application(device_name: str, employee_id: str, reason: str) -> dict: """提交设备领用申请，生成申请单号。仅在审批结果为批准时调用。""" # 提交逻辑 ...这里有个细节：我在判断技能和提交技能之间设计了先后依赖。模型看到用户问“我想领台笔记本”，会先走judge，拿到允许结果后再调用submit。第二段技能描述里特意写了“仅在审批结果为批准时调用”，这能极大降低模型在流程未完成时乱提交的概率。
3.3 技能注册进Agent主流程
技能实现好后，要注册进智能体的技能路由里。我比较喜欢用注册表模式：
skills_registry = { "judge_device_application": { "function": judge_device_application, "description": "判断设备领用申请是否可批准", "input_model": DeviceCheckInput }, "submit_device_application": { "function": submit_device_application, "description": "提交设备领用申请", "input_model": DeviceApplyInput } }在接Agent时，我不会把两段技能描述全塞给系统提示词，而是等用户问题进来后，先用关键词加向量检索，从注册表里筛出相关技能，再把相关技能的描述注入本次会话的上下文。这样做的收益是：模型每次决策只面对少量候选技能，准确率更高。
3.4 测试与效果迭代方法
技能库搭完，接下来是持续测试。我自己的经验是：一定要在真实对话流里测，而不是单独测函数。单独测函数能保证逻辑正确，但测不出“模型是不是会主动调用它”。
我常用一个“意图-调用-结果”三层测试框架：
- 意图层：输入一百条真实用户问题，看模型是否选中了正确技能
- 调用层：看传参是否正确、是否调用了多余技能
- 结果层：看技能返回结果能不能被模型正确转述给用户
每轮测试完，统计准确率。低于预期的，去分析是描述问题、参数问题还是路由问题。然后调整，再跑。这个循环看着笨，但对稳定性的提升是最扎实的。
4. 常见故障排查与避坑经验
4.1 模型无视技能，直接凭知识回答
这种故障很常见：用户问“我的订单到哪了”，模型不调用物流查询技能，而是直接根据自己的训练知识编一个答案。原因通常是技能描述不清晰，或者技能描述里没有强调“未调用技能前不要猜测”。
我的排查顺序是：
- 先看技能描述里是否包含触发场景。如果没有，加上“当用户询问位置、物流、签收时间时，请优先使用该技能”
- 再看技能是否进了当前会话上下文。很可能被路由阶段过滤掉了，调低相似度阈值试试
- 最后看模型输出日志，确认模型是否真的看到了技能信息
真实项目中，最后发现的大多还是描述问题。把技能描述往“用户说人话版本”改，命中率立刻就上去了。
4.2 上下文膨胀导致技能失效
这是个隐性坑。技能数量一多，描述全塞进上下文，再加上用户对话历史，上下文窗口很快吃紧。模型思维链变短，选择技能时就开始出错。
我建议用以下几个手段：
- 路由阶段裁剪技能候选数量，最多给模型看六个技能描述
- 定期压缩对话历史，把早期的详细对话摘要化
- 技能描述统一精简，控制在两百字以内，保留触发场景和限制条件即可
有人跟我说技能描述写详细点不是更好吗，其实不然。描述过长会稀释关键信息，模型反而不容易抓到触发点。描述做到“精确但克制”，才是正确方向。
4.3 多个技能之间互相打架
当用户问题横跨多个技能边界时，模型会陷入混乱。比如用户问“我申请了显示器，顺便帮我看看能不能批下来”，这里涉及到“提交申请”和“查询审批进度”两个技能。模型可能只调其中一个，或者先后调用但参数错乱。
我的处理办法是增加一个组合技能。组合技能内部先查后续流程，再提交申请，把两步用编排逻辑串起来。对外只暴露一个技能入口，让模型不需要自己决定顺序。说白了就是把容易出错的编排逻辑从模型手里收回来，交给代码去保证。
4.4 快速排障速查表
| 现象 | 可能原因 | 应对措施 |
|---|---|---|
| 技能没被调用 | 描述缺乏触发场景 | 补全“当用户……时”说明 |
| 技能调用频繁失败 | 参数命名不符合直觉 | 改成业务通用命名并写清映射 |
| 模型跳过前置校验直接提交 | 依赖顺序未写清 | 在提交类技能描述中声明前置条件 |
| 上下文超长 | 技能候选过多、历史未压缩 | 缩减候选、增加摘要机制 |
| 模型输出与技能返回不一致 | 结果转述规则缺失 | 在提示词中强调“根据技能结果如实回复” |
| 错误信息不可读 | 底层异常直接上抛 | 在技能层统一捕获并格式化错误 |
这张表是我每次排查故障时的出发点，你完全可以把它当成基础清单来用。
5. 进入智能体工程后我学到的几件事
做agent-skills越久，我越觉得这活儿跟“教新人”很像。你不能只给新人一堆资料让他自己领悟，你得把任务拆清楚、边界画明白、异常情况演练熟，最后他才能独立扛事。给智能体设计技能也是这个道理。
第一件事是，技能库需要持续护理，不要想着一次成型。业务规则在变、用户问法在变、模型版本也在变。我把技能监控做成了常态工作，每周看一次调用日志，发现调用少或者经常失败的技能，立刻调整描述或逻辑。
第二件事是，从第一天起就要留日志。技能调用本身、传参内容、返回内容、模型决策结果，全都要记。没有日志，出问题就只能瞎猜。有了日志，很多问题一眼就能定位到是模型选错了、参数传错了还是业务逻辑错了。
第三件事是，先接真实流程再优化性能。有人喜欢先把技能库做得又大又全再上线，我个人不推荐。先挑两三个核心高频技能接入生产，把端到端跑通，再根据数据反馈慢慢扩充。这种小步快跑的路径，能让你快速发现设计层面的方向性问题，避免花大力气做出一堆没人调用的技能。
如果你现在正要设计一套智能体技能，我建议你从最小的场景开始：挑一个最高频的用户意图，把相关技能挖到足够深，至少让它稳定解决这一类问题。运行两个星期，把日志看明白，再复制这套方法论去扩展其他技能。这比一开始就规划一个大而全的技能广场要靠谱得多。技能工程是个手艺活，耐心打磨出来的东西，才经得住真实用户的考验。
