去年我在一个内部知识库问答系统上第一次踩到“技能组织”的坑。当时功能其实都写好了查库存、算价格、发邮件、建工单一个个Python函数摆在那里。结果大模型经常选错工具或者把参数传错一场演示下来翻车了好几次。后面我把这些能力重新按“技能”而不是“函数”来组织加上了描述、参数约束、测试样例效果才明显稳下来。这篇文章想聊的就是这套被我验证过多次的做法。所谓的agent-skills说人话就是让大模型能够稳定发现、理解、调用的一组可执行能力单元以及围绕它们衍生出的设计、实现、评测和迭代方法。它解决的核心问题是模型再聪明如果没有一套能被正确调用的“手”也做不成事而工具一多怎么让模型不选错、不卡死、不受损就是技能工程需要回答的事情。如果你是做Agent应用开发、想给自己的大模型接上工具或者单纯想看看一套技能库应该长什么样这篇文章应该能帮你节约不少试错时间。1. 先把“技能”这件事想清楚1.1 为什么不是简单函数调用很多同学一开始都会想Agent调用工具不就是“给模型一个函数列表让它自己选”吗理论上没错但实操中这里有三层认知很容易被忽略。第一函数调用是编程视角技能是模型视角。你在代码里写query_inventory(item_id: str)模型并不知道“item_id”究竟是SKU编码还是商品名称也不知道这个函数适合在什么业务场景下用。技能需要额外提供一句人话说明比如“当用户询问某商品是否有现货时调用参数item_id为商品唯一编码可从商品详情中提取”。第二单个函数往往不构成完整能力。比如“下单”这个动作可能需要先查库存、再查价格、再校验地址、再创建订单。如果把这一整串都做成一个函数内部会非常臃肿但如果不封装模型需要自己编排好几个工具推理链路长了以后错误率会指数上升。技能允许你把这串动作封装成一个更高层的复合能力让模型只做一次决策。第三函数调用是静态的技能体系是动态的。新业务上线时你不需要改动Agent的主流程只需要注册一个新技能描述清楚它是什么、能做什么、参数怎么传模型下次就能用。这种“即插即用”的能力扩展方式才是技能工程化最大的价值。所以我的结论是不要把技能理解成API网关上的接口列表而要把技能理解成“给模型看的说明书可执行逻辑”的组合体。设计时始终问自己一个聪明但完全不了解我们业务的人看到这份说明书能不能正确使用它1.2 技能的三要素一个能被Agent稳定使用的技能至少包含三个部分身份描述、参数契约、执行逻辑。三者缺一个都会出问题。身份描述回答“这个技能是什么、什么时候用”。我习惯给每个技能写下面几类信息技能名称要唯一且语义清晰、一句话摘要不超过50字、使用场景写清楚触发条件包括“什么时候不要用”、依赖关系它内部调用了哪些下级能力。参数契约回答“模型应该传什么进来”。这部分建议直接用JSON Schema。好处是模型推理时结构明确校验逻辑也统一。每个参数都要写清楚类型、是否必填、取值范围、示例值特别是“示例值”非常有用——模型在不确定参数格式时会参考示例来推断这比在描述里写一大段规则有效得多。执行逻辑回答“调用之后实际发生什么”。这是一个普通函数、一段工作流、还是一个外部服务请求都不重要。重要的是它必须有明确的成功与失败返回结构。我会统一用{success: true, data: ...}和{success: false, error: {...}}两种结构返回这样模型在观察阶段才能正确判断是否需要换工具或重试。1.3 技能工程化解决的三类痛点把技能当作一等公民来管理而不是散落在代码里的工具函数主要能解决三类痛点。第一是选择准确率问题。技能带上了场景描述和禁用条件之后模型选错的概率会明显下降。比如我有一个“查天气”的技能描述里明确写了“仅用于未来3天天气预报历史天气请使用查历史天气技能”模型就不会拿它去回答昨天的天气。第二是维护成本问题。没有技能库的时候要用某个能力就得去翻代码、找函数、猜参数。有了统一的技能清单和版本管理运营同学也能通过配置中心维护技能描述不用每次改个说明都要走上线发布流程。第三是扩展性问题。系统要接入一个新领域能力时只需要新增技能并注册Agent主流程和提示词都不用动。我在做跨部门系统集成时就是靠这种方式把几个团队的工具统一汇入一个技能库各自维护各自的技能互不干涉。2. 设计一套可复用的技能体系2.1 技能分层原子、复合、编排把所有技能都平铺开来数量一多就会乱。我一般分成三层。原子技能是最小可执行单元比如查询天气、发送邮件、创建工单。它们一般对应单次外部调用没有内部子技能依赖。复合技能由多个原子技能或小复合技能编排而成比如“下单购买”内部会依次调用查库存、算价格、创建订单。编排技能本身不执行具体业务逻辑它的职责是判断当前场景需要哪些复合技能并按顺序触发。分层带来的最大好处是职责清晰。原子技能保持单一职责容易测试复合技能把常见多步操作固化下来减少模型推理负担编排技能则负责在更高维度上做路由。我做智能客服时给技能分层的体会是把“查询”和“操作”严格分开。查询类技能可并发执行操作类技能需要用户确认。如果混在一起模型可能在用户还没确认时就执行了下单操作这是产品层面的严重事故。所以设计分层时不只是看技术复杂度还要看业务风险等级。2.2 技能描述怎么写才不让模型误解技能描述是模型“看到”的唯一窗口它的质量直接决定选择准确率。我踩过很多次坑之后总结出几条写法经验。描述开头第一句话直接说功能不要铺垫。模型在推理时是逐词读取的如果前20个字还在讲“本技能用于帮助用户解决……”真正功能信息就被冲淡了。正确写法是“列出用户指定时间段内的所有历史工单记录。”写清“什么时候用”和“什么时候不用”。很多模型误选工具就是因为没有禁用条件。我会在描述里专门加一节使用限制说明这个技能不覆盖哪些场景模型看到明确禁用信息后通常会转去调用正确技能。参数说明都用示例说话。不要只写“date: 日期”要写“date: 2025-05-01注意日期格式为YYYY-MM-DD必须是过去时间”。示例比规则更直观因为模型在大量训练数据中见过示例形式的表述。描述长度也要控制。太长会占用上下文太短又说不清楚。我一般控制在200字左右重点信息前置。超过300字的描述我会考虑拆成两级把核心功能放前面详细规则放参数的description里。2.3 冲突消解与优先级策略技能多了以后一定会遇到“多个技能都能完成类似任务”的情况。比如我做过一个系统里同时有“查快递”和“查物流”两个技能功能高度重叠模型经常选错。我的处理方式是建立冲突消解表。在技能管理后台里维护一张关系表注明哪些技能之间存在重叠、各自的优先场景是什么、当模型同时匹配到多个技能时默认推荐哪一个。然后在系统提示词里加一段通用规则若多个技能描述指向同一目标优先使用专名更具体的技能若无法判断优先使用最近上线的版本。如果重叠实在无法避免干脆合并。有一次我只保留了一个“统一搜索技能”内部根据关键词自动路由到不同数据源模型不再需要纠结选哪个。这样做的代价是这个技能内部会变复杂但推理层的选择负担就减轻了。2.4 技能边界划分的经验给技能划边界有一个实用技巧按“用户可以自然表达的意图”来切而不是按“后端提供的接口”来切。比如后端可能拆了订单查询、订单详情、订单状态三个接口但用户只会说“帮我看看我的订单到哪了”。这时应该把它们合并成一个“查询订单状态”技能内部自己组合接口。边界画得太细模型选择困难画得太粗技能内部变成一个庞然大物维护困难。我的经验是一个技能对应的用户意图尽量保持在“一句话能说清楚”的程度。否则就继续拆。3. 实操搭建一个最小可用的技能库3.1 项目结构怎么组织我习惯用一个独立目录来承载所有技能而不是和主程序混在一起。目录结构大致如下agent_skills/ ├── registry.py # 技能注册器 ├── models.py # 技能数据模型 ├── loader.py # 动态加载技能 └── skills/ ├── __init__.py ├── order_query/ # 一个技能一个目录 │ ├── skill.yaml # 技能描述与参数契约 │ └── handler.py # 执行逻辑 ├── weather_query/ │ ├── skill.yaml │ └── handler.py └── ...每个技能独立目录的好处是可以单独写测试、单独发布、单独维护负责人。skill.yaml里放的是给模型看的描述和参数契约handler.py里放的是真正的执行逻辑。两者分离意味着描述调整可以不用动代码也就是运营同学能直接参与维护。3.2 定义一个技能的数据结构我先定义一个技能的数据模型把技能名、描述、参数契约、执行函数都绑在一起。下面使用pydantic来做校验实际你用什么库都行关键是字段清晰。from typing import Any, Callable, Optional from pydantic import BaseModel, Field class Skill(BaseModel): name: str Field(description技能唯一名称使用小写加下划线) description: str Field(description给模型看的技能描述) parameters: dict Field( default_factorydict, descriptionJSON Schema格式的参数契约 ) handler: Optional[Callable[..., Any]] None tags: list[str] Field(default_factorylist) version: str 1.0.0 disabled_scenarios: str Field( default, description描述该技能不适用的场景 ) def invoke(self, **kwargs) - dict: if self.handler is None: return {success: False, error: {code: NO_HANDLER}} try: result self.handler(**kwargs) return {success: True, data: result} except Exception as e: return { success: False, error: {code: EXEC_ERROR, message: str(e)} }这个模型很像一个“给模型看的函数签名”。description和parameters是模型能看到的handler是实际执行的模型看不到。disabled_scenarios是我后来加的用来告诉模型“别乱用”效果很显著。3.3 动态加载与注册机制技能库不可能每次新增技能都改主程序代码所以需要一个动态加载机制。我在loader.py里实现了一个简单扫描器遍历skills/目录下所有子目录读取每个子目录里的skill.yaml再导入同目录下的handler.py。import importlib.util import yaml from pathlib import Path from .models import Skill SKILL_ROOT Path(__file__).parent / skills def load_skill_from_dir(skill_dir: Path) - Skill: meta_path skill_dir / skill.yaml handler_path skill_dir / handler.py with open(meta_path, r, encodingutf-8) as f: meta yaml.safe_load(f) spec importlib.util.spec_from_file_location( skill_dir.name _handler, handler_path ) module importlib.util.module_from_spec(spec) spec.loader.exec_module(module) return Skill( namemeta[name], descriptionmeta[description], parametersmeta.get(parameters, {}), handlergetattr(module, handle), tagsmeta.get(tags, []), versionmeta.get(version, 1.0.0), disabled_scenariosmeta.get(disabled_scenarios, ), ) def load_all_skills() - list[Skill]: skills [] for child in SKILL_ROOT.iterdir(): if not child.is_dir(): continue skill load_skill_from_dir(child) skills.append(skill) return skills这种动态加载改造成本很低却让技能库具备了很强的扩展性。后来我还加了基于文件修改时间的自动重载开发调试时改完技能描述保存一下就能生效不用重启服务体验非常好。3.4 技能测试与依赖管理技能库的测试不能只测功能逻辑还要测描述文本和参数契约是否符合预期。我会写两类测试。第一类是单元测试直接调用handler验证执行逻辑。比如模拟一个天气接口返回固定数据断言技能返回结构正确、参数校验失败时能返回规定的错误格式。第二类是契约测试检查skill.yaml里的描述是否满足规范。我用一个脚本扫描所有技能检查必填字段是否齐全、参数Schema是否符合JSON Schema规范、描述里是否包含禁用场景说明。这些自动化检查在CI里跑能挡住不少低级错误。依赖管理方面一个领域内高度相似的技能共用底层客户端模块不要让每个技能自己封装HTTP请求。我把共享客户端抽成common/clients.py技能里的handler只负责业务逻辑和参数组装。这样接口升级时只需要改一处。4. 接入Agent运行时的关键环节4.1 把技能列表交给模型的结构技能库建好了下一步是让它真正进入Agent的推理循环。目前主流做法是直接把技能列表序列化成模型可读的JSON结构拼进系统提示词。序列化时注意要保持原始JSON Schema不要自己简化。def build_skills_prompt(skills: list[Skill]) - str: lines [] for s in skills: schema { name: s.name, description: s.description, parameters: s.parameters, } if s.disabled_scenarios: schema[disabled_scenarios] s.disabled_scenarios lines.append(json.dumps(schema, ensure_asciiFalse, indent2)) return \n\n.join(lines)我见过有些团队为了省tokens把参数描述全部删掉只留参数名结果模型乱传参数。省那一两百个token换来的是百分之十几的工具调用失败率完全不划算。参数契约是模型唯一能参考的格式规范能保留就保留。4.2 工具调用失败以后怎么办技能执行不可能百分百成功。模型调用工具拿到失败结果后表现高度依赖返回信息的质量。如果返回只是一句“Error”模型根本不知道错在哪、要不要重试。我设计的失败返回包含错误码、错误阶段、修正建议三块。举个例子{success: false, error: {code: MISSING_PARAM, field: user_id, message: 缺少用户ID请先获取用户信息}}模型读到这个结果知道自己缺了什么参数、该去哪里补下一步就会去调用“获取用户信息”技能而不是反复重试同一个失败的调用。错误码要尽量稳定且枚举化模型会更愿意依据已知错误码做分支判断。还有一个关键点是重试限制。我会在Agent循环里记录每个技能的最大调用次数比如默认3次。超过次数还没成功就让模型更换策略或直接向用户说明暂时无法完成避免无限循环烧token。4.3 上下文膨胀与结果压缩技能调用多了Observation会非常长尤其是查询类技能把一堆数据塞回上下文很快就把窗口占满。我常用的三种压缩手段只返回摘要而不是原始结果。比如查库存技能返回的不是全部明细而是“共找到132个SKU其中缺货3个详见附件”。模型需要的是结论和判断依据细节放在执行结果文件里需要时再让模型调用详情查询技能。截断长列表保留头部和尾部。模型通常最需要知道“有哪些”“总量多少”中间大量重复项可以省略用一句...共省略120条...示意。用向量检索代替全量返回。我在一个文档问答技能里就是这么做的先把文档切片向量化存入检索库技能返回给模型的只是“已检索到相关段落共5条”而不是把整份文档塞回去。上下文压力瞬间小了很多。4.4 多Agent场景下的技能共享与隔离技能库在单一Agent里跑起来之后迟早会遇到多Agent的场景客服Agent、数据分析Agent、后台管理Agent都挂在同一个技能库上。这时必须考虑共享和隔离。我采用的方案是给技能增加可见性标签按Agent角色过滤。def visible_skills(skills: list[Skill], roles: set[str]) - list[Skill]: return [ s for s in skills if not s.tags or (s.tags roles) ]比如下单类技能只有客服角色可见数据批量导出技能只有管理员可见。这样模型即使看到了全部技能列表也应只按自己的角色权限调用避免跨权限操作。权限判断不能只靠提示词执行端必须再做一次校验。真正安全的做法是技能执行前根据调用来源角色再做一次白名单检查防止模型被诱导执行未授权操作。这里要特别强调永远不要相信模型不会越权。技能库的权限边界必须在执行层硬性约束提示词只是辅助手段。5. 技能质量的评测与持续迭代5.1 构造评测场景的方法技能好不好不能靠感觉。我的做法是准备一套Golden Set每个用例记录用户的原始输入、期望调用技能名、期望参数值。数量不求多但覆盖面要广。50个精心设计的用例比500个随意泛化的用例更有效。用例设计有几个角度常见意图用户最常说的话、边界意图类似“帮我查一下”这种缺少关键信息的输入、易混淆意图两个技能都能沾边的场景、禁用意图描述里明确不支持的场景。每一类都配10条以上基本能把技能选型的问题暴露出来。跑评测的方式很简单把Agent系统提示词和技能列表固定住只输入用户文本记录模型实际调用结果和期望值对比。我一般会统计准确率和错误类型分布。5.2 关键指标怎么解读我长期关注的指标有三个技能命中率、任务完成率、平均调用轮次。技能命中率指的是模型选对技能且参数基本正确的比例。低于80%说明技能描述有严重问题需要重写描述而不是继续调提示词。任务完成率看的是整条链路的最终效果包含执行成功和模型正确判断是否需要换技能。平均调用轮次则反映效率一个简单查询如果模型绕了三五个工具才做对说明技能编排有问题多半是复合技能没有封装好。表格可以这样记录对比指标优化前优化后变化原因技能命中率68%91%参数示例补全、禁用场景写清任务完成率53%87%复合技能封装下单链路平均调用轮次6.23.1统一搜索技能减少路由判断5.3 回归测试与版本管理技能库一旦被多个Agent共用改动影响范围会很大。我经历过一次改技能描述把所有Agent都带崩的惨案之后非常强调回归测试。每次有技能描述或逻辑变更我会先在测试环境跑一遍完整Golden Set对比指标差异再决定是否上线。版本管理上skill.yaml里的version字段必须递增。技能发布系统会记录每个技能的历史版本支持一键回滚。做法不复杂发布时把整个skills/目录打一个快照回滚时把快照内容覆盖回去即可配上一个简单的版本号路由就能做到。5.4 持续运营的节奏技能库不是上线就完事的需要持续运营。我给维护定了几个固定节奏每周从线上日志里抽一次失败案例看错误分布每月用新需求驱动新增技能每个季度做一次全量评测对比当季目标。线上日志里的错误分析是最重要的来源。比如某个技能用户用得多但失败率高可能不是描述问题而是下游接口不稳定。这些经验积累下来技能库会越来越像一个稳定运转的产品而不是一堆临时脚本。6. 我的实际体会这套技能工程化的思路前前后后改进了三四轮我最想分享的教训是模型的能力边界决定了技能描述怎么写而技能描述的质量决定了整个Agent的上限。与其花大把时间调prompt不如把功夫下在技能设计上效果更稳定也更可持续。如果你正准备从零搭一个Agent技能库我的建议是不要一上来就把所有功能都封装上去。先挑两三个最核心、最容易被模型理解的技能跑通全流程再逐步扩展。技能描述写不好的时候多拿真实用户输入去测试让模型告诉你哪里不够清楚——它在选错工具时给出的“思考过程”就是最直接的优化线索。最后再分享一个小技巧每个技能的skill.yaml里加一个test_cases字段存放两三条典型的用户输入样例。调试Agent时直接在提示词里加入当前技能对应的样例模型往往能快速对齐使用方式比纯描述更管用。这个细节让我在项目后期的排查效率提升了不少。