从给Agent加技能这个角度来写收到这类问题太多次了——模型推理能力越来越强但真让它干点具体活儿比如查个库存、算个报价、生成一份符合公司格式的周报它就开始发挥不稳定。问题不在模型本身而在我们只给了模型一张嘴没给它一双手。2025年Agent真正缺的不是更强的推理而是一套可复用、可管理、可评估的技能系统。这篇就以我从零搭建agent-skills的过程为线索把技能设计、注册、调用、治理的思路完整过一遍。1. 先搞明白agent-skills解决的是谁的痛点1.1 模型的满血与裸奔之间有很大落差先聊一个观察。过去一年我接触了不少团队大家做Agent普遍有一种错觉模型足够聪明给个API Key就能让它干活。真跑起来才发现模型只是一个“很会说话的大脑”它如果想要完成一个业务流程比如自动把客户邮件里的询价信息提取出来回填到CRM系统根据销售数据生成一份多维度周报还要按公司模板排版接到工单后自行查知识库、翻历史记录、调监控接口最后输出一段诊断结论。没有预先准备好的动作序列和领域知识模型就会陷入“意图明确、执行拉胯”的状态。它知道该干什么但不知道怎么干——不知道调哪个接口、参数填什么、数据格式长什么样、失败重试的策略是什么。这就是我理解agent-skills的起点技能是模型与真实世界之间的标准化能力层。它把会做什么和知道怎么调用彻底分离。模型负责在合适时机选择合适的技能剩下的执行细节全部交给技能本身。1.2 每个人都在重复造轮子技能就是那个轮子我最初动手做这套东西是因为团队里三个项目同时在写调用公司内部工单系统的代码。每个人写法不一样错误处理不一样参数命名不一样更可怕的是文档还各写各的。后来一查上游接口都换了版本三个人写出来的代码全挂。这件事让我下定决心凡是高频、有边界、可复用的事一律沉淀成技能由统一机制管理。这也是为什么现在各个大厂和开源社区都在推Agent技能库——包括Claude推出的Agent Skills、OpenAI的GPTs Actions、LangChain的工具封装等。核心思路殊途同归把能力标准化、模块化、可复用。1.3 什么算技能什么不算技能为了让讨论有边界我给自己定了一个判断标准有明确输入输出:比如输入PDF文件输出提取后的结构化文本有可复现的调用逻辑:不是一次性的Prompt技巧而是有代码、有API、有完整逻辑链路的动作有独立的可测试性:能给技能写单元测试能单独跑通有可观察的失败模式:技能挂了要有清晰的报错、日志和手工兜底方法。满足这四条我才会把它规划成一个技能。至于那些帮我写一段文案分析一下这个数据的泛化需求本质上是模型推理能力不需要做成技能直接靠Prompt就够。2. 技能和工具、插件、工作流的边界概念不清是最贵的坑2.1 工具是点技能是动作链这是我在项目里反复给团队讲的一张图。工具Tool通常是单一能力比如发一封邮件查一条数据库记录技能Skill则是围绕某个目标组织起来的一组能力里面可能包含多个工具的调用顺序、决策逻辑和异常处理。举个例子邮件相关技能不是简单封装一个SendMail接口而是包含判断邮件是回复还是新发起提取收件人、抄送人、优先级根据上下文自动生成摘要和正文草稿调用SendMail工具发送发送失败时根据错误码进行重试或转人工。也就是说技能是思维链路工具执行的组合体。仿照人类的经验我们开车不只是踩油门而是包含观察路况、判断距离、控制速度、预判风险的一整套动作。2.2 插件偏框架技能偏资产好多人把插件Plugin和技能混着用。我理解的区别是这样的插件是Agent运行时的扩展框架它定义了一套接口规范让外部能力能被加载进来技能是可被复用的能力资产它不关心宿主是哪个框架只要能把这个能力标准化表达、便于调用。一台终端设备可以插很多插件但真正让设备值钱的是你到底掌握了哪些技能。插件是渠道技能是内容。两者有交集但不能划等号。2.3 工作流是剧本技能是演员还有一个常被混为一谈的概念是工作流Workflow。我用个比喻工作流是把整个流程写死第一步做什么第二步做什么每个步骤之间是什么顺序技能更像演员的素养我们给演员一套标准的镜头前表演技能但具体每一场戏怎么演是导演Agent临场发挥决定的。复杂业务需要两者配合工作流保证流程不漏技能保证执行到位。但它们的定位不同不能直接互相替换。3. 从零搭建技能库一份可以照抄的设计方案3.1 技能注册表让能力变得可发现、可管理我先说结论任何技能库的第一件事不是写代码而是设计一份技能注册表。这是我踩过坑之后的总结。技能注册表本质上是一份结构化描述文件包含技能ID和名称适用场景和触发条件需要的输入参数和约束执行步骤摘要依赖的工具/服务/接口错误码和兜底策略版本号、维护人、最后更新时间。用它对Agent做技能路由再合适不过。Agent先看注册表判断当前用户请求匹配哪个技能再拉取对应技能的详细定义去执行。3.2 技能技能的拆分粒度粒度太粗太细都难受拆分粒度是我反复调整了很长时间才基本稳定的点。经验法则有三条一个技能只解决一类完整问题不要拆到接口级别技能内部允许包含多个子步骤但每个子步骤尽量复用已有工具技能之间尽量不互相调用——如果需要互相调用考虑是不是应该合并或者抽公共子技能。举个例子财务场景下生成报销单是一个技能它内部会调用识别发票查询员工信息生成PDF等工具但这些都是内部实现不对外暴露为独立技能。如果哪天识别发票也要给别的技能用再把它单独升级为公共子技能。3.3 技能的输入契约别让模型猜参数我发现很多Agent方案挂就挂在参数上。模型不是万能的你不能指望它知道员工id要从哪里取日期格式必须是YYYY-MM-DD——这些都是隐性约定模型根本猜不到。所以我在设计技能注册表时大幅强化了输入契约的定义。包括每个参数的格式、枚举、默认值参数之间的依赖关系比如如果填了项目ID则部门ID可以省略参数来源建议比如从用户上下文中提取从上一流程输出中获取必填和选填标识以及缺失时如何处理。这一层看似繁琐实际作用巨大它能直接提升Agent首次调用的成功率减少无意义的试错。3.4 技能评估没有指标等于盲人开车技能是好是坏不能靠感觉我建立了一套粗颗粒但有效的评估机制调用成功率技能内部各步骤是否顺利完成有无异常用户满意度技能产出是否被用户接受比如用户是否在聊天里点头确认、是否继续追问资源消耗调用耗时、token消耗、API调用次数维护成本技能定义变更频率、错误工单数量。用表格记录每次迭代的指标变化再决定是否调技能逻辑。这样做的好处是技能库不是越堆越多而是越来越精。4. 实战让Agent真正会干活的技能注册与调用实现4.1 定义一个技能以生成项目周报为例纸上谈兵没意思我直接给一个实际跑通的例子定义一个生成项目周报的技能。技能目标是根据项目成员的工作日志、任务管理系统的状态、里程碑进度生成一份符合团队模板的周报Markdown文件。我先在技能注册表里登记技能ID: weekly-report-generator 触发条件: 用户要求生成某项目某周的周报 输入参数: - project_id: string, 必填 - week_start: string, 选填, 格式YYYY-MM-DD, 默认本周一 - template_id: string, 选填, 默认standard 执行步骤: 1. 调用任务系统API拉取该项目本周任务 2. 调取工作日志系统汇总成员提交记录 3. 拉取里程碑/迭代进展 4. 使用模板填充生成Markdown 5. 保存到指定目录并返回文件路径 失败兜底: - 任务系统无数据 - 标记warning仍生成周报的数据缺失版本 - 工作日志为空 - 跳过该板块并提示4.2 技能描述文件怎么写模型才能看得懂注册表里登记完成还不够还需生成一份面向模型的技能描述文件。这玩意模型会直接读到所以写得越具体越好。我一般会写清楚技能是什么一句话;什么时候使用触发场景示例;什么时候不要用反例避免模型误触发参数说明和示例值返回结构说明常见错误及处理方法。描述文件我会放在技能的根目录比如SKILL.md模型在判断是否调用、怎么调用时都会先看它。别小看这段自然语言它决定了模型能不能正确地想起这个技能。4.3 内部执行逻辑把杂活封装成稳定函数技能真正执行的部分是后端代码通常是一个Python函数或REST接口。在这个例子里我封装了类似如下的执行逻辑def generate_project_weekly_report(project_id, week_startNone, template_idstandard): if week_start is None: week_start last_monday() tasks fetch_tasks(project_id, week_start) logs fetch_member_logs(project_id, week_start) milestones fetch_milestones(project_id, week_start) report_data build_report_data(tasks, logs, milestones) markdown render_with_template(template_id, report_data) save_to_knowledge_base(fweekly_report/{project_id}/{week_start}.md, markdown) return {path: markdown_path, summary: report_data.summary}这里最重要的是异常处理的颗粒度。我只在关键节点做异常捕获比如任务系统不可用时不会让整个技能崩溃而是降级继续生成部分报告并在结果里明确标注数据缺失。这样Agent拿到结果后可以向用户说明这周的数据有一部分没抓到你可以人工补充而不是让用户面对白屏或者完全失败。4.4 模型侧的调用逻辑技能选择、参数提取与结果消化代码写好了描述文件也写了模型究竟怎么调我在实际项目里让Agent先根据用户请求对照技能注册表做技能匹配匹配到之后有两个重要步骤参数提取从对话上下文抽取project_id、week_start等参数。这时候我发现聪明的做法是给模型一个参数提取示例而不是让它自由发挥。比如示例里明确写用户说给我上周A项目的周报项目ID对应A上周要换算成具体日期。结果消化技能返回的不只是文件路径还有一段结构化摘要。Agent需要把这段摘要翻译成用户能直接看懂的话比如你项目的任务完成率是85%但里程碑B延期两天详见附件”。如果你期望Agent直接渲染大段Markdown那基本就是灾难用户的屏幕会刷出一片不知道是报告还是代码的东西。4.5 多技能协同的初步实践单技能玩熟之后我开始让几个技能串起来跑。以客户投诉自动处理为例它拆成了三个技能投诉信息提取技能从邮件或聊天记录里提取投诉内容、客户ID、关联订单订单查询技能查订单状态、物流信息、历史沟通记录回复生成技能根据投诉上下文和政策模板生成安抚回复。这三个技能由Agent按顺序调用每个技能的输出作为下一个技能的输入。实现上不复杂但体验一下子质变了——投诉处理不只是回一句话而是能真正定位问题、给出解决方案建议。当然跨技能的状态流转需要设计好数据结构和中间格式否则容易在各环节之间丢信息。5. 上线之后才是开始技能库治理的几个实操心得5.1 技能冲突与重复建设的预防机制技能库一大最怕的是重复造轮子。今天A组建一个读取Excel表格技能明天B组又建一个解析xlsx技能后端逻辑一模一样。长此以往维护量翻倍模型选型也混乱。我的对策是在注册表层面增加相似技能检索环节新技能提交之前必须先检索现有技能库如果发现已有类似技能可以选择增强而不是新建。这里不仅仅是管理流程更重要是技术上的索引与查重。因为技能描述是自然语言可以用向量相似度检索省去大量人工比对。5.2 权限和边界技能不是给模型无限开火权技能给Agent带来很强执行力同时也带来很大风险。我始终坚持三条安全底线技能分级只读类技能、普通写操作技能、高影响技能如发邮件给全员、修改正式订单、取消会议分开管理。高影响技能默认需要二次确认甚至管理员审批调用留痕每个技能每次调用都要记录调用人、时间、参数、结果。不单纯为了审计也为了出问题时的排错依据回归测试技能库更新后我会跑一遍预置的回归用例防止某个技能改动影响了其他技能。Agent能力越强越需要一个好的护栏。5.3 版本管理与回滚机制技能不是一成不变的上游接口会变业务逻辑会调模板会换。如果技能没有版本概念就会出现谁动了我的周报格式这一类混乱。我目前采用的是轻量级版本管理技能定义文件和代码都进Git仓库每次改动打上版本号每个技能运行时会记录使用的版本发布流程分为开发版和稳定版开发版测试通过后晋升为稳定版稳定版由线上Agent默认采用一旦线上出了问题支持一键回滚到上一个稳定版。这样一来哪怕是团队里的小朋友改错了参数也只影响开发版不会把线上搞挂。回滚成本极低大家也就更敢于快速迭代和试错。5.4 技能运行的可观测性日志、指标与排错这一部分技术含量不高但直接决定运维体验。我把每个技能封装成统一接口自动注入调用的元信息时间戳、调用方、输入输出摘要、耗时、成功状态统一写到日志系统里。遇到一个典型的排障场景某天用户说技能偶尔会卡死。如果只是白盒代码测试很难复现但查看日志后发现卡死一般发生在某个外部接口超时且重试机制缺失时。定位到原因后我在技能描述和执行函数里补上了外部接口超时按3秒处理重试2次仍失败则降级返回部分结果的逻辑问题从此消失。这不是什么高深技巧但很多人搭建技能库只关注代码跑通完全没考虑线上怎么观察它跑得好不好。从我做这套系统第一天起就一直把可观测性摆在前面代价是前期多一点编码量但后期节省的排障时间远远不止。6. 往深走一步技能化的组织知识沉淀与个人竞争力6.1 技能库是组织知识的活体存档前面讲的都是工程细节但我觉得做agent-skills真正的红利在于知识留存方式的改变。过去公司做知识沉淀无非写文档、做Wiki、建培训视频。结果如何文档写完之后基本就躺在那里没人读更没人用。但技能库不一样它是把怎么做一件事编码成可执行的行为模式而且能被Agent实时调用。比如团队里资深销售有一套判断商机是否值得跟进的经验传统做法是写成PPT培训新人效果可想而知如今可以做成技能——把评分标准、查询项、决策阈值封装成可执行的评估函数模型在识别到相关场景时直接调用。技能一旦被Agent在生产环境里反复使用它就是活的会随着业务变化而迭代。它比任何静态文档都更接近团队真正的做事方式。6.2 技能设计与领域梳理是Agent时代的核心竞争力别急着去学Prompt的花活也别只盯着模型榜单。我现在更看重的是团队里有几个人能把自己的领域经验结构化、标准化拆解成一个个能被Agent理解和执行的技能。这要求的不只是工程能力更需要对业务有深刻理解以及很强的抽象能力。会把事说清楚的人在这个时代极其稀缺。当你把一个复杂场景拆成一套技能真的是把一个人或一个团队的能力变成了组织资产。这件事做得好不好决定了Agent的上限也决定了你在团队里的稀缺性。6.3 几个可以立刻上手的小建议如果看了这篇也想动手我给几个切实可行的起步建议别一上来就all in框架。最先做的是盘点团队高频重复、有标准操作流程的场景把它们写成流程说明先用最简单的注册表脚本实现技能调用不要过早引入复杂编排引擎从一个小技能跑通闭环比如自动生成日报观察Agent调用、执行、出错、兜底的全过程找手感刻意做一次技能评估跑上一周记录成功率、失败场景、用户反馈再迭代一版你很快就知道这个系统能不能在团队推广。只要过了从0到1这个坎后面的路就会越走越顺。