做AI应用这一年多我发现一个特别有意思的现象很多人不是不会写提示词也不是不会调API而是卡在每次让智能体干活都得重新把所有话术讲一遍这个坎上。你让AI写周报要给它塞公司背景、项目进度、格式模板你让它整理行业调研又得把信息源、输出结构、分析角度复述一遍。时间全花在重复描述上效果还不稳定——同样的需求换个表述方式结果就飘了。这就是我最近一直在折腾agent-skills智能体技能的原因。说白了它是把一次性对话变成可复用技能模块的一套工程思路先把任务拆成标准化节点再把每个节点的执行逻辑、输入输出、校验规则固化下来最后通过一个调度中枢组合调用。解决的问题很直接——让AI从听你现编需求变成按你沉淀好的技能库干活。这篇文章不聊概念只聊我怎么拆、怎么搭、踩过什么坑适合已经玩过一阵子API或智能体框架、但觉得效果不稳定的人参考。1. 先搞清楚 agent-skills 到底解决什么问题1.1 从会聊天到会干活差的是一整套技能系统大模型本身是个语言引擎你问它什么它都能接话但这跟干活是两码事。干活意味着要有输入、有处理、有输出、有确认还要能在出错的时候自己兜回来。比如让AI帮你生成一份销售周报它得先从数据源拉出数字再判断哪些指标异常然后套用你的汇报模板最后生成文字。这四步每一步都需要不同的能力而普通对话模式下这四个能力全挤在一段提示词里全靠模型临场发挥。我一开始也天真以为把流程步骤写清楚塞给模型就行。实测下来发现步骤能被模型看到但没法被模型记住和严格执行。你今天让它先查数据再总结它照做了明天你换个说法问它可能就先总结再查数据顺序彻底乱了。agent-skills的思路是把这些能力拆成独立单元每个单元有明确的输入输出边界和触发条件。类比一下你不是让一个厨师看着办做顿饭而是给他一个配菜台、一个灶台、一个装盘区每个区域有标准动作。大模型还是那个大模型但有了技能系统的约束它的发挥空间被收敛到可控范围内稳定性立刻上来了。1.2 它的能力边界和应用场景搞清什么时候该用技能系统也很关键。不是所有任务都需要agent-skills别为了工程化而工程化。我现在的判断标准是如果任务可以一句话说清、一轮对话完成那直接写提示词调API就行搞技能层纯属浪费。但如果是下面这几种情况技能系统就值回票价了多步骤任务步骤之间有依赖关系比如先采集→再清洗→再分析→最后成稿跨系统操作需要调数据库、调第三方API、读写文件模型本身没有这些能力得靠技能节点去接同一个流程要被反复执行比如每周的周报、每月的复盘、每个新客户进来都要跑的标准化流程2. 把智能体技能拆成五个模块照着搭就行2.1 五大基础功能感知、规划、记忆、行动、反思我在实际搭建时发现不管多复杂的技能拆到底都跑不出五个基础功能块。你可以把它想象成人的工作方式先看感知、再想规划、记笔记记忆、动手做行动、做完检查反思。感知模块负责把外部信息转成模型能理解的格式。比如用户上传一个PDF里面是扫描件感知模块就得先OCR再结构化如果是数据库就得先查出来再转成表格。这个模块我建议独立做因为输入源经常变但后续流程不需要关心输入是什么格式。规划模块是最容易过度设计的地方。我之前总想让模型自动规划每一步后来发现对复杂任务靠谱对日常任务反而容易飘。现在我的做法是简单任务直接用固定流程序列复杂任务才让模型在技能库里面选路。比如生成周报是固定序列帮我做季度复盘就让它自己决定要不要先拉数据、再调历史、再做对比。记忆模块分两层。短期记忆就是对话上下文SQLite或者内存里放一下就行长期记忆必须用向量库存历史项目和用户偏好。踩过的一个坑是无脑把所有对话全塞给模型结果上下文窗口爆了费用还翻倍。后来改成按需检索——只有当前步骤需要历史信息时才从向量库里查两三条相关的放进去。行动模块就是真正调用外部工具的地方包括API请求、代码执行、文件写入。这里面有个细节每次调用必须做输入校验。因为技能编排是自动的模型生成的可能不是合法参数。我见过最离谱的是模型调用天气API时传了个日期字符串明天直接把API干崩了。反思模块是新手最常忽略、老手最看重的一块。它的作用是在输出后加一步自检结果符不符合预期有没有缺数据格式对不对我通常在关键技能后面挂一个反思节点用另一个提示词去校验上一个节点的输出不合格就打回重做。别小看这一步它能把你整个系统的不稳定率压下去一半。2.2 技能描述比技能代码更容易被低估很多人把重心全放在代码逻辑上结果路由此起彼伏——模型根本不知道该在什么时候调哪个技能。我后来才明白在技能系统里描述文本比执行代码更重要。代码是怎么做描述是何时做模型靠描述来做路由决策。举个例子我有个技能是查询产品价格我刚开始写的描述是查询产品价格并返回结果结果模型遇到帮我看看这个套餐多少钱这种问题死活不调它。后来我把描述改成当用户询问任何SKU的价格、历史价格趋势、折扣信息时调用本技能输入是产品ID或名称输出是当前价格和30天价格曲线。一改完命中率立刻上来了。描述里面必须写清楚触发场景、输入要求、输出格式、不能做什么。特别是不能做什么它能挡住很多误调用。我有个技能是生成营销文案描述里明确写了不处理与营销文案无关的任何请求从那以后模型再也不会拿它去生成代码注释了。3. 技能工程实操把一个任务改造成技能3.1 用流程切片法拆解真实任务我在公司落地过一个行业信息周报的智能体可以拿这个例子完整走一遍流程。需求很朴素每周收集指定几个渠道的行业动态去重、摘要、按重要性排序最后生成一份带观点分析的周报。第一步不是写代码而是把人工做这件事的完整步骤写下来。人工流程是打开资讯源→筛选近7天的内容→把重复的合并→判断每条重要度→写摘要→补充自己的分析观点→排版成文。这个流程切下来就是七个技能节点。切的时候有个原则每个节点只做一个事输入输出尽量简单。比如摘要节点只管摘要观点分析节点单独拆出来别混在一起。混在一起会让单节点提示词变得很臃肿后面想单独调参或者替换某个环节都很难。拆完之后的节点定义大概长这样节点输入输出处理逻辑采集渠道列表、时间范围原始文章列表调用RSS/API抓取标题正文清洗原始文章列表去重后的文章列表按标题相似度去重过滤广告打分去重后的文章列表带重要度分数的列表关键词权重 时效性加权摘要带分数的列表每条200字摘要调用大模型生成观点摘要列表3条核心观点基于摘要做趋势判断排版全部内容逃生Markdown文本套模板加小标题自检成稿文本修正后的成稿检查错乱、重复、超字数表格里最容易被忽略的是打分节点。很多人会让模型直接判断重不重要但模型对重要的主观性太强。我改用规则权重打分标题和正文里出现客户公司、竞品公司名加3分出现融资、收购等关键词加2分时间越近加越多。规则计算稳定可解释模型只负责在摘要和观点环节发挥语言能力。3.2 注册、编排、调用的完整套路切片完成后就是工程化落地我这套是用Python写的核心就三个部分技能注册表、路由调度器、执行器。技能注册表就是一张映射表把技能ID、描述、入口函数注册进去路由调度器负责根据用户请求选路径执行器负责跑每个节点。SKILL_REGISTRY { collect_news: { description: 从指定渠道收集近N天行业资讯输入渠道列表与天数输出文章列表, handler: collect_news, input_schema: {channels: list, days: int}, output_schema: {articles: list} }, deduplicate: { description: 按标题相似度去重输入文章列表输出去重列表, handler: deduplicate, input_schema: {articles: list}, output_schema: {articles: list} } # ... 其他节点 }真正执行的时候我强烈建议把每个节点的输出缓存下来存成结构化数据不要只存最终结果。原因有两个一是排在后面的节点如果挂了可以直接从缓存节点重跑不用整个流程从头来二是方便调试查问题你能清楚看到哪一步产出的结果不对劲。我调试智能体时必做的一件事就是翻中间缓存。执行器里还有个参数计算的小技巧。调用大模型时max_tokens不是随便设的。我的做法是先用输出schema估算摘要节点每篇200字约300个token列出10篇就要预留大约3000个token然后我再加20%冗余。这样设max_tokens既不会因为超长被截断也不会因为设得太大浪费钱。3.3 给技能装一个反思回路反思节点的提示词模板我踩过很多坑最终稳定的版本长这样你是一个质检员。请检查以下文本是否满足要求只回答PASS或FAIL不要修改原文。 检查点 1. 是否包含所有必须字段{字段列表} 2. 是否有重复段落或互相矛盾的内容 3. 是否超过{最大字数}字 4. 是否遵循了{输出格式要求} 文本内容 {替换为待检查文本}注意这里要求它只回答PASS或FAIL不要修改原文。我一开始允许模型直接改结果它自作主张把内容重写了一遍事与愿违。让模型只做判断修改动作交给重跑机制执行流程会清晰得多。判FAIL的节点会自动回到对应上游节点带着质检反馈重新跑一次。这个重跑机制我用了一个最大重试次数默认2次超过次数就标记人工介入避免死循环烧token。4. 工具链对比和实操中绕不开的坑4.1 主流框架怎么选得先看生态我折腾过好几套方案结论是先别急着选框架先看你要解决的问题适合哪一派。目前主流的方向大概分四种LangChain系、LlamaIndex系、AutoGen系、还有各家云厂商的官方Agent SDK。LangChain是我最早用的它提供的LCEL可以很灵活地做编排技能库Skill的生态也最丰富。缺点是抽象层级太多光理解它的链、图、记忆、回调就够喝一壶的而且版本迭代经常破坏性更新我升级过一次之后工具直接跑不起来折腾了大半天。适合已经有LangChain基础、需要快速积木式搭系统的人。LlamaIndex在数据接入方面是强项如果我做的场景重数据比如文档问答、知识库检索首选它。它的Agent Skills更偏数据管道如果你做的是动作类智能体要调用一堆外部服务用起来反而别扭。AutoGen是多智能体派的代表适合要让多个角色互相协作的场景。但我个人觉得它对技能这类确定性的东西支持不如单智能体流程顺手多智能体的对话开销也大一套流程跑下来token消耗感人。如果业务不是必须要角色扮演式的协作建议先别上。各家云厂商的Agent SDK值得单独说说。OpenAI和Anthropic的官方SDK对技能的定义更原生描述、调用、路由都是第一公民写起来比LangChain清爽很多。Anthropic那个Claude Skills的形式其实跟我在2.2里说的思路很像——描述驱动路由。缺点是绑定平台模型和技能系统都在一家换模型就得重写。我的选择跟单一模型深度绑定的项目用官方SDK需要多模型切换的复杂项目还是回到LangChain。4.2 三个绕不开的坑第一个坑是上下文膨胀。技能节点多了之后每个节点都会往上下文里塞东西越跑越慢、越跑越贵。我后来在每个节点结束时只保留本节点的结构化输出和一条摘要把过程性内容统统清理掉上下文从动不动七八千token降到了两千以内。第二个坑是工具调用失败没有重试。模型调用API经常遇到超时、限流、返回格式不对不发重试逻辑就等着失败。我的做法是把所有带副作用的外部调用都包一层统一的重试中间件比如API请求失败就退避重试3次超时就把超时时间翻倍再试一次。第三个坑是缺少评测。没有评测的智能体就是盲改。我现在每次改技能都会跑一遍我预置的20个固定测试用例对比改前改后的通过率。没有这个动作你可能根本不知道一次改动是变好了还是变差了。评测集不用多我一开始用了20个场景覆盖不同难度和不同输入风格够用且维护成本低。5. 高频故障自查表与提速技巧5.1 几分钟定位问题以下是我在调试中遇到的问题概率最高的几个整理成了速查表遇到症状直接对号入座症状最常见原因解决动作智能体完全不会调用某个技能技能描述不清晰、路由选错了重写描述加入触发场景示例调用了技能但返回结果乱套输出schema定义不严格给输出加JSON Schema校验不合格重跑任务跑一半卡住不动节点之间数据传递断了查看中间缓存定位断点结果时好时坏缺少反思节点或提示词里有模糊词加质检节点把模糊词改成确定规则token消耗暴涨上下文没清理多轮对话全堆着每轮结束后精简上下文技能互相误触发描述里没写职责边界每个技能描述加不能处理条款这个表不是万能的但覆盖了我超过八成的问题。排查的核心思路永远是先看中间结构化数据别直接盯着最终文字输出看那等于雾里看花。5.2 我实测有效的三个提速技巧第一个是并行调用。有些技能节点之间没有依赖关系比如采集和清洗有依赖必须串行但采集A渠道和采集B渠道完全独立可以用线程池并发跑。我的周报系统原来七个节点串行要4分钟改成去重后并行采集和打分直接压缩到1分50秒。第二个是结果缓存。面对同一个用户反复问相似问题时我会把上次的查询结果按输入参数的hash缓存起来命中就直接返回不带模型也不调外部API。这个方法能省下不少token尤其适合那些高频查询类技能。第三个是分级路由。不是所有请求都要走完整流程。先让一个小模型便宜的那种或者一版极简规则判断用户意图是简单问答、标准流程、还是复杂自定义任务。简单问答直接给答案标准流程调固定技能链复杂任务才让大模型在技能库里面自由路由。这相当于给智能体加了一个交通分流便宜模型处理了80%的流量成本一下就降下来了。6. 最后分享几点我自己摸索出来的经验做agent-skills快一年最大的体会是别指望一步到位先跑通再优化。我第一版周报智能体只用了三个节点输出质量大约能到人工的六成但已经能跑通流程。后面才慢慢加打分、反思、缓存。一上来就追求完美架构的人多半在半路就放弃了因为永远有细节没想明白。另外一个很实用的建议是多做版本标记。我每套技能都带版本号改一次就升一次级。这样出了问题可以快速回滚到上一个版本不会出现昨天还能用今天就不行了的懵圈状态。这个习惯帮我避免了好几次事故。技能库的沉淀是个滚雪球的过程。第一个技能搭起来最费劲但搭完之后第二个、第三个就是照着模子刻。我现在新接一个流程从拆解到落地一般两天能搞定有三分之一的时间是在复用之前写好的节点。做这套东西总结起来就一句话与其每次让模型自由发挥不如把发挥空间圈在你自己设计的边界里这个边界越清晰结果越稳定、越可控。希望这些经验能帮你少走点弯路。