做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快一年，最大的体会是别指望一步到位，先跑通再优化。我第一版周报智能体只用了三个节点，输出质量大约能到人工的六成，但已经能跑通流程。后面才慢慢加打分、反思、缓存。一上来就追求完美架构的人，多半在半路就放弃了，因为永远有细节没想明白。
另外一个很实用的建议是多做版本标记。我每套技能都带版本号，改一次就升一次级。这样出了问题可以快速回滚到上一个版本，不会出现"昨天还能用今天就不行了"的懵圈状态。这个习惯帮我避免了好几次事故。
技能库的沉淀是个滚雪球的过程。第一个技能搭起来最费劲，但搭完之后，第二个、第三个就是照着模子刻。我现在新接一个流程，从拆解到落地一般两天能搞定，有三分之一的时间是在复用之前写好的节点。做这套东西总结起来就一句话：与其每次让模型自由发挥，不如把发挥空间圈在你自己设计的边界里，这个边界越清晰，结果越稳定、越可控。希望这些经验能帮你少走点弯路。
