做Agent项目有一段时间了我最大的体会是真正决定一个智能体上限的往往不是藏在模型权重里的“智力”而是它到底会多少“手艺”。光会聊天的大模型就像一位满腹经纶但从没下过厨房的理论大师你让他做一桌菜他能把步骤说得头头是道却连火都不知道怎么开。于是就有了“agent-skills”这种思路——把智能体需要的能力封装成一个一个可以被发现、被调用、被组合的技能包让模型从“知道”变成“做到”。这篇文章想跟你聊的就是一套我在实际项目中反复打磨过的智能体技能体系怎么设计技能的结构、怎么把技能注册进智能体、怎么让模型在合适的时机选对技能、怎么把多个技能串起来干活以及最后怎么排查那些“模型明明调了技能却答错”的经典问题。如果你正在做 AI 助手、自动化流程、企业知识库问答这类应用或者单纯想知道怎么让大模型真正“动起手来”这篇内容应该能给你一份可以直接抄作业的参考。1. 为什么需要Agent Skills从“能聊天”到“能干活”1.1 模型的“想”和“做”之间有一条鸿沟大语言模型本质上是一个文本生成模型。它接受的输入是文字输出的也是文字。这意味着它天然擅长总结、翻译、推理、写作但遇到需要访问实时数据、操作外部系统、执行精确计算的任务时就会暴露出明显的短板。你问它“帮我查一下这个订单到哪儿了”它无法直接连接物流系统你让它“把这份表格按照规则拆分成本地文件”它也没有原生能力去操作磁盘。这正是智能体技能存在的意义。所谓 Agent Skills就是给模型补齐“行动能力”的一套机制。它把一个个具体的业务能力——查天气、算工时、搜文档、发通知、解析文件——封装成模型可以理解和调用的模块。模型不需要知道技能内部怎么实现只需要知道“什么时候该用哪个技能、需要传什么参数”剩下的脏活累活交给技能执行器去完成。我在一开始做这类项目时犯过一个典型错误试图让大模型直接输出操作指令然后由外部系统解析执行。结果指令格式五花八门稍微复杂一点的场景就崩。后来换成技能封装的方式把“动作”收敛成标准接口模型只做选择与传参系统负责执行整个稳定性和可维护性立刻上了一个台阶。1.2 技能不是普通函数也不是固定工作流很多人会问Agent技能不就是函数调用吗把API封装成函数让模型调用不就行了这是最容易踩的坑。普通函数与Agent技能之间关键差异在于“模型是否真的理解该在什么场景下使用它”。普通函数的视角是为开发者服务的调用关系在代码层面是确定的。而Agent技能是为模型服务的模型面对的是开放的自然语言它需要根据用户的一句话判断调用哪个技能、怎么填参数。所以技能必须包含足够丰富的“语义上下文”它适用什么任务、不适用什么任务、参数分别代表什么含义、最好再附上几个典型的用户提问示例。技能与工作流也不太一样。工作流是预先编排好的一串固定步骤适合“流程确定、很少变化”的场景比如每天定时抽取数据、清洗、入库。而技能更像一块块独立的乐高积木可以灵活组合。同样一个“文件解析”技能既能服务于“总结PDF”的任务也能服务于“批量提取合同字段”的任务。技能不预设调用顺序谁需要谁就拿这种松耦合在需求频繁变化的产品里会更从容。可以简单用一个表格区分它们能力形态面向对象灵活性适合场景典型问题普通函数/API开发者低调用关系固定系统内部模块协作模型不知道怎么用语义断层Agent Skill模型开发者高可动态选择组合开放对话、任务自动化需要额外设计描述和路由工作流/Flow运维/产品低流程固定定时、批处理、标准流程需求一变就要重新编排如果你只想做一个离线批处理工具那直接用工作流就够了但如果你做的是需要面对五花八门用户指令的智能助手技能体系几乎是绕不开的选择。2. 技能体系的核心设计从定义到运行2.1 一个技能就是一个自包含的“工作包”先看一个标准技能应该长什么样。我习惯把每个技能拆成两部分一部分是给模型看的“说明书”也就是元信息另一部分是给程序执行的“操作手册”也就是执行器。元信息里最重要的是描述description。这段描述不是给你自己看的是给模型看的。它决定了模型在什么情况下会想起这个技能。我见过很多新手把描述写得特别简陋比如“计算工时”。模型遇到“这个任务大概要多久”时根本不知道“计算工时”跟这个问题有关系于是干脆不调用技能或者乱调一个。准确的描述应该类似于“估算软件开发任务的工时输入任务清单、团队人数、复杂度评分输出三点估算结果。适用于项目排期、人力评估等场景。”这种描述能把触发边界说清楚。参数定义也建议用 JSON Schema 规范而不是随手写个字典。因为模型在生成参数时需要一个结构化的约束。哪个字段必填、哪个字段可选、允许的取值范围是什么都要写明。特别要注意参数类型如果你把“任务清单”定义成字符串模型很可能传一个逗号分隔的文本如果你定义成数组模型就会按数组结构生成。类型边界直接影响下游代码能不能直接消费。执行器部分是真正的业务逻辑。它可以是一段 Python 函数、一个 HTTP 调用、甚至是一段提示词加本地脚本的组合。执行器内部不应该再去猜模型意图它只负责“输入参数进计算结果出”。我总结了一套技能的字段清单供参考name技能唯一标识代码内部使用建议小写加下划线。description面向模型的自然语言描述必须包含适用场景和不适用场景。parametersJSON Schema描述输入参数。handler可调用对象接收参数并返回结果。examples2到3条“用户问题 → 应调用本技能”的示例能显著提升命中率。priority优先级用于多个技能都满足条件时决策。timeout / retry执行超时和重试策略。permissions技能运行所需的最小权限声明比如哪些API、哪些文件目录。2.2 技能注册与意图路由让模型在正确时机选对技能有了技能定义下一个要解决的是“模型怎么知道现在该用哪个技能”。我把这个过程拆成两步注册和路由。注册就是建一个技能清单把所有技能对象放进一个注册表。这一步本身没有太多难点但要点在于“注册表里装的是描述而不是实现”。你在运行时需要实时拿到所有技能的描述去参与路由判断。很多框架会把这个过程做成装饰器一个函数加一行注解就完成注册。路由部分则讲究一些。简单场景可以直接用关键词规则用户问题里包含“工时”“估算”就命中工时技能。这种做法在演示项目里没问题但真实用户说的话千奇百怪关键词覆盖率太低我很快放弃了纯规则方案。更通用的做法是“检索精排”两段式路由。第一步把用户问题向量化与所有技能的描述、示例做相似度检索召回 TopN 候选技能。第二步把候选技能的完整描述、示例和用户问题一起发送给大模型让模型从候选里挑一个或几个并输出标准化的调用参数。这样做的好处是即使你注册了上百个技能模型每次只需要在最多5个候选里做选择准确率会高很多也不会把上下文撑爆。这段路由逻辑可以用一个很朴素的方式落地注册表 向量检索 一次带JSON输出的模型调用。你不需要一开始就上复杂的Agent框架只需要确保最终链路是用户输入 → 路由组件 → 技能执行 → 结果返回给模型 → 模型组织回答。3. 从零搭一个技能库实操过程记录3.1 用最少代码实现技能注册与调度我平时喜欢用 Python 做这类原型因为生态成熟调试方便。下面这套代码是我实际项目里精简出来的去掉了一些业务细节保留了核心骨架。它灵活到足够支撑中小型Agent应用。import json from typing import Any, Callable, Optional from dataclasses import dataclass, field dataclass class Skill: name: str description: str parameters: dict handler: Callable[[dict], Any] examples: Optional[list[str]] None priority: int 10 def to_prompt_snippet(self) - str: return json.dumps( { name: self.name, description: self.description, parameters: self.parameters, examples: self.examples or [], }, ensure_asciiFalse, indent2, ) SKILL_REGISTRY: dict[str, Skill] {} def register_skill( name: str, description: str, parameters: dict, examples: Optional[list[str]] None, priority: int 10, ): 装饰器把普通函数包装成技能并注册到全局注册表。 def decorator(handler: Callable[[dict], Any]): SKILL_REGISTRY[name] Skill( namename, descriptiondescription, parametersparameters, handlerhandler, examplesexamples, prioritypriority, ) return handler return decorator这里最核心的是Skill这个数据类。to_prompt_snippet方法会把技能描述格式化成一段JSON文本后续可以拼进系统提示词里也可以送到向量检索模型。你用装饰器注册的每个技能都会被收集到SKILL_REGISTRY中路由和执行都能统一从这个表里找。接下来是路由我这里提供一个两步实现的例子。先用关键词做粗筛然后用大模型精挑。如果你没有本地向量库也可以把第三节中的向量的部分替换成简单的“把全部技能描述发给模型”但技能超过20个后效果会明显下降。def route_skill(user_input: str): # 第一步关键词粗筛缩小候选范围 candidates [] for skill in SKILL_REGISTRY.values(): # 这里可以换成向量检索关键词只是演示 if any(kw in user_input for kw in skill.name.split(_)): candidates.append(skill) if not candidates: candidates list(SKILL_REGISTRY.values())[:3] return candidates当然真实项目我不会真的只用函数名匹配那太脆了。我会把所有技能的name、description、examples拼成文档用嵌入式模型建索引。用户输入先做余弦相似度召回前5个再让大模型从5个候选里选择并输出调用参数。这一步里大模型的“选择”不是简单的查字典它还会根据用户话里的信息把参数补全。3.2 一个完整示例让Agent学会“计算项目工时”说了这么多理论我们来落地一个确实能用上的技能工时估算。这是做项目管理类产品时很常见的需求。用户可能问“我们一个10人的团队要做一个带后台管理系统的App大概要多久”我先定义技能。工艺是把任务清单和人数传进来内部用三点估算法计算。register_skill( nameestimate_project_hours, description估算软件开发项目工时。适用于项目排期、资源评估、任务拆解后的工作量预估。不适用于硬件生产或非技术类任务。, parameters{ type: object, properties: { task_list: { type: array, items: {type: string}, description: 任务清单例如[用户注册登录,后台商品管理,支付接口对接], }, team_size: { type: integer, description: 参与开发的人数, minimum: 1, }, complexity: { type: string, enum: [low, medium, high], description: 整体复杂度, }, }, required: [task_list, team_size], }, examples[ 我们10个人做一个电商小程序要多久, 估算一下开发一个后台系统的工作量, ], ) def estimate_project_hours(params: dict): task_list params[task_list] team_size params[team_size] complexity params.get(complexity, medium) # 简化示范每项任务的基础小时数再按复杂度调整 base_hours { low: 24, medium: 40, high: 64, } per_task base_hours[complexity] total_hours per_task * len(task_list) # 考虑人员沟通损耗人越多单位效率越低 effort_coefficient 1 (team_size - 1) * 0.05 optimized_total int(total_hours * effort_coefficient) return { total_hours: optimized_total, task_count: len(task_list), complexity: complexity, advice: 建议至少预留20%缓冲时间, }当用户提问进来后系统把该技能的描述和参数给到路由模型模型提取出{ task_list: [用户注册登录, 后台商品管理, 支付接口对接], team_size: 10, complexity: medium }然后执行器被调用得到结果。注意这个结果不要直接原样返回给用户应该再交给模型加工一遍让它生成一段“工时时长大约X小时约合X人天建议预留缓冲”之类的人话。这就是智能体工作时的完整闭环用户自然语言 → 模型结构化参数 → 程序精确计算 → 模型人性化表达。3.3 技能间协作与编排把单个技能拼成流水线单个技能解决的问题是有限的。更复杂的任务比如“把今天的销售数据报表下载下来→生成摘要→发送到钉钉群”需要通过编排器把多个技能串起来执行。我建议用最简单的有向无环图DAG来做编排而不是用固定顺序的if-else链。因为真实流程经常有“摘要和统计可以并行”这类情况DAG能灵活描述依赖关系。class SkillNode: def __init__(self, skill_name, input_params): self.skill_name skill_name self.input_params input_params self.depends_on [] self.output None class SkillOrchestrator: def __init__(self): self.nodes [] def run(self, user_input): # 建立执行顺序先跑没有依赖的技能再按依赖链串起来 done set() while len(done) len(self.nodes): for node in self.nodes: if node in done: continue if all(dep in done for dep in node.depends_on): skill SKILL_REGISTRY[node.skill_name] node.output skill.handler(node.input_params) done.add(node) return {node.skill_name: node.output for node in self.nodes}调用方可以手动声明orchestrator SkillOrchestrator() download SkillNode(download_report, {}) summary SkillNode(generate_summary, {}) summary.depends_on.append(download) notification SkillNode(send_notification, {target: group}) notification.depends_on.append(summary)这种方式把技能的复用性发挥到了极致。每个技能不知道其他技能的存在只关心输入输出格式编排器只负责串联顺序不关心内部实现。以后如果要从钉钉换成企业微信只需要新增一个send_notification的实现改一行注册信息编排逻辑完全不用动。4. 技能评估与典型问题排查4.1 怎么判断一个技能好不好用很多同学开发完技能就急着联调结果只测了两条用例就觉得“可以了”。等到真实用户进来需求变化一多各种问题就暴露了。我给自己的项目定了几个评估维度每次新技能上线都过一遍路由准确率用户一句意图明确的话系统是否正确选择了目标技能。参数完整率模型是否把必填参数都提取出来了枚举值是否合法。执行成功率技能执行器是否有异常、超时、返回格式错误。端到端满意度加完技能后用户问题的最终回答是否比“没有技能”时更好。我会维护一个小型测试集。每类技能准备10条左右覆盖不同表达方式的用户问题比如“这个大概多久”和“帮我排一下下周的开发计划”其实指向同一个工时技能但表达完全不同。每次修改技能的描述或参数Schema后跑一遍这个测试集看路由准确率和参数完整率有没有下降。这个习惯能帮你避免“改好了一个技能反而破坏另一个技能”的回归问题。4.2 高频踩坑误路由、参数错乱、上下文丢失以下是过去半年里我遇到最多的几类问题以及对应的排查思路现象根因处理方式用户说“估算一下工时”模型却调了“成本分析”两个技能描述太像在描述里写出更明确的边界比如“成本分析是财务口径不包含开发人力估算”技能返回了结果但用户问“为什么是这个数字”模型答非所问执行结果没传回给模型加工不要直接把JSON返回给用户让模型基于结果组织回答参数里应该传数组模型传了逗号分隔字符串JSON Schema类型不严格检查路由提示是否注明了具体类型必要时让模型先输出JSON再做校验技能链很长时中间某一步结果丢了编排器没有保留中间上下文把每个节点的输出存在统一的上下文字典里传参时从上下文读取而不是重新让模型生成参数错乱这个问题我要多说两句。很多人认为模型传错参数是模型笨其实多半是你在技能定义时没有给足信息。比如“时间范围”这个参数如果你只写start_time: string模型大概率会猜格式如果你在描述里写清楚格式为YYYY-MM-DD默认是今天错误率会成倍下降。技能参数Schema里的description字段重要性不亚于技能总描述。4.3 经验补充技能数量不是越多越好做技能库最上瘾的事就是不断往里加新技能但这里有个很反直觉的规律技能数量超过一定阈值后整体效果反而会下降。因为路由模型面对的选择越多越容易发生“相似技能互相干扰”。我在一个项目里试过把技能从30个增加到60个结果路由准确率从92%掉到85%后来不得不做技能下架和合并。现在我会遵循几条实操原则第一每个技能必须能回答“它独有的价值”如果两个技能有80%的输入输出重叠就并成一个。第二技能应该按业务模块分目录管理例如sales/、hr/、ops/路由阶段先按业务领域粗分再进入技能精排而不是让一个平面列表承载所有能力。第三每季度清理一次调用日志把调用率极低的技能下架或重写描述因为很可能用户根本不知道你有这个能力说明描述没写对。另外我在后期给每个技能的描述里都加了一段“负面示例”也就是明确写清楚这个技能不要用于什么场景。别小看这句话它能显著减少误路由。比如工时估算技能的描述里有“不适用于硬件生产或非技术类任务”之后用户问“一条流水线要几个人”时模型就不太会错选这个技能。对我个人来说这个是投入产出比最高的一个技巧。技能体系的设计没有标准答案但“技能描述 参数协议 执行器 编排器”这套四层结构是很容易上手、也经得起业务考验的组合。如果你正在做Agent应用先不要急着堆功能挑一个最常被问到的任务按这个结构封装成技能跑通一遍完整链路再逐步扩展。很多问题会在第一个技能落地之后变得更加清晰。