做AI Agent开发的朋友应该都有这种体会刚把工具函数接入大模型时效果挺惊艳可一旦场景复杂起来代码就变成一团乱麻——几十个函数堆在一起模型经常选错目标参数格式写错一次就要返工一小时。我接触agent-skills这个概念大概半年多前前后后在几个不同的模拟项目X里试过好几套方案今天把其中一套比较成熟的架构思路整理出来希望能给正在做Agent落地的朋友一些参考。agent-skills说白了就是给智能体准备的一套“技能库”。它跟单纯的函数列表不太一样重点是把一个能力按标准格式封装起来包含技能的名称、描述、输入输出Schema、执行逻辑、依赖资源甚至可以包含一组完整的工具调用序列。Agent在运行时会根据当前任务主动去技能库中检索和匹配选中最合适的技能来执行。这样一来Agent不再只是一个会说话的回答机器而是变成了一个有工具箱、有操作规范、能持续沉淀能力的执行者。这篇内容适合谁看正在做AI助手、自动化助手、智能客服、工作流引擎的开发者都能用得上。哪怕你的Agent还没上生产只是在学校内部项目或企业内部验证阶段这套思路也能帮你把系统搭得更稳。我会尽量把设计思路、踩坑过程和完整代码骨架都写出来希望能真正帮到你。1. 为什么Agent需要技能库而不是纯靠Prompt1.1 从“会调用工具”到“具备技能”的转变很多人最开始做Agent的时候习惯把所有能力都塞进System Prompt里比如“你可以使用以下工具get_weather、book_hotel……”然后让模型自己去拼。这种做法在小规模、工具数量少于五个的时候是可以接受的我也这么做过图省事。但一旦超过十个工具问题就开始暴露Prompt太长导致模型注意力分散描述写得不仔细就会选错增加新工具还得频繁改提示词而且不同工具的输入输出风格五花八门Agent内部要针对每个工具写适配代码。这就是单纯“工具接入”阶段最大的痛点。技能库的思路是把“工具”再往上升一层。工具是最小执行单元比如一个查询接口、一个计算函数技能则是一个“完整动作”它可能只依赖一个工具也可能串联好几个工具并且自带规则和边界条件。比如“查询天气并给出穿衣建议”单看工具层需要至少两个能力天气查询和知识推理。但作为技能它应该是一个整体先查天气再根据温度范围、降水概率组织建议文案。模型只需要做一次选择执行细节全部封装在技能内部。这个抽象层面的提升非常关键。它让Agent的决策面变小了——不是让模型去编排每一步工具调用而是让模型在有限的技能菜单里做选择。菜单里的每项技能都经过测试和验证执行结果可控。我在实际项目中体会最深的一点是Agent系统的可靠性往往不是靠模型聪明而是靠决策范围收窄。模型需要做的判断越少出错率就越低。1.2 技能库到底解决了什么核心问题技能库不是花架子它解决的是三个核心问题。第一是复用。同样一个“内容安全审核”技能可以在内容生成Agent里面用也可以在用户反馈处理Agent里面用只要接口定义一致换一个Agent实例就能直接挂载。做过多个Agent的人应该都有经验如果没有统一的技能层同一套逻辑就得在每个Agent里重新实现一遍维护成本直接翻倍。这里说的复用还不只是代码复用更重要的是能力沉淀。一个技能被验证有效它就能成为团队的基础资产后面开发新Agent时可以直接调用不用每次从头设计。第二是管理。技能库把每个能力的版本、依赖、测试用例都固化下来能单独升级、单独回滚。我在某跨平台系统里遇到过一种情况某个汇报生成技能改了一版Prompt之后其他Agent的对话质量集体下降排查了半天才发现是因为技能库是共享的有人直接改了原文件。后来改成版本隔离每个Agent锁定技能的某个版本问题才彻底解决。这个坑让我意识到技能库必须做版本管理不能只有一坨最新文件否则牵一发而动全身。第三是可验证。技能库里的技能是可以单独测试的不需要跑到完整Agent链路里才能验证。这一点在工程实践里非常有价值。我经常用一套固定的测试用例去回归技能库改一行代码就能知道会不会影响到其他调用方。这种确定性让人很安心也是技能库跟散乱工具函数最本质的区别之一。1.3 技能、工具、插件、工作流的边界很多人对这几个概念是混着用的我在团队评审时也经常被问“这跟插件有什么区别”。我的理解是工具是最底层它不关心业务就是一个能完成某个原子操作的函数或接口比如“发送邮件”“解析PDF”。技能是工具的封装它有明确的业务目标和输入输出契约比如“生成会议纪要并发送给指定参会人”内部可能用到了语音转文字、摘要、格式化、发送邮件四个工具。插件是技能的集合和分发单元通常包含一组相关技能再加上自己的界面或配置入口可以整体安装卸载有点像一个技能包。工作流则是技能之上的编排层它表达的是“先做A再做B如果条件C成立就做D”的流程逻辑偏业务层面。把这一层理清楚之后你会发现设计技能库时不会纠结“这个能力该放在哪儿”。比如一个纯粹的PDF解析功能它应该是一个工具不占技能库名额而“从PDF中提取表格并整理成结构化数据”就是一个技能因为它有明确的目标描述和输出规范甚至可以内部选择用哪个解析工具。这种边界感让我在设计新Agent时省了很多不必要的争论。2. 技能库设计的三个核心原则2.1 原则一统一接口让输入输出都有Schema约束技能库如果想让不同Agent都能调用第一件要做的事就是统一接口格式。最通用的做法是给每个技能定义输入参数和输出结果的JSON Schema用类型、必填、描述、默认值来约束输入用固定结构描述输出。这里有一个容易被忽视的点不仅输入要校验输出也要有结构化的Schema。如果技能返回的是自由文本模型的后续决策就缺少确定性的抓手很难稳定地做下一步操作。举个例子一个“分析用户评论情感”的技能输出如果只是一个字符串“比较满意”下游技能根本没法做数值判断。更好的输出是{sentiment: positive, confidence: 0.93, summary: 用户对物流速度满意}这样即使不依赖大模型普通代码也能处理还能把置信度数值直接用在下游统计里。我觉得这一步是整个技能库的地基。Schema定义得越清晰后面做参数校验、自动补全、接口测试都会越顺。我见过不少团队先写执行逻辑回头补Schema结果发现逻辑里的输入输出跟契约对不上返工量大得吓人。所以我的建议是任何技能的Schema设计都要跟执行逻辑开发同步推进哪怕先草草写一版也要让契约先立起来再围绕它实现。2.2 原则二描述语料要写给模型看不只给人看技能的描述字段往往决定了模型能不能在正确的时候选中这个技能。这里说的描述不是功能文档而是给大模型看的“使用说明书”。它需要包含几个关键信息这个技能是干什么的、适合在什么场景下用、什么情况下不要用、输入输出分别是什么。描述写得太简单比如只写“获取天气”模型很容易在需要穿衣建议的时候去调用天气技能而不是去调用更高层的穿衣建议技能描述写得太啰嗦又会稀释模型注意力导致技能检索效率下降。我常用的写法是几个固定的段落一句话总结然后写适用场景再写不适用场景最后给一个典型调用例子。句子尽量短动词明确避免模糊词汇。比如一个“订单取消”技能描述可以是“当用户要求取消尚未发货的订单时使用。不适用于已发货订单已发货订单请使用‘售后申请’技能。典型输入订单ID、取消原因。”实测下来这种结构化描述能让技能选错率明显下降。我还在元数据文件里加了一个examples字段里面放两三条真实的输入输出对效果比单纯写描述更稳定。之前看过一份评测报告说模型对示例的敏感度其实高于对描述文字的敏感度这点我在实际项目中也深有体会。与其花大量时间打磨描述措辞不如先把高质量示例补上。2.3 原则三技能粒度要收放有度技能粒度这个东西我一开始也控制不好走了不少弯路。粒度太细比如写了一个“发送HTTP请求”技能结果Agent每个动作都要绕一圈又慢又琐碎等于是把工具列表换了个名字并没有解决决策负担的问题。粒度太粗比如写了一个“完成整个营销方案”技能模型几乎没法复用稍微换一个需求场景就失效了等于写死了一个一次性业务脚本。我的经验是利用“可复用边界”来判断如果一个技能能被两个以上不同的任务用到粒度就是合适的如果只能被一个特定任务用到要么继续拆分出通用子技能要么接受它就是一个独立业务脚本不进技能库。写技能的时候多问自己一句除了当前需求还有谁会用到这个技能如果答案是没人那就把它设计成通用技能的组合调用而不是单独建一个独占技能。还有一个实操技巧同一业务域里尽量保证技能水平一致。如果“生成文案”和“生成文案并配图并定时发布”同时存在模型很容易混淆不知道该选哪个。我的建议是只保留粗粒度技能把细粒度能力作为内部工具隐藏起来让技能库的条目总数保持在几十个以内。这样模型选择压力小维护成本也低很多。3. 从零搭建一个最小可用的技能库3.1 目录结构与技能元数据设计先看目录结构。我比较喜欢用扁平化加标签的方式而不是深层嵌套。每个技能占一个目录目录名就是技能ID里面至少包含元数据文件skill.yaml、执行脚本exec.py和可选的依赖声明文件。目录结构如下skills/ email_reply/ skill.yaml exec.py tests/ cases.json meeting_summary/ skill.yaml exec.py requirements.txt review_sentiment/ skill.yaml exec.py目录名用snake_case或kebab-case都可以但全库必须统一。我建议用snake_case方便Python类库直接映射。这里顺便说一下技能ID一定不要随便改因为ID会被写进各种编排配置和接口日志里改名会导致历史数据对不上。skill.yaml的核心字段可以这样设计id: meeting_summary name: 会议纪要生成与要点整理 version: 1.2.0 description: | 当用户提供会议录音或文字稿时使用能够生成结构化会议纪要包含议题、结论、待办事项。 不适用于纯闲聊或需要翻译的内容。 典型输入会议文字稿或录音文件路径。 examples: - input: 会议记录关于Q3目标、预算…… output: 议题Q3目标确认结论预算需压缩10% input_schema: type: object required: - transcript properties: transcript: type: string description: 会议文字稿内容长度不超过20000字 include_action_items: type: boolean description: 是否输出待办事项清单默认为true output_schema: type: object required: - summary - action_items properties: summary: type: string action_items: type: array items: type: string dependencies: - llm_sdk - pydantic注意一点不要在skill.yaml里写具体的执行逻辑细节也不要放过于冗长的Prompt模板那些东西归类到exec.py或独立的prompt文件里。元数据本身要保持轻量这样模型和代码读取时才会快维护的人一眼也能看明白这个技能到底是干什么的。3.2 技能注册与动态加载技能库在代码层面要做的一个重要事情是动态注册。你不能在系统里写死一个技能字典否则每次新增技能都要改主程序。更合理的做法是在进程启动时扫描技能目录读取每个目录的skill.yaml构建索引然后按需加载执行模块。下面是一个用Python实现的简化加载器import yaml from pathlib import Path from importlib import import_util class SkillRegistry: def __init__(self, base_dir: str skills): self.base_dir Path(base_dir) self.skills {} self.modules {} def scan(self): for skill_dir in self.base_dir.iterdir(): meta_path skill_dir / skill.yaml if not meta_path.is_file(): continue with open(meta_path, r, encodingutf-8) as f: meta yaml.safe_load(f) skill_id meta.get(id, skill_dir.name) self.skills[skill_id] { meta: meta, dir: str(skill_dir), } def load(self, skill_id: str): if skill_id in self.modules: return self.modules[skill_id] spec import_util.spec_from_file_location( fskill_{skill_id}, Path(self.skills[skill_id][dir]) / exec.py, ) module import_util.module_from_spec(spec) spec.loader.exec_module(module) self.modules[skill_id] module return module def execute(self, skill_id: str, **kwargs): module self.load(skill_id) validate_input(self.skills[skill_id][meta], kwargs) result module.run(**kwargs) validate_output(self.skills[skill_id][meta], result) return result def list_skills(self): return [ {id: sid, name: meta[meta][name], description: meta[meta][description]} for sid, meta in self.skills.items() ]这个设计的关键点是元数据在启动时就全部加载执行模块在真正被选中后才动态加载。这样启动速度快内存占用也低。另外validate_input和validate_output两个函数一定不要跳过它们实际上是在执行边界上做契约校验能拦截大量脏数据。我在一个项目里就靠这两行校验函数挡住了模型传错字段的情况不然错误会一路传导到下游排查起来痛苦得多。3.3 一个完整技能的编写示例我们来实现一个比较有代表性的技能把一段产品反馈整理成结构化问题清单。这个技能在很多Agent场景里都通用比如客服系统、需求收集助手。先看技能元数据的输入输出契约再看exec.py的实现骨架。import re from typing import List, Optional from pydantic import BaseModel class FeedbackItem(BaseModel): category: str content: str priority: str medium class RunResult(BaseModel): items: List[FeedbackItem] raw_count: int def run(feedback_text: str, categories: Optional[List[str]] None) - dict: segments split_feedback(feedback_text) items [] for seg in segments: if len(seg.strip()) 5: continue category classify(seg, categories) priority estimate_priority(seg) items.append( FeedbackItem( categorycategory, contentseg.strip(), prioritypriority, ) ) return RunResult(itemsitems, raw_countlen(segments)).model_dump() def split_feedback(text: str) - List[str]: parts re.split(r[。!?.\n], text) return [p for p in parts if p.strip()] def classify(seg: str, categories: Optional[List[str]]) - str: if categories: for cat in categories: if cat in seg: return cat return 其他 def estimate_priority(seg: str) - str: if re.search(r崩溃|闪退|无法|严重|紧急|赔偿, seg): return high if re.search(r建议|希望|可以优化, seg): return low return medium这个技能实际运行时Agent只需要传feedback_text剩下的拆分、分类、优先级估计全部在内部完成输出结果是结构化JSON。这就是技能封装的意义对外暴露的是简单契约对内可以自由混合规则和模型调用。上面示例用的是纯规则实现实际项目中如果分类准确率不够可以在classify函数里换成调用大模型接口但要注意把超时、重试、模型名等配置放在技能目录下的config.json里由加载器统一注入不要散落在代码里。3.4 执行包装与统一异常处理技能执行时会遇到各种问题网络超时、模型接口报错、输入字段缺失、输出格式非法。如果不做统一包装Agent主循环的异常处理会被各种技能错误淹没。我建议每个技能模块统一暴露run作为入口而注册中心在执行时包一层异常处理和重试策略。重试策略要区分错误类型网络类错误可以重试两到三次业务校验类错误不要重试直接返回参数错误原因。可以在注册中心里加一个简单的重试逻辑import time def execute_with_retry(self, skill_id: str, max_retries: int 2, **kwargs): last_error None for attempt in range(max_retries 1): try: return self.execute(skill_id, **kwargs) except NetworkError as exc: last_error exc time.sleep(1.5 * (attempt 1)) except (SchemaError, ValueError) as exc: raise RuntimeError(f技能参数错误: {exc}) from exc raise RuntimeError(f技能执行多次重试仍失败: {last_error})这个方法看起来简单但在实际项目里非常管用。我在某实时数据处理Agent里用上这套后因为第三方接口不稳定导致的会话中断少了大概一半。记住一个原则技能内部不要自己加无限重试重试逻辑放在统一层避免一个卡住的技能占住线程资源不放。另外错误信息一定要写得足够详细尤其是参数校验失败时最好把期望格式和实际收到的值都列出来这样模型自己才有可能在下一次调用前修正。4. 技能编排让多个技能协作干活4.1 顺序流水线怎么设计单个技能解决的是单点问题但真实业务里往往需要把多个技能串起来。最基础的是顺序流水线。比如一个“舆情分析日报”场景需要依次做数据抓取、文本清洗、情感分析、聚合统计、生成报告。如果拆成五个技能来做每次Agent都在大模型侧决策下一步效率低且不稳定。更好的做法是把这些技能放到一条编排配置里由编排层按固定顺序执行模型只需要在入口触发一个“生成舆情日报”的总控技能。编排配置可以是一份JSON{ id: report_workflow, trigger_skill: parse_user_request, steps: [ { skill: fetch_data, inputs: {source: {{request.source}}} }, { skill: text_clean, inputs: {documents: {{steps.fetch_data.output}}} }, { skill: sentiment_analysis, inputs: {texts: {{steps.text_clean.output}}} }, { skill: aggregate_stats, inputs: {items: {{steps.sentiment_analysis.output}}} }, { skill: generate_report, inputs: {stats: {{steps.aggregate_stats.output}}} } ] }这里的变量引用语法是{{steps.xxx.output}}本质上就是让编排引擎把上一步的输出结构体传给下一步。实现这个机制并不复杂关键是要在每一步执行后缓存output对象并提供一套模板替换能力。我自己用Python实现时只写了一个简单的递归替换函数大概一百多行完全够用。顺序流水线的价值在于稳定性固定流程不会受到模型发挥波动的影响该先做的不会跳过去。它适合那些步骤明确、顺序强依赖的业务比如数据处理类任务。4.2 条件路由与技能回退很多场景不是简单的顺序线而是有分支的。比如“根据订单状态决定后续动作”已发货走物流查询未发货走改地址退款中走售后催办。这套逻辑如果全部靠Agent自由发挥状态判断容易出错。我一般推荐把条件路由写在编排层用显式的if条件控制分支。条件路由的一个常见误区是把JSON条件表达式写得过于复杂实际上你只需要支持等于、不等于、包含、正则匹配这几种基础算子就够用了。我统计过自己搭建的十几个编排流程百分之九十的分支逻辑都能用这些基础算子覆盖。把条件写清楚以后代码调试起来非常直观任何一个分支的走向都能提前预判到。另外技能回退也很重要。比如查询订单状态失败了是直接告诉用户失败还是尝试调用备用接口如果在编排层给技能配置了fallback字段主技能抛异常时自动切换到备选技能用户侧基本无感知。我在线上环境里遇到过主链路接口连续抖动的情况如果没有回退机制那段时间所有相关Agent都会跟着一起不可用加上回退之后影响范围缩小了不少。4.3 技能间的数据契约与上下文传递多技能协作最大的坑就是数据格式不对齐。技能A输出customer_id技能B期望的是user_id如果没有统一的数据契约只能靠写胶水代码编排一复杂就维护不下去。我的做法是引入一个“技能上下文对象”在每个技能执行前根据其input_schema自动截取上下文里需要的字段。如果技能输出字段名跟下一个技能不一致就在编排层配置一个显式的字段映射{ skill: get_user_profile, inputs: {user_id: {{steps.query_order.output.customer_id}}} }把这种映射放到配置里而不是写在代码里好处是业务调整时不用改主程序。这个模式我用了一段时间后发现很多成熟的开源编排工具也是同样的思路算是行业里的通用实践。再提醒一点上下文传递时尽量传递值对象或ID而不是传递庞大的中间文本。我之前踩过几次坑一个文本清洗技能把整篇大文档往下传结果后续技能越跑越慢一度以为是模型速度问题最后发现是上下文里积累了太多冗余文本。后来我让每个技能在输出时主动做一次字段精简只保留下游真正需要的数据整体token消耗和延迟都降下来了。5. 常见问题与排查技巧实录5.1 模型总选错技能怎么办这是使用技能库后最常遇到的问题表现为该调用A技能的时候模型调用了B技能或者干脆回答“我没有这个能力”。我排查时一般按三条线走。第一条看技能描述是否包含明确的“适用/不适用”边界。如果只写了一句话功能描述优先补场景边界和典型示例。第二条看技能ID和名称是否太长或者太抽象。比如某个技能叫“handle_order_exception”另一个叫“process_refund_request”模型很难区分改成“处理退款申请”“处理订单异常”这种业务化名称会更稳妥。第三条检查技能库里是否存在语义高度重叠的条目比如同时有“生成摘要”和“总结要点”模型不知道选哪个那就合并或者删掉一个。如果以上都做完了还是选错可以考虑在模型侧的System Prompt里加一个简短的技能索引列出技能ID和一句话说明让模型在决策前先扫一眼菜单。我也见过一些项目用向量检索先召回候选技能再把候选列表塞给模型做选择效果不错但整体复杂度明显更高适合技能条目超过五十个的情况。如果你的技能库还比较小先把描述和示例质量搞上去收益最大。5.2 技能Schema校验不过多半是类型和必填没对齐跟大模型打交道输入字段的格式问题几乎不可避免。模型自己生成的参数有时候会是字符串而不是数组有时候缺了必填字段。我的经验是Schema校验失败时一定要把原始错误信息原样返回给Agent让它自己修正参数后重新调用。这里有个细节错误信息里不要只写“参数错误”要写明“缺少字段user_id字段tags期望类型是数组实际收到字符串”。大模型对清晰错误信息的修正能力很强很多情况下一个来回就能自动解决。如果反复修正还是不行多半是技能的描述里没有写清楚参数格式。此时要在description里加一句更具体的说明比如“tags是一个字符串数组每一项是用户的标签内容”。这种提示比单纯的Schema定义对模型更友好。我甚至会建议在元数据里放一个parameter_examples字段把每个参数的合法示例都写出来这样能在根本上降低模型生成错误参数的概率。5.3 技能加载慢、内存占用高技能库条目多了以后进程启动时扫描全部元数据一般也就几十毫秒不至于有瓶颈。真正容易出问题的是有些人在注册中心里把每个技能的执行模块都在启动时就import这会拖慢启动速度还会占内存。我的建议是采用懒加载也就是真正执行一个技能时才import它。另外有些技能内部依赖一些体积较大的库比如PDF解析、图像识别如果十个技能都依赖同一个库加载器可以做一个模块复用的缓存池不要让每个技能重复挂一份同样的依赖对象。还有一个隐藏问题技能模块里的全局状态。如果某个技能在模块内定义了一个全局缓存字典多次执行之后内存会一直涨。排查时可以定期打印技能模块对象的数量如果发现同一个技能被加载了两份要检查import路径是否不一致。我之前就遇到过因为目录大小写不一致导致模块被重复加载的情况看起来是小问题实际会让内存占用翻倍。5.4 技能更新后老Agent却报错这个跟版本管理有关。技能库是共享的你更新了技能文件所有引用它的Agent都会受影响。有些Agent依赖旧版本的输出格式更新后自然就出问题。我目前的做法是每个Agent实例在初始化时记录自己依赖的技能版本集合注册中心提供一个按版本隔离的获取接口。元数据文件里加version字段同一份技能可以有多个版本目录共存比如meeting_summary_v1、meeting_summary_v2。发布新版本时不要删旧版本等所有Agent都迁移完成后再清理。这个流程看起来繁琐但能避免不少线上事故。另外技能测试文件应该跟技能同目录存放每次改动后跑一遍tests/cases.json里的用例确认输出Schema和示例数据都一致再考虑发布。我自己就因为偷懒跳过测试吃过亏那之后所有技能都强制要求附带至少三个输入输出用例。特别是涉及大模型输出的技能很容易出现结构不稳定只有靠固定用例回归才能保证升级安全。5.5 调试技能库的实用小工具最后分享一个调试技巧。我给技能库加了一个“单技能命令行执行器”可以直接在终端跑一个技能传参并查看输出不需要把整个Agent跑起来。python -m skill_runner run meeting_summary --transcript 会议内容...这个工具本质上就是注册中心的一个薄封装执行时传入技能ID和JSON参数最后格式化打印输出。这样调试效率会高很多尤其在排查某个技能单独报错的时候不用再动其他部分。我一度调试Agent链路要反复改Prompt和参数加上这个小工具后至少省了三分之一的时间。我建议每个团队做技能库的时候都顺手把这个工具加上成本很低日常收益却很大。做技术选型的时候我一直喜欢那些能在真实场景里扛住压力的方案而不是演示时看着炫酷的玩法。技能库这套架构在好几个生产级Agent里帮我扛过了流量压力也给后续扩展留了空间。如果你刚开始接触agent-skills不用急着把所有能力都封装成技能先从两三个高频业务动作入手把接口、描述、测试这三件事做扎实跑通之后再逐步扩充会比一开始就铺一个大而全的库稳妥得多。等你的技能库真正被多个Agent复用时你会发现之前在设计和规范上花的时间都是值得的。