最近前后左右都在聊 Agent但真把 Agent 跑起来的没几个。我问过几个朋友同一个问题同样的大模型为什么别人调出来的 Agent 看着又稳又聪明自己调的就像个只会复读机的人工智障后来我把他们的项目翻了一遍发现大多数人把精力都花在调 prompt、换模型、堆 RAG 上唯独漏了一件最关键的事——给 Agent 建一套标准化的“技能”。agent-skills 这个概念圈子里面已经聊了很久说白了就是给智能体配备一套可复用、可管理的能力库。它不是黑科技而是一套工程方法。这篇文章就把我从零搭建 agent-skills 的完整思考、踩坑记录和实操套路梳理出来给正在搞 Agent 应用的朋友做个参考。先说一个我观察到的现象。现在很多 Agent 项目看起来功能丰富实际拆开全是“一次性 prompt”。用户问什么模型临时生成一个答案回答完就算完事。这种模式最大的问题是什么上下文浪费和输出不稳定。举个例子你让 Agent 做一个竞品分析每次它都得从零开始组织结构、回忆分析维度、推测该看哪些数据。今天心情好多写两段明天上下文被无关内容挤占了就给你交个半成品。没有技能体系的 Agent就像让一个新入职的员工在没有任何操作规程经验参考的情况下直接接手核心项目——能做成什么样完全看运气。agent-skills 这套思路的核心就在于把那些高频、稳定、可迁移的“干活流程”沉淀下来变成 Agent 随时可以加载的标准化模块。我最初接触这个思路是从 Claude 的 Skills 功能开始的后来发现社区里已经有大量类似的实践本质都是一样的把“该怎么干活”的完整知识从对话的一次性内容里剥离出来做成 Agent 可以主动发现并按需加载的技能包。它解决的问题可以概括成三句话一是不再重复造轮子二是让输出质量下限明显抬升三是让 Agent 的能力边界变得可以预期、可以管理。下面我从设计思路、实操步骤到排障心得一步步拆开讲。1. agent-skills 的底层逻辑Agent 为什么需要“技能”而不是“更多 Prompt”1.1 从“会回答”到“会干活”缺的不是模型能力这两年模型能力进步是肉眼可见的推理、代码、长文本都越来越强。但注意模型强不等于 Agent 强。你用一个能力很强的模型做底座盲目给它一个复杂任务它未必能把事办得漂亮。为什么因为模型擅长的是单点推理和对话而“干活”需要的是流程控制、工具使用、结果校验、错误恢复这一整套东西。我做过一个实验。用同一个模型A 组直接让它“帮我写一份针对竞争对手某产品的深度分析报告”B 组先给 Agent 挂了一个技能包——技能包内明确规定了分析框架、需要采集的数据点、报告模板、命令格式。结果 B 组的输出结构一致性非常高关键数据点几乎没有遗漏A 组的输出则随机性很强报告格式每天一个样数据维度有时全有时不全。这个实验让我彻底想明白了Agent 的稳定性不是靠模型推理硬扛出来的而是靠技能系统兜底出来的。技能系统把“怎么做”的确定性提前固化了模型只需要负责在确定性的框架里做推理和填充难度自然下降稳定性自然上升。1.2 技能和 Prompt、工具、插件的边界到底在哪很多朋友对 agent-skills 的第一反应是这不就是变着法子写 prompt 吗有这个疑问很正常因为它们看起来确实有重叠。但如果你亲手搭过一个像样的技能包你就会明白边界其实很清楚。我常用这样一个比喻Prompt 是一条锦囊妙计用完就没了工具是一个扳手只干一件具体的事而技能是一条完整的作业流水线它内部集成了操作手册、质量标准、辅助工具、验收清单。为方便理解我整理过一个粗略的对比表形态生命周期颗粒度典型用途Prompt/指令单次对话最小临时让模型按某种风格或格式输出Tool/工具函数长期复用原子操作查天气、发请求、执行一段命令Skill/技能包长期复用可演进复合能力一套完整的任务处理流程可拆解可组合Workflow/工作流长期复用流程编排把多个技能按顺序组织成完整业务流程拿竞品分析这件事来说如果只是告诉模型“你来分析竞品”这是 prompt如果给模型一个“获取某公司官网信息”的函数这是工具但如果把“拆解分析维度 采集数据清单 报告结构 输出模板”打包在一起并注明适用范围和使用方法这就是一个标准的技能包。技能包是工具的放大器是 prompt 的系统化升级它让 Agent 不仅“知道怎么回答”还“知道怎么干活”。1.3 一个标准技能包的最小可运行结构我见过不少折腾 agent-skills 的人一开始就纠结平台级的复杂架构结果根本跑不起来。我的建议是先把最小可运行结构跑通。一个基本的技能包目录大概长这样competitive-analysis/ ├── SKILL.md # 核心技能定义元信息操作指导 ├── examples/ # 示例库给 Agent 的“参考答题卡” │ ├── basic-analysis.md │ └── edge-case.md ├── references/ # 参考资料模板、数据源清单、常见误区 │ └── report-template.md └── assets/ # 辅助资源命令脚本、配置、结构化数据 └── metrics.json这里面的关键点是技能包不是写给人类看的文档而是写给模型看的“任务说明书”。所以它的结构、措辞、示例方式都要围绕“模型能不能准确理解、能不能照着执行、能不能在必要时灵活调整”来设计。我见过很多人的技能包写得像公司内部 wiki满篇“我们建议”“原则上应”模型看了只会一头雾水。技能包的语言要像给一个聪明的实习生写任务简报清楚告诉他背景是什么、步骤怎么走、输出长什么样、哪些坑绝对不能踩。2. 手把手设计一个技能包从需求拆解到文档成形2.1 先明确“什么时候该用它”比什么都重要技能包里的元信息部分是整个技能包最容易写错、也最容易被忽略的。我说的元信息不仅是名字更重要的是“触发条件描述”。你可以把这段描述想象成技能包的“门牌号”——Agent 在接到任务时会先扫描所有可用技能的描述判断哪一个跟当前任务最匹配。如果这一步写得模糊后面内容再精彩也是白搭。打个比方。我给一个 Agent 配置了两个技能一个是“竞品分析”一个是“技术方案调研”。如果竞品分析技能的描述只写了“用于分析竞争对手”那遇到“帮我看看 XX 竞品的定价策略有什么变化”这种需求时模型可能会分不清该调用哪个。但当你把描述改成“当用户需要分析某公司/某产品的市场定位、定价、功能对比、渠道策略等竞争情况时使用特别适用于销售和产品团队的市场调研场景”模型的选择准确率会明显改善。写触发条件的时候我总结了三要三不要要写明典型场景和用户可能的问法不要只给抽象名词要说明边界——什么样的问题不该用它避免误调用要写清该技能区别于其他相近技能的差异点帮助模型做区分2.2 指令正文的写法既要有边界又要留空间技能包的核心是一份指令文档。这份文档的详略程度直接决定 Agent 输出质量。写得过于详细模型会变得机械丧失对特殊情况的应变能力写得过于粗略模型输出的稳定性又无从谈起。我试过很多种风格最后沉淀下来的口诀是定义清晰的步骤骨架留出灵活的执行空间。我用竞品分析技能举个例子。它的指令正文大致长这样# 竞品分析技能 ## 目标 产出一份结构清晰、数据支撑充分、决策导向的竞品分析报告。 ## 执行步骤 1. 识别竞品清单根据用户提供的领域、品类或目标公司列出主要竞品。 2. 确定分析维度至少覆盖产品功能、定价策略、目标客群、市场渠道四个维度。 3. 采集证据优先从可获取的公开信息中提取数据标注信息来源和时效性。 4. 分析对比做横向对比突出差异点。 5. 产出结论结论必须落在“我方应该如何应对”的决策点上。 ## 输出要求 - 报告必须包含“摘要”“维度对比”“关键结论”三个部分。 - 所有数据必须注明来源。 - 对比表格是必需项禁止只罗列文字描述。 ## 红线 - 禁止编造数据无法获取的数据明确标注“未能获取”。 - 禁止只做信息堆砌必须有分析和建议。你仔细看这个指令它规定了做什么、按什么顺序、绝对不能做什么但没有规定每一段具体怎么写也没有把所有可能的分析场景都列一遍。这就给了模型一个稳定的“操作轨道”同时在轨道内保留了发挥余地。我后来把这种写法推广到其他技能包里比如“数据清洗”“技术调研”“活动复盘”效果都很稳定。2.3 示例库给 Agent 的“参考答案”不能只给一个很多人在搭技能包的时候会轻视示例库以为放一两个例子意思意思就行。我把话说直白一点示例库的质量决定了 Agent 输出的下限。模型跟人一样你只给它看一种优秀示范它就只会机械模仿那一种你给它看多种不同情况下的示范它才能真正理解这个技能的精髓。以竞品分析技能为例我放了三种示例第一种是常规场景的完整报告示例覆盖所有标准维度让模型知道“标准答案”长什么样第二种是一个数据严重不足的“受限场景”示例里面大量用“未能获取”“暂无公开数据”等表述教模型在信息不完整时如何体面输出第三种是一个“反例”——一个信息堆砌、缺乏结论的报告并在旁边批注了问题所在。放反例这事是我自己实践出来的效果出乎意料地好。模型在看到了反例之后输出里堆砌信息的情况明显减少。它似乎学会了什么是“不想要的输出”这对稳定质量非常关键。2.4 辅助资源把脏活累活交给脚本模型只做判断技能包还有一个可选组件——辅助脚本。不要小看这个组件它是让技能包从“会说话”升级到“能办事”的关键。我把 Agent 的工作分成两类一类是思考判断比如数据怎么理解、结论怎么下另一类是机械操作比如抓网页、调接口、批量生成表格。后一类活儿让模型硬做容易出错性能也差。更好的做法是让技能包自带脚本模型只负责调度和解读结果。比如我在一个竞品数据采集技能里放了两个 Python 脚本一个负责从指定网址批量抽取结构化数据如产品名、价格、简介另一个负责把这些数据整理成标准 CSV。Agent 在处理任务时先调用脚本完成采集拿到结构化结果后再进行推理分析。这种方式有几个好处一是数据采集速度和准确性远超模型直接读网页二是模型的注意力可以集中在分析和判断上输出质量更高三是整个过程具备可复现性重跑一次结果一致。不过这里要提醒一句技能包里的脚本必须写清楚用法包括参数说明、依赖环境、输出格式否则模型调用的时候会一脸蒙圈。我最初不太注意这一点结果 Agent 经常拿着脚本不知所措后来我干脆在脚本文件开头注释里说得事无巨细问题才真正解决。3. 把技能交给 Agent目录结构、发现机制与调用编排3.1 技能文件放哪里直接决定 Agent 能不能“看得到”一个很现实的问题是你把技能包写好了但 Agent 根本不知道它的存在。这里涉及技能的“挂载”方式。不同平台的实现方式有差异但核心逻辑是相通的技能包需要被加载进 Agent 可感知的上下文或工具列表中。我最初的实践是在本地建了一个统一的技能目录比如放在项目根目录的skills/文件夹里每个子文件夹对应一个技能包。Agent 启动时会扫描该目录读取每个技能的元信息构建一个“技能索引”这样它才知道当前可用技能有哪些。这种方式的优点是直观、易调试缺点是如果技能数量多了索引本身会占用较多上下文。如果你用的是 Claude 这类产品可以把技能包放在系统提示词允许引用的路径下如果你用的是普通的大模型 API也可以把关键技能的指令内容以精简摘要形式拼进 system prompt把全文放在模型需要时可以“按需请求”的位置。不管用哪种方式我都会遵循一个原则Agent 必须能低成本地“发现”技能而不是凭着运气可能读到一份文件。3.2 技能清单和描述词优化让 Agent 一眼选中对的技能当技能库里的技能多起来以后Agent 的“技能选择”就会变成一个关键问题。我见过一个项目给 Agent 挂了十几个技能结果 Agent 每次选技能都跟抽签一样经常用错。排查下来原因很简单——技能描述写得太模棱两可模型根本分不清它们的边界。技能描述词就是技能包的“门牌”门牌写不清楚客人自然走错门。我后来花了一下午把每个技能描述都重写了一遍不只写“这个技能是干嘛的”还写“这个问题为什么适合它那个问题为什么不适合它”。比如收款数据整理技能描述里写明“适用于从银行账单、收款记录中提取结构化数据”同时注明“不要用于电商平台的订单统计那是另一个技能”。改完之后技能调用准确率从惨不忍睹的六成拉到了九成以上。这一个细节的收益远超我重新设计模型 prompt 的收益。3.3 多个技能之间如何协作任务拆解与顺序编排单个技能能解决的事终归有限真实世界里任务往往是多技能协同。拿“做一份周报”来说它至少需要三个能力从项目管理系统拉数据、把数据按逻辑组织成叙事、按模板输出最终文档。这三个能力就可以拆成三个技能数据采集技能、内容归纳技能、排版输出技能。任务编排这件事我一开始也想复杂了——以为要搞一个正式的 workflow 引擎。后来发现对大多数场景来说用一个“总控技能”就足够了。所谓总控技能就是一个大而全的流程指令它会告诉 Agent第一步调取哪个技能第二步把结果交给哪个技能第三步如何校验输出。总控技能相当于那个“包工头”负责拆活、派活、验收。这种做法的好处是非常灵活改流程只需要改总控技能不需要动底下的子技能。不过编排的时候要特别注意一个问题技能与技能之间的数据传递格式。比如采集技能输出的 CSV 格式如果跟分析技能预期的输入格式不一致中间就需要加一个转换步骤。我建议所有技能在输出部分都明确标注输出格式最好带上一个简单的 JSON schema 示例这样编排才能顺畅。4. 调优与排障实录技能不生效、输出不稳定、技能打架怎么办4.1 症状一Agent 完全无视技能包这是最常见的翻车现场。你费尽心思写了一个技能包结果 Agent 还是我行我素根本不按你的剧本来。遇到这种情况我的排查顺序很固定。第一确认技能包是否真的挂载成功——有时候文件路径配错了Agent 压根没读到第二检查触发条件描述是否足够明确——如果描述跟用户输入完全对不上模型也就不知道什么时候该用第三确认上下文容量是否够——Agent 如果上下文已经很拥挤技能内容只会被丢进“半读半忘”的状态。我在一个项目里折腾了许久最后发现就是技能包放的位置不在 Agent 的可见路径里文件根本没被加载。这种低级错误提醒我挂载机制永远比指令优雅度优先级更高。4.2 症状二技能被调用了但输出还是乱如果你的 Agent 已经会主动调技能说明机制跑通了但你可能会发现它输出质量依然不稳定。这里最可能的坑是技能包里的指令与示例不一致。举个例子指令里规定输出必须有数据来源标注但示例文档里没有一处在标来源模型就会优先模仿示例。所以技能包内部的一致性极其重要。我合并掉好几个矛盾技能包后输出稳定性会有直观提升。另外如果技能包内容太长模型在单次上下文中不能完整读完也会出现执行走样。我建议一个技能包的核心指令控制在 1500 字以内太长就得考虑拆分子技能。4.3 症状三多个技能之间互相干扰技能多了以后会有一个很微妙的坑模型有时候会把两个技能的内容混着用。比如说竞品分析技能和数据清洗技能同时加载模型可能在做竞品分析的时候突然执行了一堆数据清洗逻辑输出结构不伦不类。这个问题最典型的触发原因是两个技能包的描述边界模糊模型分不清什么时候该用谁。我解决的方式是在技能描述里刻意增加“互斥说明”比如分析技能里注明“本技能不做数据清洗原始数据应事先由清洗技能处理”模型在决策时自然而然就会理清边界。4.4 症状四某个技能改了一版之后Agent 行为明显漂移技能包不是写一次就完事的它需要持续迭代。但迭代有一个隐蔽的风险每改一次技能Agent 的行为模式就可能微妙地“漂移”一次——虽然你只是加了一句“注意使用最新的价格数据”结果模型可能把报告结构都改了。这事的本质是模型对技能内容的所有部分是一视同仁的你改哪句话它都有可能过度解读。我后来养成一个习惯技能包内容每个版本都做一次回归测试。准备几个固定的测试用例每改完一遍就跑一遍对比输出结构是否仍然稳定。如果漂移明显我会细化改动范围把改动局部化而不是大段重写。4.5 一套可复用的调试流程来来回回调了好几个月我自己总结出一套好用的调试流程分享出来给大家。第一步准备 5 到 10 个覆盖不同难度和场景的测试用例第二步任何改动先跑测试集记录输出结构和关键数据点完整性第三步针对失败用例单独分析判断是技能内容问题还是技能选择问题第四步修改技能后重新跑全量测试集。这套流程看起来麻烦但长期下来收益极大——它让技能库的迭代变得可量化、可观察再也不是凭感觉调参。5. 从“能跑”到“好用”技能库的分层、版本管理与长期运营5.1 技能库分三层通用层、领域层、临时层当你开始积累技能早晚会遇到一个问题技能太多了怎么避免臃肿。我现在的做法是把技能分成三层。第一层是通用技能比如“信息检索”“数据清洗”“结构化输出”这类技能适用面广几乎每个 Agent 都需要第二层是领域技能比如“竞品分析”“技术方案对比”“项目复盘”它们解决一类特定业务问题第三层是临时技能属于那种可能用一两次就闲置的一次性任务。这个分层解决的最大问题是上下文的“贫富不均”。通用技能和领域技能常驻在核心配置里临时技能按需临时挂载。如果一个临时技能用完发现它其实高频可用就会把它升级为领域技能。这样技能库既保持了精炼又能持续扩展。5.2 版本管理技能包也要像代码库一样审视技能包本质上是带逻辑的内容资产它需要像代码一样管理。我现在每个技能目录都是一个 git 库每个改动都走提交记录。有人可能会觉得小题大做但当你改了某个技能然后发现新版本让一个老业务场景输出变差你就能直接 diff 出是哪个改动出了问题。没有版本管理这种问题只能靠回忆来定位体验非常痛苦。5.3 把技能当产品经营用失败样本持续喂养技能包最后想说一个容易被忽略的点技能包应该是活的东西要用真实世界的失败样本持续喂养它。我每完成一个任务都会记录任务过程中 Agent 表现不佳的地方。攒到一定量我就会把这些失败样本汇聚成“反面示例”或者提炼成新的注意条款加进技能包里。这个过程本质上是在用真实反馈反向持续优化 Agent 的能力。我试过一段时间之后发现技能包每经过一轮“失败样本反哺”输出质量的下限就会被显著抬高。agent-skills 这套思路的奇妙之处在于它并不依赖某个特定的模型或者平台它是一套通用于所有大模型应用的设计方法论。你做的东西再小哪怕只是帮自己自动生成周报也能用这套思路让输出更稳定、更可控。做 Agent 难的不是把模型接进来而是把“能力”以可管理的形式沉淀下来。技能包正是这样一个把能力沉淀成资产的方式。