写技能的时候，我踩过最大的坑就是把Agent的技能写得像教科书目录——条理清晰、面面俱到，结果Agent每次调用都犹豫不决，甚至把不相关的技能拼接起来，产出一堆莫名其妙的中间结果。后来我把整套“agent-skills”体系推翻重写，才慢慢摸清了门道。
先交代一下背景。我做的这套东西，本质上是一个给Agent装配“职业技能包”的框架。它要解决的核心矛盾是：底层大模型什么都懂一点，但什么都不精；遇到专业任务时，如果完全依赖模型自由发挥，输出质量就像抽卡。而一套精心设计的技能体系，相当于给Agent一本图文并茂的操作手册，告诉它遇到什么样的活，按什么流程干，调什么工具，产出什么格式，每一步的关键参数是什么。
这篇文章不聊花哨的概念，直接拆解agent-skills的骨架、实操过程和我在真实项目里趟出来的经验。如果你正在做Agent开发，或者被“Agent能力不可控”这个问题折磨过，这篇内容应该能帮上忙。
1. 项目整体设计与核心思路
1.1 技能不是指令，而是“可复用的能力封装”
刚开始接触Agent开发的人，很容易把“技能”和“提示词”混为一谈。觉得给Agent写一段详细的prompt，告诉它遇到问题怎么一步步做，就算是给Agent配技能了。这个理解方向对，但粒度差得很远。
我的实践结论是：技能（skill）不应该是写进系统提示词里的一段话，而应该是一个结构化的、可以被按需加载和调用的独立模块。它类似人脑海里的“工作程序”——你不需要在每次写代码前把“如何设计类结构”整个过一遍，你只需要知道项目需要什么，然后在合适的时候把对应的知识和方法调出来用。
在设计agent-skills时，我参考了前端工程里“组件化”的思路。每个技能像是一个独立组件，有自己的输入输出接口、依赖关系、版本信息和使用约束。Agent在做任务规划时，先看一眼任务目标，决定要调用哪些技能，然后按技能定义里写的流程去执行。
这里有一个很重要的设计决策：技能文件里的内容，不仅是给模型看的“说明书”，还是给调用方看的“契约”。也就是说，技能文件本身要能被程序解析，也要能被模型理解。双轨制是这套体系稳定运行的基础。
1.2 为什么选择文件目录式的技能组织方式
方案选型阶段，我有过几个候选方案：
- 把所有技能写在一个巨大的YAML/JSON配置里，启动时全量加载
- 用数据库存技能，运行时按需查询
- 把每个技能做成一个目录，目录里包含描述文件、提示词模板、工具调用配置等，运行时按需发现和加载
最终我选了第三个方案——文件目录式组织。原因很简单：一是可维护性好，一个技能对应一个目录，增删改都不影响其他技能；二是可读性好，整个技能库的结构一眼就能看懂，协同开发时不用借助额外的管理后台；三是与Git等版本控制工具配合得天衣无缝，每个技能的变更历史都清清楚楚，回滚起来方便。
这套方案还有一个意外的好处：技能的“热插拔”变得非常容易。我在多轮对话的场景里，根据用户意图动态决定加载哪几个技能目录，不相关的技能完全不进入模型的上下文窗口，这样既省token，又降低了模型“混淆工具用途”的概率。
1.3 技能体系的层次划分与职责边界
在agent-skills里，我把技能分成了三个层次，每层的职责边界定义得很清楚：
- 原子技能：完成一个不可再拆分的单一动作，比如“发送HTTP请求”“执行SQL查询”“计算两段文本的相似度”。原子技能通常对应一个具体的工具或API。
- 复合技能：把多个原子技能按业务逻辑串联起来，形成一个完整的工作流。比如“拉取网页内容并提取正文”“批量生成图片并打水印”。
- 策略技能：这一类是最有意思的。它不直接操作工具，而是决定“在什么条件下，用什么样的顺序和策略去组合使用下面的技能”。策略技能承载的是行业经验，比如“处理用户投诉时，先安抚情绪再定位问题”这类流程性的软知识。
这个层次划分的价值在于，责任清晰以后，调优就有了抓手。我的经验是：Agent表现不好时，先判断是哪个层次的问题。如果工具调用参数总是错，那是原子技能层的工具定义不清晰；如果步骤顺序总是乱，那是复合技能层的编排逻辑有缺陷；如果是面对模糊需求时不知道选哪条路径，那是策略技能层的决策规则没写明白。
提示：技能粒度不是越细越好。原子技能如果细到“点击某个按钮”，会让技能数量爆炸，规划开销大增；如果粗到“做一次完整的市场分析”，就又退化成提示词了。粒度把控的参考标准是——技能的执行结果是否具有明确的、可检验的完成标志。
2. 技能文件的结构设计与编写规范
2.1 一个技能文件的完整骨架
我的技能目录结构大致长这样：
skills/ ├── web_search/ │ ├── SKILL.md │ ├── tools.json │ ├── templates/ │ │ └── search_prompt.j2 │ └── assets/ │ └── example_output.json ├── data_analysis/ │ ├── SKILL.md │ ├── tools.json │ └── references/ │ └── metric_definitions.md └── customer_email_reply/ ├── SKILL.md ├── workflow.yaml └── examples/ └── good_bad_cases.md核心文件是SKILL.md。它是一份面向模型的主文档，统一使用Markdown格式，方便模型理解和解析。我习惯的字段包括：
name：技能名称，全局唯一description：用自然语言描述“这个技能解决什么问题、在什么场景下使用”，这段话就是模型做意图匹配时的依据when_to_use：明确列出“适用场景”和“不适用场景”，正反两面写，减少误调用workflow：核心执行流程，用编号步骤描述完整操作过程dependencies：依赖哪些原子技能或外部工具output_format：输出结构的规范说明
一个简单示例：
## name send_invoice_email ## description 根据订单信息和客户联系方式，生成发票邮件并调用邮件API发送。 ## when_to_use - 用户要求发送发票、账单或付款凭证时 - 订单已完成支付、需要把电子发票发给客户时 不适用场景： - 用户仅询问发票金额而未要求发送邮件 - 收件人信息缺失或不明确，此时应先向用户确认 ## workflow 1. 从订单数据库提取发票数据，校验发票号与金额 2. 使用 invoice_email_template 渲染邮件正文 3. 调用 sendgrid_send 工具发送邮件 4. 返回邮件发送状态和 message_id ## dependencies - render_template（原子技能） - sendgrid_send（原子技能） - order_db_query（原子技能） ## output_format 成功时返回 JSON： {"status": "sent", "message_id": "..."} 失败时返回错误码和人类可读的错误描述。2.2 description的描述质量直接决定调用准确率
这是我在实践中最深的一点体会：模型选择技能时，绝大多数情况是靠读description来判断“这个技能适不适合当前任务”。所以description写得好不好，直接决定了技能调用准确率的天花板。
什么叫写得好？两个标准：具体、有区分度。我见过很多人写技能描述时草草一句“用于处理数据分析相关任务”，这种描述放在一个技能库里跟没说一样。模型在多个技能之间犹豫时，越笼统的描述越容易造成误判。
我现在的写法是把关键细节前置，并刻意加入“限定条件”。比如同样是搜索类技能，我会区分成“web_search”和“document_search”两个技能，前者的描述强调“搜索互联网公开网页内容”，后者的描述强调“在用户已上传或系统知识库的文档内进行检索”。这样一来，模型根据输入特征就能做出明确选择，误调用少了一大半。
另外，在描述里写明“不适用场景”非常管用。Agent卡住然后强行调用技能的情况，大多是它判断不出边界。有了“不适用场景”的提示，模型在犹豫时更容易走向“请求用户补充信息”的正确分支，而不是瞎猜。
2.3 workflow的写法：基于“约束视角”而非“教程视角”
workflow段是最容易写崩的地方。我初版写技能的时候，这里写成了“步骤教程”，事无巨细地描述每一步的内部实现，结果模型执行时过于死板，遇到边界情况就罢工。
后来我把写法切换成“约束视角”——每一段步骤的核心是定义“这一步要求什么输入、要产出什么结果、完成标志是什么”，而不是“怎么做到”。相当于给Agent一个目标函数，而不是教它一步步走迷宫。
以“分析销售数据并生成报表”这个复合技能为例，初版我把workflow写成了：
- 读取CSV
- 用pandas做透视表
- 生成柱状图
- 导出PDF
换成约束视角后的版本是：
- 确认数据源路径和期望的分析维度，若用户未明确，先列出可分析维度清单请用户确认
- 生成包含汇总统计和至少一个趋势分析维度的结果，注意剔除异常值
- 产出结果为可阅读的报表文本，并附上对应的可视化文件路径
- 报表内容必须包含数据日期范围和数据来源，便于复查
两种写法最大的区别在容错性。约束视角允许Agent根据实际情况自己琢磨实现路径，自由度高了，对模型的推理能力要求也更高，但最终产出的质量反而更稳定，尤其是面对非标准化的输入时。
3. 实操环节：从零搭建一套可用的agent-skills体系
3.1 第一步：盘点原子技能，画清工具地图
搭体系不要直接从上层需求倒推，那样容易漏底层的支撑能力。我推荐的做法是：先把当前Agent所有能调用的工具、API、函数列一个清单，然后给每个工具写一张“能力卡片”。
能力卡片的内容很简单：
- 工具名称和一句话功能说明
- 输入参数列表，包括每个参数的类型、必填选项、取值范围
- 输出结果的结构
- 调用限制（超时时间、并发限制、费用参考）
- 错误码和常见异常
这一步的价值在于“盘点”。等清单完成后，你会对Agent的硬件能力有一个清醒的认知，哪些业务场景可以直接支撑，哪些场景需要组合多个工具，哪些场景存在能力缺口需要额外开发。我团队里有个伙伴把这步叫“画工具地图”，我觉得很贴切——工具地图是所有上层技能设计的基础。
3.2 第二步：面向典型业务场景，编写复合技能
有了工具地图，下一步是从真实业务场景出发，把高频的、重复性的工作流整理成复合技能。这里有个关键动作：复盘历史对话或历史任务日志，找出哪些流程是反复在做的，哪些步骤是固定不变的，把这些固定套路沉淀成技能。
我做过一个客服场景的Agent，刚开始完全依赖模型自由发挥，后来复盘了上百条真实对话，发现大约六成的任务能归类到五个高频场景里：查订单状态、处理退换货、解释价格差异、修改收货地址、催开发票。把这几个场景各自沉淀成复合技能以后，Agent的表现立刻稳了一大截，模型不再需要在每次会话里重新“发明流程”。
写复合技能时，我的建议是先把“happy path”走通，再慢慢补边界处理逻辑。不要一上来就想把所有异常情况写全，那样技能文件臃肿，模型反而抓不住主干。
3.3 第三步：设计技能的“触发协议”与上下文管理
技能文件写好后，还有一道关键工序：设置触发协议。我使用的模式是，在每一轮模型的最终回复前，增加一个工具调用决策节点。模型根据用户的最新输入和当前会话上下文，决定是直接回复、澄清问题、还是调用某个技能。
其中有一个优化细节很值得分享：技能的加载不是全量的，而是在触发后才把对应的SKILL.md内容插入到模型的上下文窗口里。这样做的目的是控制上下文长度。试想一下，如果Agent挂了200个技能，就算每个技能文件的平均token消耗是800，全量加载就是16万token，直接把上下文撑爆。改为按需加载后，每次会话只加载活跃的那几个技能，长上下文压力小了一个数量级。
触发协议的具体实现可以用一个函数调用的形式：
def select_skill(user_input: str, available_skills: list[str]) -> str | None: """基于用户输入与技能描述，选出一个最匹配的技能名。""" prompt = f"""根据用户输入，从以下技能列表中选择最匹配的一个技能。 如果所有技能都不适合，输出 None。 用户输入：{user_input} 技能列表： {available_skills} 只输出技能名，不要输出任何解释。""" response = llm_call(prompt, max_tokens=16) return response.strip() if response.strip() != "None" else None当然，这只是最简实现。真实场景中触发协议还要考虑会话历史、已加载技能的状态等。但核心思路不变：让模型做一个轻量级的“路由决策”，而不是每次都全量推理。
3.4 第四步：建立技能评测机制，持续迭代
技能写完不是终点，评测迭代才是常态。我给技能库配了一套最简单的评测方案：准备一组标准测试用例，每个用例包含“输入请求、期望调用的技能、期望的输出类型、关键的验收点”，然后每次技能定义有改动，就全量跑一遍回归。
这个流程初期投入的成本不小，但回报非常可观。尤其是当你改了某个原子技能的工具定义后，影响范围往往超出预期。没有回归测试兜底，线上Agent出现诡异行为你甚至不知道是哪次改动导致的。
4. 技能编排与多技能协作实战
4.1 当一个任务需要多个技能按顺序配合
真实任务极少是单个技能能搞定的，绝大多数需要多个技能有序配合。技能编排就是设计这些技能的协作路径。
以一个“自动整理竞品动态并生成周报”的场景为例。这个任务背后的技能编排路径是：
web_search：检索竞品相关的最新新闻和公告web_extract：打开高价值内容的URL，提取正文summarize：对每篇内容生成不超过200字的摘要weekly_report_merge：把多条摘要按竞品维度分组，输出结构化周报
这个流程看起来顺理成章，但如果让模型自由发挥，常常有意外事故。比如模型搜完直接开始写总结，跳过了正文提取环节，导致摘要内容基于搜索结果的只言片语；或者模型在搜索阶段就试图执行周报模板的格式，浪费了大量上下文。
解决这个问题的利器是“工作流约束”：在复合技能里，用明确的步骤列表把编排路径固定下来。模型不是不能发挥，而是只能在“流程固定、参数灵活”的框架内发挥。
4.2 策略技能：让Agent学会“分情况讨论”
比固定编排更进一步的是策略技能。它描述的不是一条固定的路径，而是一个“决策树”或者在多个路径间选择的规则。
举个例子，我做过一个“内容审核辅助”的技能。它的策略逻辑是：识别文本类型，如果是纯事实性陈述，直接走“事实核查”分支；如果包含观点性内容，走“标注观点来源”分支；如果两者混合，先拆解再分别处理。这种“分情况讨论”的策略，极大提升了输出与需求的匹配度。
写策略技能最大的心得是：别试图覆盖所有分支，只覆盖统计上最高频的那几个分支。长尾情况留给模型临场判断。这就像带新人，你把“正常情况怎么处理”讲清楚，剩下的让他自己体会，成长反而更快；你事无巨细把每种情况都规定死，新人反而畏首畏尾。
4.3 技能间的数据流约定
多技能协作时，数据格式的一致性往往是被忽视的坑。A技能输出的数据结构，B技能期望的输入结构，如果对不上，模型就得在中间做一层“格式转换”。转换一次两次没问题，转换多了，信息损耗和出错率都会上来。
我的做法是，在技能库的统一规范里约定公共的数据交换格式。比如所有检索类技能的统一输出都是：
{ "items": [ { "title": "标题", "url": "来源地址", "snippet": "摘要片段", "source": "来源名称", "timestamp": "ISO时间字符串" } ] }所有技能在设计阶段就要“对齐接口”。这跟前后端分离开发时先定接口文档是一个道理。省去了模型在中间兜圈子的开销，正确率提升立竿见影。
注意：技能间的“粘合逻辑”尽量放到代码里，而不是依赖模型生成。能用几行Python函数处理的数据清洗，就不要让模型来做。模型只做理解和决策，不做事无巨细的体力活。这是Agent工程与纯提示词工程最大的分水岭。
5. 常见问题与排查技巧实录
5.1 症状一：Agent总是选错技能
这是最让人头疼的问题，每次有90%的概率是description写得不够精准。排查方法很简单：把技能列表打印出来，把当前用户输入放在旁边，自己站到模型视角上选一次。如果你自己都觉得“两个技能好像都沾边”，那模型也会糊涂。
解决方向：
- 在description里强调触发场景的“强信号特征”。比如“当用户输入中出现‘订单号’时，优先考虑调用订单查询类技能”
- 在“不适用场景”里明确排除容易混淆的情形
- 如果两个技能的功能确实有重叠，考虑合并成一个技能，内部按参数分支
模型误选择技能的另外一个原因是技能库数量太大，超过了模型阅读全部的注意力范围。这种情况可以往技能库加一个索引层——一个精简的技能速查表，模型先读索引再决定到底加载哪个技能。
5.2 症状二：技能流程执行到一半就断了
我遇到过执行半路断掉的原因，大多出在“工具调用失败后的重试策略”上。Agent调某个API超时了，直接放弃了整个任务，也不告诉用户发生了什么。我一开始以为是模型能力问题，后来排查发现，是技能文件里漏写了“调用失败时怎么办”的兜底说明。
现在我的技能模板里，workflow的最后永远有一节“on_error”说明，明确每种常见失败类型对应的处理方案。比如“工具超时：重试最多两次，若仍失败，返回错误并建议用户稍后再试”。这种兜底说明对模型来说是一颗定心丸，它能区分“应该继续尝试”和“应该放弃并上报”，而不是在两者之间摇摆不定。
5.3 症状三：Agent打开技能文件后，上下文明显变长，响应变慢
技能文件过多或过长带来的性能损耗是真实存在的。我的处理方案有两个方向：
- 精简技能文件内容，把大段示例移到单独的references目录，主文档只保留核心信息。模型需要时可以按需查看子文件，这个策略类似代码模块的懒加载。
- 分级缓存：对已加载过的技能内容做会话级缓存，同一会话内多次调用同一技能不需要重复插入。
5.4 症状四：输出格式不稳定，有时候给JSON有时候给散文
这类问题八成是output_format没写死。我的经验是要多写一层“模板示例”。给出一段完整的示例输出，明确到什么字段、什么格式、甚至大括号和引号怎么放。模型看到具体示例时，模仿能力是远好于纯文字描述的。
另外每一步workflow里增加“本步骤产出物写入格式校验”也不算多余，尤其在关键节点上做一次格式校验，能及时拦截后续步骤的错误输入。
5.5 踩坑实录：一次因为“优先级冲突”引发的线上事故
最后分享一个印象深刻的翻车经历。有一版技能库里，我同时定义了“敏感内容检测”和“自动回复生成”两个技能，前者逻辑是“检测到不当内容立即拦截并上报”，后者逻辑是“对所有用户请求自动生成回复内容”。触发关系上，“自动回复生成”的适用范围写得太宽，结果Agent在检测到不当内容后，仍然先走了一步自动回复生成，把拦截结果给吞掉了，导致不合适的回复直接发出去了。
这个事故的根源在于：两个并列技能都没有声明“相对优先级”。之后我在技能定义里增加了一个priority字段，并约定：当两个技能的能力边界存在交叉场景时，优先级高的技能拥有决策权。这类“技能之间的冲突处理规则”是维护大技能库不能绕开的问题，越早设计越好。
一点个人体会
做了这么久agent-skills，最大的心得是：Agent的能力天花板，不在模型选得多大，而在你给它装配的技能体系有多扎实。技能不是一次性写完就完事的资产，它是需要随着业务演变持续迭代的系统。你观察Agent的每次失误，本质上都是技能体系里某个定义不够精准的反馈信号。把反馈回路跑起来，Agent的表现就会持续往上走。
这套体系目前支持了我的多个业务场景，从客服会话到内容生产到数据分析，覆盖了数百个技能定义。如果你正在搭建自己的Agent应用，建议从最小的场景开始，先沉淀三五个核心技能，跑通闭环，再逐步扩展。与其一开始就追求庞大的技能库，不如先把核心路径上的技能打磨到极致。
