agent-skills：把智能体能力沉淀为可复用、可编排的技能库-北京尧图网络

agent-skills把智能体能干的活沉淀成一套可复用、可编排的技能库做Agent项目时间长了你会发现一个挺扎心的规律单看一个智能体的Demo跑通并不难难的是让它稳定地干很多不同类型的活。今天聊的这个项目“agent-skills”本质上是给智能体装一套“技能管理框架”让LLM不只会聊聊天还能按步骤、按规则去调用工具、执行流程、处理数据并且这些能力可以被长期复用、灵活组合。这篇文章我会结合自己的实践经验把技能体系的设计思路、定义规范、编排方式以及我把一个技能从零落地跑通的全过程拆开来讲顺便把容易踩的坑一并列出来。先说清楚它能解决什么问题。假设你想让智能体帮你做“整理收藏夹里的网页并生成摘要”这件事没有技能体系的时候你得在系统提示词里写一大堆逻辑模型记住了就执行记不住就失灵换个场景又得重写。有了技能体系之后“抓取网页”是一个技能“提取正文”是一个技能“生成摘要”又是一个技能智能体只需要知道自己“有哪些技能可选”然后按需组合调用每个技能本身是独立的、可测试的、可替换的。这套思路适合谁适合正在做Agent应用开发的工程师也适合想把LLM接入实际工作流的同学哪怕你之前只是调过API也能从中得到不少可落地的设计参考。1. 先想清楚agent-skills到底解决什么问题1.1 为什么Agent需要一个独立的技能层现在的LLM本身很强能理解复杂指令能生成自然语言但它有两个天生的短板一是不知道外部世界发生了什么二是不能保证每次推理都按固定的可靠路径执行。如果你只是问它“你觉得明天的天气怎么样”它只能靠编。如果你让它“调用天气接口查一下明天的气温”它需要有工具、需要知道工具怎么用、需要把工具返回的数据整理成答案。技能层就是解决这个问题的中间件。我在早期做Agent的时候犯过这样的错误把所有工具说明一股脑塞进System Prompt让模型自己决定用什么。小规模时还能跑技能一旦超过五六个模型就会出现“选择困难”——要么频繁调错工具要么明明该调用却直接凭记忆编答案。后来我把工具调用改成了“技能注册按需加载”的方式情况立刻不一样了。核心区别在于智能体不需要同时看到所有技能它只需要在“当前任务需要什么能力”时能看到匹配的技能描述并触发对应执行器。这个思路和微服务很像每个技能是一个独立的小服务Agent是一个编排层负责理解意图、拆解任务、调用合适的技能。1.2 技能体系的核心构成要素一个完整的技能体系从数据流角度看包含四部分技能注册中心、技能描述索引、技能执行器、技能运行时上下文。技能注册中心就是技能的“户口本”记录每个技能的唯一标识、版本号、作用范围、依赖关系。技能描述索引是给LLM看的目录它不包含具体代码而是包含“这个技能什么时候该用、能干什么、参数长什么样”LLM靠这个索引做判断。技能执行器是真正干活的代码它接收结构化参数执行实际操作比如发HTTP请求、处理文件、更新数据库。技能运行时上下文则负责在执行过程中保存状态让多个技能可以接力干活。这四个要素缺一不可。只做注册和执行LLM找不到技能只做索引和执行技能之间无法共享数据没有注册中心版本一多就乱套。把这个体系先搭明白后面做任何Agent应用都踏实。1.3 技能设计和普通函数设计有什么不同很多人刚接触技能体系时会问这不就是封装函数吗我写个Python函数不就行了其实差别很大。普通函数的调用者是程序员程序员会读文档、会调试、会按约定传参。技能的调用者是LLM它没有“调试”的耐心也不会严格按你脑子里的约定来传参。你写一个函数fetch_url(url, timeout10)人类队友知道timeout可以省略LLM却可能传一个timeout很快进来。所以技能设计要做的第一件事就是“面向LLM编程”。参数定义必须用JSON Schema这种机器可读的结构而不是函数签名。技能描述必须写得像“给一个聪明但没经验的实习生看的操作手册”不能指望它有上下文联想能力。同时还要考虑一件事技能执行大概率会失败执行器必须有完善的错误返回机制把失败原因整理成LLM能理解的文本而不是抛出一个Python异常就完事。这也是agent-skills这类项目真正要解决的痛点不是让代码多优雅而是让LLM这套“不太可靠的调度系统”能可靠地使用你的代码。2. 技能的精确定义从描述文本到参数结构2.1 技能的唯一标识与注册机制技能不能只有名字得有一个完整的注册记录。我习惯用这样的结构来定义一条技能元信息字段示例值说明skill_idweb_archive_capture全局唯一标识建议用下划线命名name网页内容归档人类可读的名字用于界面展示description抓取指定URL的正文内容保存为Markdown文件并返回文件路径与字符数给LLM看的描述决定它会不会选这个技能version1.2.0语义化版本号方便回滚与兼容处理authorteam_archiver维护者标识tags[web, archive, crawler]标签用于技能检索分组parametersJSON Schema对象描述调用参数的结构注册机制上建议把元信息集中放在一个目录里每个技能一个子目录目录内包含skill.yaml或JSON描述文件与executor.py执行器代码。加载时统一读取并建立索引。这样做最大的好处是版本管理简单——每个技能子目录本身就是一个独立模块进Git仓库天然支持code review、diff和回滚。我有一个实际体会不要把所有技能写进一个大文件里哪怕初期只有三五个技能统一注册和独立目录也能省不少事因为技能的迭代频率往往比你想象的高。2.2 技能描述文本决定LLM会不会用错描述文本是整个技能体系里投入产出比最高的部分。很多项目技能执行代码写得没问题但模型就是不会在正确的时机调用它十有八九是描述没写对。描述的核心要求可以浓缩成三句话说明触发场景、说明能力边界、说明关键参数注意事项。举例来说“网页内容归档”这个技能好的描述是当需要把网页正文保存为文档、或者需要提取网页中的核心文字内容时使用。本技能可以抓取公开网页的正文自动去除导航、广告、页脚等干扰元素并输出为Markdown格式。不可用于需要登录的页面、不可用于下载音视频文件。这段描述里包含了触发信号“保存为文档”“提取核心文字”、边界不可用于登录页和音视频以及输出格式Markdown。模型看完之后不仅能判断“该不该用”还能知道“用了之后会得到什么”这对多技能组合推理非常重要。再对比一个糟糕的描述抓网页工具参数有url和filename。这种描述太笼统模型不知道什么时候用也不知道输出格式结果就是该用的时候不用不该用的时候乱用。我的经验是一段描述写完后自己读一遍假想自己是个完全没看过代码的人能不能根据描述判断触发条件。如果不能那就重写。2.3 参数Schema既要结构化也要容错技能参数建议统一用JSON Schema定义这样好处有两个一是可以校验参数完整性二是在把自然语言转成结构化参数时模型有一个明确的输出模板可以参考不容易瞎编。以网页归档技能为例{ type: object, properties: { url: { type: string, format: uri, description: 需要抓取的完整网页地址包含协议头例如 https://example.com/page }, include_images: { type: boolean, description: 是否在归档文件中保留图片引用默认关闭, default: false }, output_name: { type: string, description: 归档文件名称不含扩展名默认根据页面标题自动生成 } }, required: [url] }注意几个细节。第一每个参数都要有description而且description里要给出例子和格式要求因为LLM很可能把example.com/page这种缺协议头的地址传进来描述里写明“包含协议头”能明显降低这类错误。第二required数组只放真正不能缺的字段其他字段给默认值这样即使模型少传参数执行器也能正常工作。第三不要在Schema里写过于严格的枚举限制除非业务上确实只有这几个选择否则会限制模型判断的空间。参数的容错比校验更重要。我的处理方式是执行器内部再做一层归一化清洗比如URL自动补全协议头、文件名去掉非法字符、布尔值接受字符串true/false。这相当于在LLM和真实代码之间加了一个适配层。LLM是个很不稳定的调用者你不能指望它每次都能输出完全合法的JSON适配层的存在可以避免大量无谓的失败重试。3. 技能编排让多个技能协同工作3.1 串行流程明确技能的输入输出契约单个技能完成了“点”上的能力真正让Agent变强的是“线”上的编排。比如“归档网页并生成摘要”这个完整任务至少需要三个技能协作抓取网页 → 提取正文 → 调大模型生成摘要。这里有一个关键点每个技能的输出必须可预测、有结构才能作为下一个技能的输入。我在设计技能输出时统一规定每个执行器返回一个状态对象包含以下字段{ status: success, output: { file_path: /data/archives/xxx.md, char_count: 5300 }, log: [页面抓取完成耗时1.2秒, 正文提取完成去除链接45个] }status字段只有两个取值success或failed绝不让执行器有第三种模糊状态。output永远是JSON对象即使只有一个返回值也要包一层。log是给人看的执行痕迹调试和LLM回答用户问题时都用得上。串行编排时Agent需要读上一个技能返回的output提取出下一个技能需要的参数。这个过程如果让LLM自己做容易出现来回试探、传参失误。我的做法是在编排器中固化一些常见模式比如“上一个output的某个字段映射到下一个技能参数的同名字段”只有遇到无法自动映射的情况才让LLM介入。能用代码解决的就不要消耗模型的推理次数。3.2 分支路由与并行执行技能编排不只有串行。实际任务里经常需要根据条件走不同分支比如“如果网页是技术文档就走长文摘要流程如果是新闻就走短讯简报流程”。在技能体系中这个判断可以由Agent决策也可以由编排器规则触发。我更推荐后者的变体Agent先做一次意图判断返回一个结构化的路由结果例如{route: tech_doc}然后由编排器按照预定义的路由表把任务分派到对应技能链路上。并行执行也很有价值。比如做竞品分析时需要同时抓取多个网页如果串行执行耗时是叠加的如果技能框架支持并行调用多个技能实例可以并发运行总耗时只取决于最慢的那个。并行需要注意一点技能执行器必须是线程安全或进程隔离的不能有共享的可变全局状态。我在设计技能执行器时要求每个技能实例都是无状态函数加独立上下文的模式同一个技能可以被并发实例化多次互不干扰。3.3 执行防护超时、重试、熔断与幂等技能编排中最容易被忽略的是防护机制。LLM调用技能不会像人一样有耐心如果某个技能执行时间太长用户早就走了。所以每个技能都强制配置超时上限默认30秒超过就立即返回failed状态并附上“执行超时”的错误日志。重试策略要区别对待幂等操作比如抓取公开网页可以自动重试一次非幂等操作比如创建订单、发送消息绝不自动重试必须由用户确认后再触发。熔断机制同样重要。我遇到过这种情况某个技能本身有Bug在资源不足时会崩溃但Agent不知道还会反复调用它结果每次都失败白白浪费时间。后来给技能执行器加了一层熔断器如果一个技能连续失败达到阈值比如3次在接下来的时间窗口内不再被调度Agent会收到提示“该技能暂时不可用”转向其他方案或直接向用户说明。这是从微服务治理里借鉴的思路搬到技能体系里同样适用。幂等性是一个看起来隐性但特别重要的要求。以网页归档技能为例最自然的实现是“先抓网页再写文件”。但如果网络抓取成功、写文件失败重试时就会重复抓取。有些页面有访问计数重复抓取会产生副作用。应对方法是给每个任务生成一个trace_id技能执行时先检查trace_id对应的产物是否已存在存在就直接返回上次的结果不再重复执行。这样重试变得安全Agent调度逻辑也能简化不少。3.4 技能版本与回滚策略技能会不断迭代但Agent正在跑的任务不能因为技能升级而中断。我在技能注册中心里支持多版本共存每个技能记录当前版本和可用版本列表编排器调度时默认使用当前稳定版本如果出问题可以快速把版本号切回上一个稳定版。版本策略上遵守一个简单原则兼容性变化升大版本号比如1.x升2.x新增参数或非破坏性修改升小版本号1.1升1.2。执行器之间通过版本的deprecated标记来通知后续淘汰计划。这里也踩过坑最初我没有版本概念一个技能改了参数结构导致所有依赖它的旧流程全部报错从那以后我要求所有技能上线时都要声明一个基础测试用例集每次版本变更都跑一遍回归测试确保“改坏了能及时发现”。4. 实操案例从空白工程到可运行技能4.1 第一步定义“网页归档摘要”技能链我挑一个实际跑通的例子来讲建一个“网页内容归档并生成摘要”的能力。这里强调一下它不是单一技能而是一组技能链但一开始我们把它拆成两个独立技能来注册web_capture负责抓取和正文提取summary_generate负责调用LLM生成摘要。先建目录结构skills/ web_capture/ skill.yaml executor.py summary_generate/ skill.yaml executor.pyweb_capture/skill.yaml里定义前面说的元信息和参数Schema。summary_generate/skill.yaml里定义模型相关参数比如model_name、max_length、language。Catalog加载器启动时会扫描这个目录把每个技能的描述和参数Schema注册进索引。这样Agent运行时能看到两张“卡片”每张卡片都写清楚了触发条件和调用方式。4.2 第二步实现执行器并注册进技能仓库以web_capture为例核心执行逻辑分三步发起下载、清洗HTML、保存Markdown。下载部分用标准库加第三方HTTP库实现超时设置成15秒。清洗HTML时我直接用内容提取算法定位正文节点而不是粗暴地去掉所有标签——后者会把导航栏文字也留下来摘要质量会很差。一个简化但能跑通的核心执行器骨架如下class WebCaptureExecutor: def execute(self, params: dict, context: dict) - dict: url normalize_url(params.get(url, )) if not url: return self._error(缺少有效URL参数) html fetch_with_retry(url, timeout15, max_retries2) if html is None: return self._error(页面抓取失败请确认网址可公开访问) markdown extract_readable_content(html) file_path save_markdown(markdown, output_nameparams.get(output_name)) return { status: success, output: { file_path: file_path, char_count: len(markdown), title: extract_title(html) }, log: [ fURL抓取完成状态码200, f正文提取完成有效字符数{len(markdown)}, f已保存到{file_path} ] } def _error(self, message: str) - dict: return {status: failed, output: {}, log: [message], error: message}写执行器时的要求是所有外部依赖调用都要包在错误处理里任何一步失败都要生成上下文可理解的错误信息。_error返回的message非常重要因为Agent看到失败后会基于这段文字决定下一步怎么做如果只返回“Exception: timeout”模型会一脸茫然不知道是网址错了还是网络坏了。实现完之后把技能信息注册进仓库这一步通常不需要手写SQL或服务端逻辑用一段脚本扫描技能目录把所有描述构建成一张索引表输出为JSON文件启动时一次性加载到内存。索引构建完成后我习惯先手工打印一遍所有的技能描述快速扫一眼有没有格式错误、内容冗余或者互相矛盾的地方。4.3 第三步Agent如何感知并调用技能Agent这一侧的调用链路设计我总结为三步感知、决策、执行反馈。感知阶段Agent从用户描述里提取出意图然后在技能索引里检索最相关的技能卡片。这一步可以直接用向量检索也可以简单地让LLM在少量候选里做选择。我倾向于混合策略先用关键词粗筛缩小候选范围再让LLM从候选中选出最合适的一个因为直接把所有技能描述全塞给LLM的话token开销太大且容易互相干扰。决策阶段LLM根据技能卡片的参数Schema把用户描述里的信息映射成结构化参数。这一步同样不建议让LLM自由发挥应该把参数Schema转换成“填空模板”让模型只负责填值不做任何字段增删。执行反馈阶段Agent拿到执行器的返回结果后需要把output和log整理成用户可读的答案同时保留结构化的内部状态方便后续技能链继续调用。我见过不少实现里把执行日志直接丢给用户看体验很差。正确的做法是日志里的事交给日志系统给用户看的必须是清晰、完整、不暴露内部细节的答复。4.4 第四步给技能链加上编排配置单个技能能跑之后我一般会立即做编排层的配置。比如把web_capture和summary_generate串起来用一份简单的纯声明式配置描述流程chain_id: quick_summarize steps: - skill: web_capture output_mapping: file_path: captured_file - skill: summary_generate input_mapping: source_file: captured_file language: zh这份配置的核心是映射关系。web_capture执行后output.file_path被存进上下文变量captured_file接着summary_generate从上下文里读captured_file作为它的输入参数source_file。这样两个技能就打通了而且整个流程是声明式的不依赖LLM在每一步都做规划执行起来稳定得多。做完这套配置后我还会补充一条“分支兜底”规则如果web_capture失败不再走摘要技能而是直接返回失败说明并给出可能的原因和替代建议。这避免了Agent在失败场景下反复重试同一个注定失败的链条。5. 常见问题与排查心得5.1 问题速查表技能体系跑起来之后我在实际维护和调试中积累了一份问题速查表每次Agent表现异常我先对照这张表排查大多数情况能在几分钟内定位问题。现象可能原因排查方法解决方案模型不调用技能直接编答案技能描述触发场景模糊或技能索引未包含该技能打印Agent感知到的技能列表确认卡片是否被加载重写描述明确触发信号模型调用了错误的技能多个技能描述重叠度高检查技能卡片之间的语义距离改写描述让每个技能边界更清晰参数传错或缺失参数Schema描述不明确查看LLM生成的中间参数JSON在description中给出格式例子和默认值执行失败但模型反复重试错误信息太笼统查看执行器返回的error字段在错误信息中补充原因分类和修复建议技能执行成功但结果质量差技能内部实现粗糙单独调用执行器查看输出优化核心处理逻辑比如正文提取规则多技能并行时互相干扰执行器内部有共享可变状态压测并发场景复现重构执行器为无状态模式这里面的原理其实都一样LLM调度技能时本质是在做“基于上下文的信息匹配”。它看到的描述越清晰、参数样例越明确、失败信息越有指导性调度的准确率就越高。反过来如果所有信息都模糊模型只能靠猜结果自然不稳定。5.2 我对“技能边界”这件事的经验技能设计里最容易被忽略的是“边界意识”。所谓边界就是明确这个技能管什么、不管什么。我在实践中学到一个判断标准如果某个技能描述里出现了“特别地”“除非”“在……情况下”这类条件状语超过两个说明这个技能的边界可能有麻烦。举例来说早前我设计过一个“文档处理”技能想让它既能转换格式、又能提取表格、又能OCR识别图片文字。描述写完以后发现特别长而且LLM经常在单纯转换格式时把OCR也做一遍白白浪费时间。后来我把这个技能拆成三个独立技能doc_convert、table_extract、ocr_text。每个技能都很纯粹描述也短调用准确率反而提升了。这个例子说明一个事情技能拆分不是越细越好而是每个技能都应当对应一个“清晰可描述、边界不重叠”的能力单元。当然也不能拆得过于碎片。如果把“抓取网页”和“提取正文”完全分开会让LLM多了一步决策这个决策本身没有收益。所以我的拆分原则是一个技能应该完成一个完整且独立的业务动作这个动作的输入输出都可以被模板化描述。比如“抓取并清洗网页内容”就是一个完整动作“HTML转Markdown”不是因为后者几乎不会单独被用户需求触发。5.3 实测验证思路不只看单次成功率技能体系建完之后我强烈建议建一个回归测试集里面收录的是真实用户问题而不是给模型预演过的问题这样才能真正反应效果。测试集不需要很大但需要覆盖正常场景、边界场景、异常场景三个纬度。以web_capture为例正常场景是“抓取一个公开技术博客正文”边界场景包括“网址缺少协议头”“网址对应的是一个404页面”“网页内容是PDF而不是HTML”异常场景包括“目标页面需要登录”“目标域名DNS解析失败”“抓取超时”。对每个场景我都会记录三个指标技能选择是否准确、参数构造是否一次通过、执行结果是否符合预期。跑完测试后常见的失败集中在两类一类是描述文本写得含糊导致模型选错技能另一类是参数Schema约束太松让模型传入了无法处理的值。把这些失败案例积累下来反过来迭代技能描述和参数Schema比盲目调Prompt或换大模型版本都有效。这个思路也算是我在agent-skills项目里收获最大的一点不要试图让模型更聪明要让技能体系本身更好用。5.4 技能可观测性日志和追踪的价值最后想聊聊运维侧的事情。技能体系如果做得比较成熟一定会有大量技能调用这时候没有可观测性几乎是寸步难行。我给每个技能调用配备一条结构化日志包含trace_id、技能ID、版本号、入参摘要、返回状态、耗时、错误信息。无论线上出了什么问题先按trace_id把整条调用链捞出来再对照每个环节的耗时和状态逐步排查效率会很高。这里有一个日常容易忽略的小细节log字段不一定非要给人看但一定会被Agent在下一轮决策时读取。所以写入log的内容既要简洁又要包含可行动的信息。比如不要写CrawlTimeoutException at M1.9, function create_connection, 而要写页面抓取超时已重试两次仍失败请检查目标站点是否可访问或换用其他来源链接。同样一件事面向人类运维和面向LLM决策的表达方式是完全不同的这一点做技能框架的同学越早意识到越好。每次技能执行结束之后我还会把调用结果统计回传到注册中心形成一个轻量的调用热力图。哪些技能被频繁调用、哪些技能几乎没人用后期做技能淘汰和优化就有了数据依据。比如某个月发现某个技能连一次都没被触发说明它的描述可能一直没匹配上真实需求这时候要考虑的是重写卡片而不是删掉功能。实际做下来我对技能体系最大的体会是Agent的智能不只在模型参数里更大程度上取决于你给它编排了多少高质量、边界清晰、可观测的技能模块。agent-skills这套思维真正改变了我搭建Agent应用的方式——从“反复调教模型”变成“沉淀能力组件”。每个技能就像一颗独立的螺丝钉框架负责把它们组装成可靠的机器。你不用贪多求快先把两三个核心技能的边界定义清楚跑通一条技能链再慢慢扩展你会发现模型的可靠性和任务完成度都上了一个台阶。

agent-skills：把智能体能力沉淀为可复用、可编排的技能库

相关推荐

IntelliJ IDEA Git 深度指南：从状态映射到上下文感知的工程实践

交通信号灯识别数据集：三种标注格式与82.88% mAP复现

股票期权适当性考试考点拆解：先建立风险边界再谈开户

更多资讯

Hadoop高可用集群搭建实战：NameNode HA配置、启动流程与故障排查

企业AI Agent可视化配置界面设计与落地实践指南

SSRF漏洞原理与实战：从内网探测到云元数据获取

Java基础：Object与String的底层原理与高频陷阱解析

Python与PyQt6实现Windows移动硬盘安全弹出工具

LNMP一键安装包后门检测与应急清理实战指南

今日更新

微信云开发旅游小程序实战：LBS打卡+UGC社交全栈方案

金融AI代理平台核心拆解：从多代理协作到财报分析实战

基于大数据的智慧旅游推荐与可视化平台架构实践

本周精选

金融AI落地指南：从调研报告到技术选型与工程实践

大模型上下文成本与注意力优化技术深度解析——为何O(n²)平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测

基于GMM的语音识别系统原理与MATLAB实现详解

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？