1. 为什么Agent项目越写越乱：问题出在缺少一层"技能抽象"
过去一年我做了好几个基于大模型的Agent项目，从最早只会调API的聊天机器人，到后来能自己规划任务、调用工具的多步骤Agent，再到尝试让Agent自主完成一系列业务操作。做得越多，越发现一个痛点：Agent的能力边界不是靠模型智商决定的，而是靠你给它沉淀了多少可复用的"技能"决定的。而"agent-skills"这个方向，恰恰是在解决这个问题。
先说个场景。假设你写了一个能联网搜索、能总结文章、能写邮件的Agent。第一版跑得很顺，提示词写得挺精妙，工具调用也打通了。但过了两三个月，你想让这个Agent再接一个新任务——比如让它去分析某个行业报告并给出竞品对标。你会发现，你写过的搜索逻辑、总结逻辑、邮件格式，全都散落在各个prompt里，形成了"一次性知识"。要么改起来很痛苦，要么干脆推倒重来。这就是典型的缺乏"技能抽象层"的项目。
我理解中的agent-skills，是指把Agent在特定场景下的一系列行为模式、判断逻辑、输出规范以及所需工具调用方式，封装成一个结构化的、可复用、可组合的"技能包"。它不同于单一的工具（Tool），也不同于一整套工作流（Workflow）。技能是介于单次调用和全流程编排之间的中间层——它更像是一个人掌握的"本事"，比如"做竞品分析""写周报摘要""从PDF提炼合同关键条款"，这些本事可以自由组合，随时复用。
这篇文章我想把agent-skills这个概念讲透：它到底解决什么问题，和工具、工作流有什么本质区别，怎么定义和落地一个技能库，以及我在多次实践里踩过的坑。适合正在做Agent应用开发、又觉得项目越写越难维护的人参考，也适合刚接触Agent、想从一开始就搭一个可持续扩展的架构的初学者。
2. 从Tools到Skills：一次"能力组织方式"的升级
2.1 工具是"手"，技能是"手艺"
很多Agent框架里都有Tools的概念，本质上是给大模型暴露一些可调用的函数接口，比如search_web、read_pdf、send_email。Tools本身不包含"什么时候该用、怎么组合、输出格式怎么定"这些高层逻辑。Tools是一双手，但脑子里得有怎么用这双手干活的"手艺"，这手艺就是Skills。
举个例子。你的Agent有一个"搜索并总结"的组合需求。如果只用Tools实现，你会让模型自己拼装：先search_web，再对结果做摘要。但问题来了——模型可能今天搜索词抽取得很准，明天就跑偏；可能前天总结还分三个要点，昨天就变成了一大段含糊的概述。结果不稳定。因为这类"流程+判断"的经验没有被固化，完全依赖模型的临场发挥。
而把能力组织成"技能"之后，事情就变了。"做行业速览"作为一个技能，内部定义了搜索词怎么生成、覆盖几个信源类型、摘要必须输出哪些板块、最多用几条搜索结果、每个板块的措辞风格。模型进来之后不是自由发挥，而是在一个已经有框架的"工作台上"填内容。这样每次产出的稳定性会明显提升，而且后期调优只需要改技能本身，不用翻遍项目里几百个prompt。
2.2 Skills、Tools、Workflow三者的边界
我习惯用下面这张表来区分这三类概念：
| 层次 | 典型形态 | 解决的问题 | 粒度 | 复用性 |
|---|---|---|---|---|
| Tool | 单个函数/API封装 | 能不能执行某个原子操作 | 最小 | 低（只解决单点） |
| Skill | 一组工具+提示词+行为规则的结构化封装 | 能不能稳定完成一类任务 | 中等 | 高（一类场景复用） |
| Workflow | 整套多步骤流程+人工介入+分支判断 | 能不能端到端完成复杂业务 | 最大 | 低（通常绑定具体业务） |
三个概念不是替代关系，而是层次关系。Workflow里会编排多个Skills，Skill内部会调用多个Tools。而你去观察一个成熟的项目，真正决定Agent"强不强"的往往不是某个工具调得溜不溜，而是它掌握了几种高质量的Skills、这些Skills能不能互相配合。
2.3 技能库的引入带来什么变革
一旦项目里有了技能库（或者说agent-skills目录），就自然形成了三个好处：
第一，知识开始积累。项目不再是一堆prompt的平铺，而是把方法论沉淀到技能包中。每解决一类新任务，就往库里加一个技能。隔几个月回头看，你拥有的不是"一段能用的代码"，而是一整套可复用的"业务能力目录"。
第二，调试边界清晰。如果Agent某个任务表现不好，你只需要把那一个技能抽出来单独调试——给一组测试输入、看它内部的工具调用序列、检查输出是否规范、问题出在提示词还是工具选择上。不用再把整个流程run一遍靠肉眼找问题。
第三，新项目可以"拼装"起来。换一个新场景时，你不需要从零写提示词。先翻技能库，挑出能用的技能，再针对新场景补一两个定制技能，就能快速搭出一个有基本能力的Agent。这个开发方式，本质上跟拼乐高差不多——一个个标准件，按需搭建。
3. 技能定义实战：如何设计一个"可复用、可维护、可演进"的技能包
3.1 技能描述：关键是让模型和你自己都看得懂
定义技能的第一步，是写一份足够准确的技能描述。这里说的"准确"包括两个层面：对人准确、对模型也准确。
对人准确的意思是，你（或你的团队成员）看技能列表时，一眼就能知道这个技能解决什么问题、包含哪些步骤。对模型准确的意思是，你把技能描述喂给Agent时，它能在合适的场景中主动唤起这个技能，不会在错误场景乱用，也不会该用时却想不起来。
我见过很多新手的写法是："skills: 做市场分析"。这种描述太模糊——模型读到之后大概率一头雾水。我的建议是给技能描述拆成几个固定字段：适用场景、不适用场景、核心能力、依赖工具、输出规范、调用的其他技能。一个完整的技能描述模板大致长这样：
name: competitive_scan description: 针对指定行业或竞品，输出包含市场份额、核心动向、差异点对比的扫描报告 when_to_use: - 用户要求对某家公司做竞品分析 - 需要了解行业头部玩家的近期动态 - 需要为策略建议提供竞争者背景 when_not_to_use: - 仅需单条新闻摘要，无需横向对比 - 用户明确要求不涉及竞品信息 tools: - search_web - fetch_url - summary_text output_format: 报告头: 目标公司与行业 市场份额部分: 支持用表格 核心动向部分: 每个竞品至少3条动态 差异点部分: 至少3个维度 depends_on_skills: - web_research这种结构化描述最大的价值是：把"什么时候用、什么时候不该用"也写进了技能里。模型在决策时，就能避免很多误唤起。
3.2 技能内部结构：把"提示词"升级为"行为协议"
传统做法里，提示词是一大段自然语言，塞进System Prompt里完事。但技能化之后，我更倾向于把提示词拆成角色设定、任务流程、约束条件、输出模板四个部分。这不是形式主义，而是为了隔离变化。
角色设定负责定义Agent在这个技能里的身份立场；任务流程定义步骤顺序，比如"第一步提取搜索词，第二步调用search_web，第三步筛选信源，第四步生成摘要"；约束条件写清楚限制，比如"搜索不超过5次""不采用未经核实的自媒体信息""摘要单条不超过100字"；输出模板则严格框定最后结果的格式。
把这四部分分开，好处非常明显：当你发现输出格式不对时，只改输出模板，不会碰流程和角色；当你发现模型总在第二步偏离方向时，只加强约束条件，其他部分不受影响。这种模块化改动的体验，跟以前"动一句提示词牵一发动全身"比起来，效率提升不止一个量级。
3.3 知识沉淀的关键：从"做事过程"中提炼技能
有一个问题经常被忽略：技能到底是怎么形成的？不是靠拍脑袋写的，是从大量实践样本里总结出来的。
我做技能库时，会先让Agent在"无技能"状态下跑一些代表性任务，记录它成功与失败的行为模式。然后问自己三个问题：
- 哪些环节是稳定的、可抽象的？（做成技能骨架）
- 哪些环节是模型随机发挥、导致结果不稳的？（需要加约束规则）
- 哪些环节是高度依赖具体上下文的？（不应该放进技能，留给运行时动态生成）
比如说，我之前做一个法律合同审查Agent，发现提取违约金条款的成功率时高时低。研究了几次日志后，发现模型容易把"赔偿金额计算方式"和"违约金上限"混在一起。于是我把"违约金条款提取"单独固化成技能内部的一个子流程，给模型明确指令："违约金部分至少输出两个子字段：触发条件和计算基准。" 加了这条规则后，后续稳定性提升明显。
这就是沉淀技能的正确姿势：不是一次性设计出来的，而是从真实失败案例里一点点"抠"出来的。这也是为什么我把agent-skills视为一个持续演进的结构，而不是一锤子买卖。
4. 技能的编排方式：让技能之间产生"化学反应"
4.1 顺序编排：最常见的一等工作模式
技能之间最简单的组合方式就是顺序执行。比如一个"行业全景分析"需求，内部可以依次调用："信息采集技能" → "公司档案提取技能" → "竞争对比技能" → "报告生成技能"。每个技能各管一段，前一个的输出作为后一个的输入。
这种模式最简单，也最容易保证稳定性。需要注意的地方是交接格式要提前约定好。我一般会在技能之间定义一个"标准数据载荷"（比如统一的JSON结构），前一个技能输出JSON，后一个技能读JSON。这比让后一个技能自己去解析前一个的自然语言输出要稳得多。
下面是一个典型的顺序编排示例：
| 步骤 | 技能 | 输出数据格式 |
|---|---|---|
| 1 | 信息采集 | 结构化链接列表 |
| 2 | 网页内容提取 | 正文+元信息JSON |
| 3 | 摘要与归类 | 分类要点列表 |
| 4 | 报告组装 | 按模板填充 |
4.2 动态选择：让Agent自己挑技能
顺序编排适用于流程固定的任务，但很多真实场景需要Agent根据情况自主挑选技能组合。这时，高级一点的架构是让Agent先"阅读技能目录"，再决定调用路径。
一个实际例子：用户说"帮我分析一下我们公司这个月运营数据，顺便对比一下竞品"。这个请求其实包含两种技能需求——"内部运营数据分析"和"竞品扫描"。如果Agent拥有技能目录，它就能自己去调用两个技能并组织输出，而不是靠你提前把所有可能性写死。
这种动态选择模式的关键在于：每个技能的description字段必须包含足够丰富的"触发线索"信息。我在3.1节里强调适用场景、不适用场景，就是为了这一步服务的。模型在读到用户请求时，是靠技能描述和当前任务的语义匹配度来决策的。描述写得越具体，匹配越准。
4.3 递归分解：复杂任务拆成技能树
再往上走一步，就是把技能作为"任务分解"的基本单元。当Agent接到一个复杂任务时，它先尝试拆分成若干子目标，每一个子目标匹配一个技能；如果某个子目标没有匹配的技能，它就会尝试用已有技能组合出一个临时方案。
这个机制让我想到了编程上的递归——复杂任务被拆成技能树，叶子节点是具体工具调用，中间节点是技能组合。当你的技能库足够丰富时，你会发现Agent面对新任务的胜任能力会有明显提升，因为它不再是"硬答"，而是"调用已有能力逼近答案"。
在实际项目中，这种递归分解一般需要配合一个"规划模块"。让大模型先输出一个任务规划树，然后逐个节点执行。我在实践中发现，规划质量跟技能目录的质量高度相关——如果技能描述清晰且相互独立，规划模块给出的树形结构通常更合理；反之，如果技能描述含糊，规划往往崩塌。
5. 落地实践中的四个大坑与应对方案
5.1 坑一：技能粒度不对，要么太大要么太小
技能粒度是整个技能库设计中最难拿捏的部分。技能定义得太粗，比如"content_generator"，听起来啥都能做，实际上Agent根本不知道具体该调用什么工具、按什么流程走，技能形同虚设；技能定义得太细，比如"generate_title_for_blog_post"，又会导致技能数量爆炸，维护成本高，Agent在技能匹配时也会陷入选择困难。
我的经验指标是：一个技能应该能在1分钟左右的执行时间内完成、内部包含2到5个工具调用步骤、输出是一个结构完整的交付物。如果执行跨度超过5分钟，基本说明技能拆得太粗；如果只调用1个工具就结束，基本说明拆得太细，应该合并到上级技能里。
5.2 坑二：技能间的上下文传递用了自然语言
这是我在早期项目里踩过最痛的一个坑。当时两个技能之间直接传自然语言文本，后一个技能拿到前一个技能的输出时，经常出现"误解上一段哪句话才是关键信息"的情况，导致把无关内容当成依据生成结论。
后来我彻底改成结构化的数据载荷传递。每个技能的输出不再是纯文本，而是定义好的JSON结构，字段含义和约束都写清楚。比如"web_research"技能的输出是这样的：
{ "source_type": "industry_report", "fact_list": [ { "fact": "市场增速放缓至4%", "source_url": "https://...", "confidence": 0.82 } ], "summary": "..." }后续技能只要读取fact_list就可以，完全不需要去猜文本里的语义。这个改动虽然初期增加了少量开发工作，但它让技能之间的松耦合成为可能——每个技能只管自己的输入输出协议，不用关心其他技能的内部实现。
5.3 坑三：技能库缺乏退出条件，Agent陷在循环里
Agent调用技能时如果没有明确的"完成标志"，很容易陷入无意义的重复调用。比如"信息采集"技能，在搜索结果质量不理想时，模型可能会不断调整搜索词重试好多次。看似勤奋，实际却造成了资源浪费和时间延迟。
应对方案是在每个技能的定义里增加两个字段：max_attempts（最大尝试次数）和 exit_condition（退出条件）。当重试次数达到上限，或者某个条件满足时，强制技能结束并输出当前最优结果。数据上看，加上退出条件之后，技能的平均执行时间缩短了不少——这个约束不是限制Agent的能力，而是让它把精力花在更值得探索的方向上。
5.4 坑四：只录技能、不测技能，等于没录
技能库维护最大的挑战不是写技能，而是定期测试和更新技能。很多项目刚上线时技能库挺漂亮，三个月后全变成一堆"过时提示词"。模型升级、业务变化、工具调整，都会让旧技能逐渐失效。
我现在维护技能库的方法是建立一套"技能回归测试集"。每个技能搭配3到5个代表性测试输入，每次更新技能（或升级模型）就整库跑一遍回归，看哪个技能的表现有明显下滑，再针对性调整。这是把技能的维护工作从"救火模式"变成了"例行巡检模式"，长期收益非常明显。
6. 技能库的演进方向：从个人项目到可共享的"能力市场"
6.1 结构化与标准化是共享的前提
如果你只是一个人做一个项目，技能怎么定义都行。可一旦想让技能在不同项目之间复用、在不同团队之间协作，就需要一个相对稳定的标准。我见过有些社区尝试把技能定义成Markdown目录+YAML元数据的组合，也有人用纯JSON Schema做定义。标准化本身并不难，难的是所有参与者是否愿意遵守同一个约定。
从我的实践看，一个健康的agent-skills标准至少要包含：技能元信息（名称、描述、版本、作者）、输入输出协议（数据格式）、依赖关系（工具与其他技能）、调用策略（何时用、何时不用）。这四个维度缺一不可。
6.2 技能质量等级：像开源项目一样演进
技能也应该分等级。我建议维护一个简单的等级标签：实验级（experimental）、稳定级（stable）、推荐级（recommended）。刚写的技能一律标实验级，经过回归测试、在多个场景中使用过，可以提升为稳定级；如果它被多个项目验证过，效果很稳定，就可以标为推荐级。
等级标签的价值在于：你在另一个项目里挑选技能时，能快速判断哪些是可信赖的，哪些还需要审慎使用。尤其是遇到"看起来能做但没写过足够测试"的技能时，这个标签能帮你做风险控制。
6.3 让Agent为技能库做贡献：自动化的技能沉淀
最后聊一个我自己正在尝试的前沿方向：让Agent在完成任务之后，自动总结经验并提出新技能的雏形。比如说，Agent今天完成了一个"员工入职材料审核"任务，流程跑得不错，它可以在总结阶段输出一个"技能提取建议"——里面包含这套流程的步骤清单、工具调用序列、输出模板，然后人工审核之后，把它正式加入技能库。
这种模式听起来很吸引人，但实际落地时还是要谨慎。因为Agent自产的技能描述经常存在两个问题：一是过度拟合当前任务，抽象不够；二是对适用场景的描述容易"自嗨"。所以我的建议是，把Agent产出的技能草稿当作"原料"，审核和加工环节必须有人类参与。技能库演进的引擎可以是自动化的，但方向盘必须握在人的手里。
从我做过的多个Agent项目来看，引入agent-skills这层抽象确实是项目走向工程化的分水岭。前期多花一点时间设计技能的结构和测试集，后期维护新场景的速度会快很多。如果你现在的Agent项目也已经陷入"提示词越改越多、行为越来越不可控"的境地，不妨试着把能力按技能拆一拆，你会发现整个系统的可维护性会有明显改善。
