先说个有意思的事。最近圈子里很多人在聊“agent-skills”这个词好像一夜之间做大模型应用的、做智能体平台的、甚至做RAG的都在往这个方向靠。我一开始以为又是哪个大佬提的新概念仔细扒了一圈才发现这不是什么新发明而是我们一直在做、但一直没做利索的一件事——把智能体的能力沉淀成可复用、可组合、可调度的“技能模块”。干过几年AI应用落地的人应该都有这种感觉模型能力越来越强但真正把一个Agent从“能聊”做到“能用”卡点根本不在模型本身而在于你怎么组织它调用的工具、你怎么让它在复杂任务里知道下一步该做什么、你怎么让一套能力从项目A平滑复用到项目B。这些问题本质上就是“技能”的问题。这篇博文我就拿自己做过的几个项目当例子把agent-skills这个方向的思路、拆法、工程实现和踩坑记录完整梳理一遍。不管你是刚开始搭Agent的新手还是已经在做智能体工程化的老手这篇应该都能给你一些能直接落地的参考。1. 先想清楚技能到底是什么和工具、工作流有什么区别很多人在聊Agent的时候工具Tools、技能Skills、工作流Workflow这几个词是混着用的。这其实是个认知陷阱。如果概念不清晰你做出来的所谓技能最后大概率会变成一坨既不像工具、又不像流程的四不像。1.1 工具、技能、工作流的分层逻辑我习惯用厨师做菜来打比方。工具是“刀”“锅”“铲”——它们是单一功能的原子操作比如“搜索网页”“调用某个API”“读取某个文件”“执行一段代码”。工具本身不关心你做什么菜它只提供一个确定的功能入口。技能是“切土豆丝”“颠勺”“调糖醋汁”——它是把若干工具按特定顺序和规则组合起来完成一个相对完整的、有明确产出的操作。技能是对工具的组织和封装它包含流程也包含这个场景下的经验。比如“搜索某个领域的论文并总结要点”就是一个技能它内部需要调用搜索工具、阅读工具、以及一个总结模型。工作流是“做一盘鱼香肉丝”——它把多个技能编排成一条完整的业务链路告诉Agent先做什么、再做什么、什么情况下走分支。工作流是面向最终任务目标的它关心的不是单个操作用什么技能而是整个任务的推进逻辑。用这套分层再去设计Agent系统你会发现很多之前混乱的地方瞬间清晰了工具层做能力的原子沉淀技能层做场景经验的封装工作流层做业务目标的编排。而“agent-skills”这个方向重点就是中间那一层——技能层。1.2 技能封装的核心价值把“经验”变成“资产”为什么要单独做技能层而不是在代码里写死流程、或者把所有逻辑都塞给模型让模型自由发挥这里有两个非常现实的动机。第一个动机是减少大模型的认知负担。大模型在上下文里同时处理“工具清单”“用户目标”“历史对话”“外部环境信息”四样东西很多时候会在工具选择上犯糊涂尤其是工具数量超过20个时选错工具的概率会明显上升。技能的作用是在工具之上做一层“粗粒度”的抽象让模型先决定“用什么技能”再由技能内部去决定“怎么用工具”。这就像你出门不需要记住每条街道的具体走法你只需要知道“我要去高铁站”然后导航帮你搞定具体路线。第二个动机是让经验和知识有地方沉淀。我见过太多项目Agent在很多情况下表现得不错但系统的能力完全散落在提示词和代码逻辑里。今天觉得这个场景处理得不好改一下提示词明天觉得那个场景需要加个判断改一下代码。结果三个月后整个系统变成了一锅粥没人敢动任何一块因为一动就坏。如果用技能封装每个技能是独立的、有版本可追踪的、有输入输出契约的系统的能力会像搭积木一样越积越多而不是越滚越乱。技能层本质上是把“写在系统里的能力逻辑”升级成“可持续积累的组织资产”。这也是我认为这个方向在未来两年内会成为Agent工程化标配的根本原因——但凡是做得比较深的Agent项目迟早都要过这一关。2. 上手拆解一个技能模块的标准结构长什么样我做了几个轮次的技能封装后自己总结了一套技能模块的推荐结构。它不一定适用于所有场景但可以作为你起步时的参考骨架先跑起来再根据实际需求调整。2.1 技能定义文件让Agent“知道有这个技能”技能定义文件是整个技能模块的门面。它的主要作用是告诉Agent你有哪些技能、每个技能是干什么的、什么情况下应该选它、调用它需要提供什么参数。很多人在设计这个文件时过于简单只写了技能名称和一句话描述这在技能数量多了以后检索准确率会明显下降。我推荐用结构化的方式来写技能定义至少包含以下字段名称name技能的标识符建议用“动词名词”的清晰结构避免歧义。描述description两到三句话说明技能的核心用途。在给大模型看的所有信息里描述可能是权重最高的部分它直接决定模型在匹配任务时能否命中这个技能所以要把适用的场景、输入要求都写清楚。适用场景when_to_use这个字段非常关键它要写清楚“什么情况下应该选我”和“什么情况下不应该选我”。我见过很多技能被错选就是因为没有写清楚边界。输入参数input_schema每个参数的名称、类型、必填与否、取值范围。这里可以直接借鉴OpenAPI的schema风格。示例examples给出一到两个这个技能被正确调用的输入输出示例。示例是帮助模型理解技能用法的最有效手段不要省略。举一个实际例子。我做过一个“网页内容深度提取”技能定义文件里描述部分写的是“从给定URL提取正文内容并去除导航、广告等噪声返回结构化文本”适用场景写的是“当用户给出一个网页链接并要求获取正文内容、或者需要基于某个网页内容做后续分析时使用”示例里给了一个典型的上游输入“请把https://example.com/article/123的内容总结一下”和对应的技能调用结构。有了这样的定义Agent在任务规划阶段能够明显更好地判断何时、以何种参数来调用这个技能。2.2 技能执行体真正干活的逻辑代码定义文件是“接口契约”执行体则是“内部实现”。同一个技能你可以用代码实现也可以用提示词实现更常见的做法是两者结合。纯代码实现的技能适合那些逻辑固定、不需要模型参与判断的操作。比如“从HTML中提取正文”“批量转换文件格式”“调用某个API并解析返回结果”。它的优点是稳定、快、不消耗模型token缺点是灵活度低遇到边界情况容易直接失败。纯提示词实现的技能适合那些“解读生成”类的操作。比如“总结一段对话的核心议题”“把技术文档改写成白话版”。它的优点是灵活能应对各种超预期输入缺点是耗token、耗时、结果有随机性。工程上更推荐的是一种混合结构技能执行体分两步走——先用代码做输入预处理和结果结构化再把中间环节交给提示词或模型来做判断和生成。举例来说“网页内容深度提取”技能我的实现方式是先抓取HTML、用解析库提取主要文本块再交给大模型进行段落精炼和重点标记。这样既保证了抓取环节的稳定又利用了模型的理解能力。这里顺便提一个很多新手会犯的错误他们把大量提示词塞进技能内部却没有设置好输入校验。如果你在代码入口不做参数范解析模型传了一个格式错误的参数技能直接崩掉而且外层没有捕获异常的话整个Agent会处于一种“既没完成用户请求、也没有给出错误提示”的尴尬状态。所以执行体的第一个步骤永远应该是“按schema校验输入参数”这个东西的成本极低但能规避大量低级故障。2.3 技能元信息描述和示例的编写技巧技能定义里的描述和示例值得你花时间认真打磨。这不是文案工作而是“面向模型的接口设计”工作是把这个技能“推销”给大模型的关键环节。写技能描述时我遵循几个硬规则描述里要有动词动词要具体。不要写“处理网页”要写“从HTML中提取正文”蓝图才清晰。要说清楚输入约束。比如“仅支持中文和英文页面其他语言的准确率会显著下降”这个信息能防止模型在错误场景下硬调用。示例不要只给一个正面例子最好给一个边界例子。比如“当提供的是PDF链接而非网页链接时本技能不适用应提示用户上传PDF后再处理”。描述不要超过一定长度太长了反而会稀释重点。我的经验是一般情况在80到150字之间即可保证信息密度高、模型容易抓取。关于示例还有一个细化技巧。示例有两种一种是在定义文件里给模型看的“调用示例”另一种是在测试阶段人工标注的“运行示例”。前者用于提高技能被正确调用的概率后者用于技能的回归测试。前者是给模型写的后者是给人看的别混在一起。2.4 一套可以照抄的技能目录组织规范当技能数量超过几十个时目录组织也在直接影响质量。我目前用的组织规则是一个技能一个目录目录名称与技能名称一致目录内部必须包含SKILL.md技能定义和run.py执行体核心逻辑两个核心文件其他辅助文件和资源可以放同目录下的子文件夹里。不做索引、不做全局清单需要什么技能按照既定规则动态加载来使用这种按目录组织的方式一来方便版本管理二来方便团队多人协作。每个技能目录就是一个最小可交付单元出问题时可以单独回滚几个目录之间互不干扰。3. 工程视角技能注册、检索与组合调度的关键技术点搞清楚了技能模块本身的结构下一步就是工程实现层面的关键机制。一个技能定义得再好如果它在运行时不能被正确检索和调用也只是一堆死文件。这一节聊聊我在技能调度机制上的一些方案。3.1 注册中心技能的“目录表”是怎么管理的技能不是散落在文件系统里就完事了运行时需要一个“注册中心”来登记和管理所有可用的技能。注册中心维护一份技能清单包含每个技能的ID、名称、定义路径、依赖列表、版本号、启用状态。实现上可以是一个数据库表也可以是一个内存对象初期用JSON文件就够了。但这里有一个值得注意的细节注册中心的数据必须是“运行时实际加载的技能”的唯一事实来源。也就是说如果你改了SDK里某目录下的技能文件但没有更新注册中心里的登记信息或者触发重新扫描运行时应该报错或者拒绝加载它。我吃过这个亏——有一次我迁移了一个技能目录的路径但配置文件里忘记改注册信息系统还在按老路径加载跑了两天都没发现一直加载的是旧的技能资源排查了半天才定位到问题。我建议的做法是启动时检查目录结构发现有变更自动刷新注册表没有变更则直接读取持久化缓存。既保证了灵活性又控制了启动开销。关于技能注册还涉及一个“启停控制”的问题。有些技能在特定环境比如缺少某些依赖库下无法运行这时候不应该让整个Agent因为某个异常技能而初始化失败。注册中心需要能标记技能状态加载失败的不应该影响其他技能的可用性。3.2 检索策略如何让Agent在几十个技能中选对当技能数量增长到一定规模后如何让大模型在生成计划时选到对的那个技能是一个非常现实的工程难题。最简单的方案是把所有技能定义拼在一起塞进Prompt里但技能一旦超过20个这种方法的效果会急剧下降——模型在大量定义中无法准确区分细微差别选择准确率下降、响应变慢、token开销急剧上升。我实践中比较有效的做法是“两段式检索”思路先粗筛、再精排。粗筛阶段用一个轻量策略从技能库里选出候选子集。这个阶段不追求极致的准确率目标是快速把数量从“几十”缩小到“五六个”。可以基于用户任务的关键词做文本匹配也可以基于一个小的embedding模型把技能描述和用户任务都做向量化后算相似度。精排阶段把筛选出来的几个候选技能的详细定义包含描述、适用场景、示例都放进Prompt里让Agent大模型在候选集合里做决策。这样既控制了上下文长度又保证了选择准确率。这里有一个容易被人忽略的经验粗筛阶段宁多勿少。因为精排阶段有模型兜底还能区分细微差别但如果粗筛阶段就已经漏掉了正确技能后面再聪明也没用。3.3 组合执行多个技能协作时的工作流设计如果说技能是“厨房里的半成品食材”那工作流就是“做一道菜的过程指令”。在一个复杂任务里Agent往往需要按序调用多个技能而且还存在依赖关系——第一个技能的输出是第二个技能的输入。我用过一个比较典型的组合例子做一个“行业研究报告速读”任务。流程是先调用“文档解析技能”把PDF转成结构化文本然后调用“关键数据提取技能”抽取出报告中的数据、图表标注和核心结论紧接着调用“术语解释技能”把报告里的专业词汇转成通俗解释最后通过“汇报生成技能”拼出一份速读材料。这个过程涉及四个技能的串联任何一个环节出问题都会影响最终交付。在做这种组合编排时有几点心得技能之间的数据接口要“松耦合”。每个技能的输入输出尽量使用通用结构比如纯文本、JSON对象不要和特定技能的实现细节绑定。要设计“失败降级”路径。比如“文档解析技能”失败了那就不能继续走提取环节而是回到Agent主循环让它根据失败原因决定是换一种解析方式还是直接告知用户。记录链路上下文。每一个技能执行完它的输出摘要要写回任务的上下文记录里这样后续技能和最终模型都能感知到“之前已经完成了哪些步骤”。3.4 上下文管理技能执行中的“内存”怎么管上下文管理是Agent技能编排里最容易被低估的环节。任务的原始输入、用户的历史对话、前序技能的输出、技能运行时的中间状态这四类信息交织在一起如果管理不当上下文很快就会乱。我的做法是给Agent任务维护一个统一的结构化记忆对象Memory不直接让每个技能去访问完整的原始对话链。技能在执行时只能从Memory里读取“授权给它的当前输入”和“必要的参考信息”然后再把它的产出结果写回Memory里供下游环节使用。这个设计在多个技能协作时能有效隔绝无关信息的干扰每个技能看到的数据边界清晰正确率会好不少。另外一个容易踩坑的地方是把大量上下文塞进技能的Prompt里会让技能执行时间变长、消耗变大。比如你要调用“关键数据提取技能”它只需要前一步解析出来的那一小段文本你就不必把用户的全部聊天历史都传进去。只有明确需要的上下文才传给技能这个原则能被严格执行的话你搭出来的Agent系统响应速度和精度都会有明显区别。4. 实操记录用“Agent技能框架”从零搭一个能用的小系统前面讲了不少理论和抽象概念这一节我们直接动手做一个“研究助手Agent”的简化版本把这个框架跑通。受篇幅限制这里只展示核心骨架但每一步都是真实可行的落地方式。4.1 定义研究助手的三个初始技能这个研究助手要能完成三个场景任务从网页提取正文、总结网页要点、把总结结果保存为Markdown文件。所以主目录下有skills文件夹里面会装web_content_extractor、content_summarizer、markdown_saver三个技能。web_content_extractor这个技能承载了上面提到的“网页内容深度提取”能力。它的SKILL.md里定义文件大概长这样name: web_content_extractor description: 从给定URL提取网页正文内容去除导航、广告等噪声返回精简后的文本。 when_to_use: 当用户提供网页链接并要求提取正文或获取页面核心内容时使用。不适合PDF、图片或需要登录的页面。 input_schema: url: type: string required: true description: 网页完整URL地址 examples: - input: https://example.com/news/2025/ai-agents output: 页面正文的纯文本内容Markdown格式它的执行体run.py是代码逻辑import requests from bs4 import BeautifulSoup def run(url: str) - dict: # 校验参数格式不合法直接抛异常外层统一捕获 if not url.startswith((http://, https://)): raise ValueError(finvalid url: {url}) headers {User-Agent: Mozilla/5.0} resp requests.get(url, headersheaders, timeout10) resp.raise_for_status() soup BeautifulSoup(resp.text, html.parser) # 清除脚本、样式、导航这类噪声剩下的才是正文 for tag in soup([script, style, nav, footer, aside]): tag.decompose() main_content soup.get_text(\n, stripTrue) # 做一次空白行合并避免文本碎片太多、过度割裂 cleaned_lines [line.strip() for line in main_content.splitlines() if line.strip()] result \n.join(cleaned_lines) return { content: result, url: url, chars: len(result) }这个技能的峰值就在这里了。真正干净的做法是让“内容抓取”这个动作不去掺杂复杂的语义理解只负责拿文本理解的事情交给后续的摘要技能。第二个技能content_summarizer负责总结。它内部是提示词驱动的核心是一个结构化提示summary_prompt 你是资深内容编辑请对输入文本进行结构化总结。 要求 - 提炼核心观点保留关键数据 - 按要点组织输出 - 控制在300字以内 - 使用中文输出 输入文本 {content} 第三个技能markdown_saver负责把内容保存到本地文件。它会校验文件名合法性、避免路径穿越等安全风险然后把内容写入output目录返回最终路径。4.2 调度器与主循环让模型决定下一步动作有了技能还需要一个调度器把它们串起来。这个调度器做两件事先用列表和检索找出候选技能再把候选技能的详细定义交给大模型做决策然后执行模型挑选的技能并返回结果。这里列一个极简的伪代码逻辑def agent_loop(user_input, skills): messages build_initial_messages(user_input, skill_candidates) for step in range(MAX_STEPS): # 模型决策选择一个技能并给出参数或直接给用户答复 action llm_call(messages, available_skill_namesskills.keys()) if action.type answer: return action.reply if action.type call_skill: skill skills[action.skill_name] result skill.run(**action.arguments) messages.append(record_skill_result(action, result)) # 超过最大步数需要强制终止防止无限循环 return 我在规定步数内未能完成这个任务抱歉。跑起来后你会发现整个系统的能力边界完全由技能决定技能库里有多少技能Agent能处理的任务类型就有多少。想扩展能力时新增一个技能目录就行不用改主循环。4.3 实测效果与关键参数调优记录我拿一篇2000字左右的科技类网页做了测试。用户输入是“提取这个网页的内容然后用三点总结它https://example.com”。第一个技能web_content_extractor抓取到正文约1800字抓取耗时约400毫秒。第二个技能content_summarizer在4000token温度0.3的设定下输出了一份三点摘要覆盖了原文的核心论点耗时约800毫秒。第三个技能markdown_saver把结果保存成文件整个过程在3秒内走完整个链路里的每步产出都有记录。在这个链路里有多个参数值得细调抓取超时如果设得太短比如3秒部分响应较慢但在正常的网站会直接失败如果太长比如30秒异常网站会卡住整个流程。10秒是我试下来最平衡的数值。摘要的温度摘要类任务建议把温度压在0.2到0.4之间输出会更稳定、更贴合原文。温度如果过高模型容易自由发挥摘要会“跑偏”。最大步数当前场景只要3步但复杂任务可能需要更多轮操作建议限制在6到8步给Agent留足操作空间也避免死循环烧token。从实测来看这个框架在小规模的单一场景下完全可用稳定性比“把所有能力都塞进一个大Prompt、让它自由发挥”明显好一截。核心变化在于每步的输入输出都是清晰的出问题时一眼就能定位到具体环节。5. 进阶经验技能复用、评测与持续迭代的实战方法如果只是做一个Demo前面的内容已经够用了。但如果你想把这套技能框架真正用在一个长期维护、持续增长的项目里有三个进阶问题你躲不掉技能多了之后怎么复用好怎么证明每个技能真管用怎么让技能越来越多、越来越准5.1 技能如何跨项目复用与迁移技能复用的一个现实场景是你在做“金融数据解析”项目时封装了一个“从财报中抽取关键指标”的技能下个月另一个“保险条款对比”项目也需要类似的抽取能力。如果你在设计技能时进行了模块化迁移成本其实很低只需要把技能目录复制过去再根据新场景调整下描述文件和示例即可。有几个可以提前为复用铺路的“逆向思维”设计技能内部不要写死和具体业务强相关的判定逻辑。比如金融项目里“筛选重点项目”的规则应该通过参数传进来而不是硬编码在技能内部。输入输出优先用通用结构。能用纯文本表达就不要用专门的对象类型能用JSON就不要用某个框架特有的序列化格式。技能描述里要写“依赖项清单”告诉使用者这个技能运行所需的第三方库、模型类型、版本要求。不然换个环境直接跑不起来你会被这个低级问题折腾得够呛。5.2 技能评测如何知道一个技能是“可用”还是“待优化”没有评测机制的技能体系就是一盘散沙。技能改没改坏、模型理解准不准、执行结果是否符合预期这些必须有一个量化手段不能凭感觉。我目前采用三层评测方法第一层是调用率评测即统计在测试集上“正确场景中該技能被正确调用的比例”。这个指标主要衡量的是技能定义的质量定义写得越清楚这个数越高。第二层是执行成功率评测即“技能执行过程中没有报错、正常返回结构化结果”的比例。这个指标主要衡量执行体的健壮程度它标明了你的代码在真实输入面前有多抗造。第三层是输出质量评测是对技能运行结果做人工或模型评价。比如摘要技能的输出是否抓住了重点提取技能的正文是否丢掉了关键段落。这一步建议定期抽样来做不需要每次全量跑因为它的成本相对较高。有这三层数据后一个技能的迭代就有了方向。定义不清导致调用率低就改描述和示例执行体脆弱导致成功率低就补异常处理和边界判断理解深度不够导致输出质量差就优化技能内部的提示词和流程设计。数据会告诉你问题在哪一层而不是让你瞎猜。5.3 技能持续迭代把线上反馈变成改进素材技能是个活的东西不是写一版就能躺平。持续迭代的核心是要把线上真实使用中的反馈转化成改进某个具体技能的依据形成一个“使用→记录→复盘→改进→上线”的闭环。我建议至少做两点沉淀第一点是在技能内部做好状态日志。每次技能调用都记录输入摘要、输出摘要、执行耗时、是否成功、失败原因。这些日志不一定要实时分析但它是复盘时的第一手证据。没有日志的技能出了问题完全靠猜这很要命。第二点是建立一个技能“问题-修订”清单。当发现某个技能的某些场景表现不稳时把它记录下来。比如“当用户提供中文PDF时提取结果乱码”——这个问题很可能不是技能本身的问题而是依赖的解析库对中文PDF的支持不足。有了清单后续做针对性优化时可以精准定位。5.4 边界处理技能能力之外要有兜底方案最后再提一个我觉得做Agent工程化最容易被忽视的点技能的边界处理。每个技能都有它能干和不能干的事但用户不会按技能边界来提问。所以技能系统一定要有一个“兜底方案”当所有技能都无法处理用户请求时系统要能优雅地“承认自己不行”而不是硬来。这里区分两种情况一种是合理但不支持的情况比如技能库里有“网页解析”但用户要解析的是需要登录的页面这时候系统应该明确告诉用户缺少什么条件或者提供替代路径比如请用户粘贴文本另一种是用户输入本身就有问题的情况比如用户给了一个损坏的文件这时系统应该引导用户更换输入而不是报一个不友好的异常。兜底方案说到底是设计者对这个系统预期的一种诚实表达。Agent不是万能的敢于承认“这个场景还不在能力范围内”往往比硬着头皮给一个错误结果更能维护系统的可信度。一个成熟的项目里兜底逻辑通常会链接到一个“问题收集”机制当用户提出超出当前技能集的问题时可以记录下来作为后续新增技能或迭代技能的依据。这样兜底也就不再只是“失败处理”反而成了系统演进和技能扩展的输入。写在最后agent-skills这个方向说到底就是把智能体的能力从“写到代码里”变成“沉淀成资产”。我真正上手做之后最大的一个感受是它不是一个单一的技术方案而是一种组织智能体能力的思维方式。它把复杂的Agent系统拆成了一个个边界清晰、可独立演进、可组合复用的模块让系统的能力增长不再是“越改越乱”而是“越积越厚”。如果你现在正卡在“Agent逻辑全写在Prompt里、一团乱麻”的阶段我的建议是别急着重构整个系统先挑两个高频场景把它们封装成技能模块感受一下这种“技术分工”的变化。等你把第一个技能跑通、评测、迭代一轮之后再回头看大概就能理解为什么这个方向这么被看重了。