1. 从“会聊天”到“会干活”Agent技能到底是什么1.1 一次失败的多轮对话给我的教训前阵子我搭了一个所谓“全能助手”Agent接了大模型API配了搜索、计算、日历三个工具信心满满让它帮我安排一场带调研的会议。结果它把会议时间算错了搜索出来的资料直接原样甩给我最后还补了一句“建议您再核对一下”。那一刻我意识到工具多不等于会干活模型知道“有哪些工具”也不等于知道“该怎么用工具完成任务”。很多人把Agent理解为“模型工具”这个框架没错但太粗了。真正让Agent从“会聊天”变成“会干活”的是中间那层被大多数人忽略的东西——技能。我后来把所有工具调用、任务拆解、结果处理都重构成一套独立的技能体系也就是今天要聊的 agent-skills 项目。这套体系解决的核心问题只有一个如何让模型像熟手员工一样按标准动作把一件事做完。所谓“技能”不是某个API函数也不是一句提示词而是一组“完成某类任务的标准操作流程 触达外部世界的能力 中间状态的记忆规则”。 它介于模型和工具之间既告诉模型“做什么”也告诉它“怎么做”还给了一些可编程的钩子让开发者能在关键节点干预结果。没有这层模型每次执行任务都是一次自由发挥结果好坏全看运气。1.2 技能Skill的定义与边界在 agent-skills 里我给技能下了一个非常朴素的定义技能是“输入—处理—输出”的封闭单元且单元内部必须包含模型可执行的判断逻辑。具体来说一个技能至少包含三部分技能说明书描述这个技能干什么、什么时候用、执行脚本模型需要遵循的步骤提示或代码逻辑、参数契约输入输出的字段定义和校验规则。边界感很重要。很多人把技能设计成“万能大杂烩”一个技能里既查天气又写周报还订外卖结果模型在选择技能时完全懵掉。我的建议是技能粒度尽量细一个技能只解决一类原子任务。比如“搜索并摘要网页内容”是一个技能“根据摘要生成周报”是另一个技能两者通过Agent编排层组合而不是揉在一起。细分之后技能的可复用性和可测试性都会大幅提升。另外要区分“技能”和“策略”。技能解决的是“怎么做一件事”策略解决的是“先做哪件事再做哪件事”。agent-skills 项目里技能是独立单元策略放在编排层。很多项目失败就是把策略写死在技能里导致技能换个场景就没法用。1.3 Agent Skills与工具Tools、插件Plugin的区别我见过大量文章把这三者混为一谈但在实际工程里它们是三个完全不同层次的东西。工具Tool最底层的原子能力比如“执行SQL查询”“调用某个HTTP接口”“读写某个文件”。工具没有智能它只提供能力接口不知道什么时候该被调。技能Skill把工具按业务目标包装成“可被模型理解的任务单元”。技能内部可以包含多个工具调用、判断分支、异常处理。例如“根据关键词搜索并整理结论”这个技能底层会调用搜索工具、网页解析工具、文本摘要模型但对外暴露的只有一个“搜索并总结”入口。插件Plugin是技能的打包分发形态。一套插件里往往包含多个技能、配置文件和依赖声明方便在不同Agent框架里复用。打个比方工具是厨师手里的刀、锅、铲技能是一道菜的完整做法包括备菜、火候、调味、装盘插件是一本菜谱收录了多道菜还写明了需要什么灶具。Agent本身是那个掌勺的厨师它按客人的点单任务翻菜谱选择技能用刀铲调用工具把菜做出来。搞清这个层级之后agent-skills 的目录结构就非常清晰了agent-skills/ skills/ web_research/ SKILL.md # 技能说明书 run.py # 执行脚本/核心逻辑 schema.json # 参数契约 requirements.txt meeting_scheduler/ SKILL.md run.py schema.json core/ registry.py # 技能注册与发现 router.py # 技能路由与选择策略 context.py # 上下文状态管理2. agent-skills项目设计技能库的整体架构与拆解思路2.1 为什么需要一套独立技能层先说说我踩过的一个坑。早期版本里我把技能提示词直接拼进系统Prompt几十个技能塞进去之后模型开始“精神分裂”既想调用搜索又突然写起了代码甚至把两个技能混在一起执行。后来我把技能全部抽离到独立层让模型先通过一个轻量级路由器选择技能再进入技能内部执行问题立刻减少了一大半。独立技能层带来的三个直接好处第一上下文瘦身。系统Prompt里不再塞全部技能说明只塞“技能清单索引”完整说明书按需加载省下大量token。第二可观测性。每个技能都有独立入口和出口可以单独打日志、设置超时、做单元测试。第三可编排性。技能成为独立模块编排层可以像拼积木一样组合它们甚至允许用户自己写新技能注册进来。agent-skills 的架构并不复杂核心就三个模块注册中心Registry、路由器Router、上下文管理器Context Manager。注册中心持有所有技能元数据路由器根据当前任务和技能索引做匹配上下文管理器负责在技能之间传递数据并记录执行历史。这三块搞明白整个技能库就立住了。2.2 技能描述Skill Description的配置规范一个技能能不能被模型准确调用80%取决于技能说明书写得清不清楚。我把 SKILL.md 的写法总结成“四段式”What技能做什么、When什么场景触发、How执行步骤概要、Limits边界和禁忌。下面是我们项目里“web_research”技能的 SKILL.md 核心内容# 技能名称 web_research ## What 根据用户给定的研究主题自动搜索多个来源生成一份带引用的结构化研究摘要。 ## When - 用户需要了解某个主题的最新信息 - 用户要求“查一下”“调研一下”“整理资料” - 任务需要引用外部实时数据 ## How 1. 解析主题提取2-3个核心关键词 2. 调用搜索工具获取排名前10的结果 3. 对每个结果执行内容抓取剔除广告和无关页 4. 按“摘要—关键发现—引用来源”结构输出 5. 所有结论必须附带来源URL禁止编造 ## Limits - 不做深度分析只做信息整合 - 不处理需要登录/验证码的页面 - 不返回超过5条核心结论注意“Limits”这一项很多博主不会强调。它实际上是在给模型划定安全边界防止技能被滥用或输出不可控。比如一个“文件删除”技能如果不在限制里写明“仅允许删除/tmp目录下的文件”模型被恶意提示词诱导后可能会指哪删哪。2.3 技能注册与路由让模型知道“什么时候该用哪个技能”技能写好后需要注册进Registry。每个技能注册时除了加载SKILL.md还要带上一个“embedding向量”或“关键词标签”供路由器做语义匹配。我测试过的方案里轻量级做法是用关键词标签加简单评分复杂一点的做法是用embeddings做余弦相似度检索。对于十几个技能量级前者就够了。路由器的核心逻辑是先粗筛再精排最后确认。粗筛阶段根据任务文本和技能标签做关键词匹配筛掉明显不相关的精排阶段把剩余技能的SKILL.md标题和描述拼成候选列表让模型从中选一个或几个确认阶段用一次独立的模型调用判断“当前技能是否真的适用”避免误选。这里有一个非常重要的实操经验不要让主Agent直接执行技能而是让路由器只输出技能ID和参数然后由调度器执行。这就像公司里老板只负责任务分派具体活由员工干老板不需要自己也写代码。我最初就让Agent同时干“选技能”和“跑技能”两件事结果它经常在选完技能后忘记调用或者自己脑补执行结果。改成“选择与执行分离”后成功率显著提高。3. 核心技能实现与实操三类高频技能从零搭建3.1 信息检索类技能RAG搜索与网页抓取信息检索是Agent最常用的技能类型没有之一。我在 agent-skills 里封装了一套“search_and_summarize”技能底层逻辑是“搜索→抓取→清洗→摘要”。这里最容易被忽略的是抓取阶段的正文提取。很多人直接用requests拿HTML然后把一堆标签塞给模型既费token又容易让模型被导航栏干扰。我用的方案是先用 Trafilatura 或 Readability 这类正文抽取库把HTML转成纯文本再做一段长度截断比如每页最多保留3000字符最后拼接多个来源的正文交给模型。实操中这套流程的效果远好于直接丢链接。伪代码长这样def run(query: str, num_sources: int 3) - dict: urls search_api.search(query, top_k10) docs [] for url in urls[:num_sources]: html http_client.get(url, timeout8) text read_quality.extract(html) # 正文抽取 docs.append({url: url, text: text[:3000]}) summary llm.summarize(f主题{query}\n材料{docs}) return {summary: summary, sources: [d[url] for d in docs]}这里我吃过一个亏搜索API返回的URL里经常有跳转链接和UTM参数直接抓会撞上反爬或拿到错误页面。需要在抓取前做一次URL清洗并设置统一的浏览器User-Agent超时控制在5到10秒。另外多来源交叉验证很重要只抓一个网站很容易被单一立场带偏。3.2 流程编排类技能多步骤业务操作流程编排类技能是让Agent“干活”的核心典型场景是“预订会议”“创建订单”“审批流程”。这类技能的特点是步骤多、依赖外部系统、容易中途失败。我习惯把这技能设计成状态机模式内部维护一个状态变量每完成一步就更新状态并记录日志这样即使中途挂了也能从上一个完成点恢复。拿“会议预订”来说状态包括待选时间→待选会议室→待确认参会人→已完成。每一步都调用独立的子操作比如查会议室空闲、创建日历事项、发送通知。关键点是每一步都要有“失败重试”和“人工确认”的钩子。比如会议室被占用时可以让模型自动换一个时间段但如果两次都失败就得停下来问用户而不是无限循环。我在实现时给技能加了一个“checkpoint”机制每完成一步把当前状态保存成一个JSON文件下次执行时先读取checkpoint再继续。这个做法在长流程里极其有用至少避免了“第四步失败后从头再来”的尴尬。3.3 工具调用类技能API对接与参数映射这类技能负责把外部API包装成模型友好的操作难点不在API本身而在参数映射。模型只会说“帮我查一下北京明天的天气”API需要的是lat39.9lon116.4date2025-06-20中间隔着一道“自然语言到结构化参数”的鸿沟。我的做法是在技能内部定义一个“参数映射器”提前写好常见实体到API参数的规则。比如天气查询技能内置国内城市代码表模型只需要输出城市名映射器自动查表得到经纬度。对于复杂API可以用一次小模型的few-shot调用把用户原始文本转成JSON参数但一定要用schema.json做严格校验参数缺失时返回错误信息并提示模型补充。这里有一个控制风险的细节所有外部API调用必须设置最大超时和重试次数且重试要加指数退避。我见过不少Agent项目因为某个接口响应慢了Agent就一直在那儿干等最后整个任务卡死。还有API返回结果必须做schema校验防止模型拿到脏数据后一本正经地加工出错误结论。3.4 技能内上下文传递状态管理技能执行过程中上下文是如何传递的很多新人会直接把所有中间结果一股脑塞进上下文窗口这既浪费token也容易让后续步骤被无关信息干扰。我在 agent-skills 里定义了一个轻量级的“工作记忆”结构每个技能只关注与自身相关的数据字段。工作记忆本质是一个字典包含当前任务ID、输入参数、执行历史、输出结果。技能之间传递时只暴露“契约字段”比如“web_research”技能只输出summary和sources不允许擅自把原始HTML塞进全局上下文。这样设计以后整个Agent处理长任务时上下文不会线性膨胀而且每个技能都可以独立测试——只要给它固定的输入就能验证输出是否稳定。work_memory { task_id: task_123, inputs: {topic: AI Agent 落地}, history: [], outputs: {} }4. 技能编排与组合从单技能到多技能协同4.1 线性编排与条件分支单个技能能做的事有限真正体现Agent价值的是技能组合。最简单的编排是线性执行技能A→把A的输出作为B的输入→得到最终结果。比如“调研某公司→根据调研结果起草合作邮件”就是“web_research→email_writer”的线性链。这类编排只需要在调度器里维护一个有序列表。但实际任务往往有分支。比如“判断用户意图如果用户只想查询就调用检索技能如果想生成报告则先检索再调用报告技能”。我建议在编排层定义一套类似“技能流程图”的配置用条件表达式控制路由。虽然有些Agent框架支持复杂图编排但对于绝大多数业务场景树状分支就够了别过度设计。分支越多模型走错路的概率越大排障也越难。在实践中我一般这样写编排配置{ steps: [ {id: intent, type: classifier, next: {search: retrieve, report: report_chain}}, {id: retrieve, skill: web_research, next: answer_draft}, {id: answer_draft, skill: writer, next: done} ] }4.2 技能间数据契约设计技能组合最大的坑是“接口不一致”。A技能输出的键叫contentB技能却读text结果B永远拿不到数据。这个问题靠口头约定没用必须在代码层面强约束。我在 agent-skills 里给每个技能的输入输出都定义了JSON Schema编排器在传递数据前做一次自动校验不匹配直接报错。数据契约的设计原则是输出尽量小字段尽量少语义尽量明确。一个技能如果输出几十个字段下游技能根本不知道该信哪个。比如“web_research”只输出summary字符串和sources列表这就够了。下游“email_writer”只需要读summary。不要图省事直接把整个输出字典传给下游那样和传全局变量没区别迟早出问题。4.3 组合失败的兜底策略技能组合一定会失败不是你的问题是概率问题。模型可能理解错意图外部API可能超时数据可能不符合预期。所以兜底策略必须在设计阶段就写进编排器。我常用来兜底的方法有三个一是“降级”比如主技能调用失败后自动换一个功能近似但更简单的技能二是“澄清”当检测到模型输出的参数不完整或置信度低时直接反问用户不强行执行三是“截断”当技能执行链超过一定步数还没出结果时停掉当前分支返回部分结果和日志让人工介入。这三个策略能覆盖90%的异常情况。特别提醒不要让技能自己无限重试。我见过一个项目里模型调支付接口失败后连续重试了二十多次差点没把用户的余额扣穿。正确的做法是设置重试上限我通常设两次超过上限就进入降级或人工确认流程。5. 常见问题与排障实录5.1 模型死活不调用技能怎么办这是最让人抓狂的问题Skill说明书写得清清楚楚模型却像没看见一样自己脑补答案。我的排查顺序是先看注册中心里技能的索引是否存在且正确再看路由器的候选列表里有没有把该技能排进去最后看SKILL.md里的When部分是否覆盖了用户的典型说法。我遇到过最隐蔽的原因是技能索引和实际技能名不一致。比如技能目录叫web_researchSKILL.md里标题却写成Web Research and Summarization路由器用目录名做关键词匹配再让模型看标题时模型就把它当成了另一个技能。后来我统一强制要求技能文件夹名、SKILL.md首行、注册名三者必须完全一致这个问题立刻就少了。另一个原因是系统Prompt语气问题。如果Prompt里写着“你可以使用以下工具”模型会觉得自己是可选的改成“当任务需要外部信息时你必须使用web_research技能”调用率会明显上升。模型很吃“必须”这个词的指令强度。5.2 技能参数频繁传错参数传错的表现是技能明明需要query模型传了个question需要date传了个time。这通常是schema信息不够清晰导致的。解决方法是在schema里给每个字段写示例值和校验规则而不仅仅是类型。比如{ name: query, type: string, description: 搜索关键词例如2025年大模型招聘趋势, minLength: 1, maxLength: 100 }如果模型还是传错可以在技能的How里加一步“参数检查”正式执行前先用一个轻量级校验函数把参数跑一遍发现不符合schema就直接报错并给模型一次修补机会。这一步能拦截大部分低级错误而且不会太耗token。5.3 技能执行结果太长上下文被撑爆Agent跑着跑着上下文窗口满了模型开始丢失早期的记忆这是长任务里最常见的崩溃方式。根源在于技能把大量中间结果写进了上下文。我的两板斧是结果压缩和外部存储。结果压缩是指每个技能在返回前用一句话摘要自己的核心输出只把摘要放进下一轮上下文原始结果存到本地文件或数据库里。外部存储则更彻底技能把完整输出写到指定路径上下文里只放一个“结果已保存到xxx需要时再说”的标识。这样上下文几乎不会膨胀。实践中我把这两招组合使用默认技能输出先做摘要摘要大于200字再走外部存储。效果非常稳定一个20步骤的复杂任务上下文体量始终控制在几千token以内。5.4 调试技巧给技能加“通话记录”最后分享一个救命级的调试技巧——给每个技能加上类似“通话记录”的trace文件。以前我调试技能时只能看到最终输出完全不知道中间发生了什么。后来我在技能执行函数里插入一个logger把每一步的时间、输入、输出、调用了哪个工具、耗时多久全部记录下来输出成结构化的JSON日志。有了这份日志我不再需要猜“模型为什么选错技能”直接看记录里路由器给出的分数排序也不再需要问“这个结果怎么算出来的”直接翻技能内部每一步的操作。我之前排查过一个“会议预订”技能莫名其妙取消订单的问题最后通过日志发现是某个步骤里的状态变量被上一步覆盖了。这个问题如果没有日志几乎不可能定位。日志的粒度控制在“每技能调用一个外部工具记一行每执行一个决策点记一行”太细会刷屏太粗没意义。卡住的时候先看最后一条日志90%的问题都能缩小到具体那一步。我在实际折腾 agent-skills 的这段时间里最大的体会是Agent能不能稳定完成任务不取决于模型有多聪明而取决于你把技能切得多细、边界画得多清、日志留得多全。模型像一名新员工聪明但没经验技能库就是标准作业手册写得越好员工越不容易出错。如果你也在搭自己的Agent不妨先从三个技能开始一个检索、一个生成、一个操作跑通了再加别一上来就搞上百个技能。慢慢来反而更快。