做AI Agent这一年多我最大的感受是能让Agent真正“靠得住”的不是更聪明的思考链也不是堆更多工具而是一套把能力沉淀成标准件的机制——agent-skills。这个说法在圈子里越来越流行它不是什么新算法而是关于“怎么给Agent封装可复用、可验证、可编排的能力模块”的一套实践。今天我就把自己从零搭建Agent技能库的完整过程写下来从设计思路到代码实现再到上线后踩过的坑一次讲清楚。这篇文章适合正在做Agent应用、尤其是感觉“模型什么都会但一做事就翻车”的朋友。1. 为什么需要Agent Skills先从一个失败案例说起1.1 大模型Agent的三个老毛病先说我最早做的一个内部运维助手。需求很简单让Agent根据用户的一句话自动检查服务器状态、分析日志、执行一些常规运维操作。当时我很天真觉得GPT级别的模型理解自然语言、写点代码都不在话下做一个“能动手的助手”应该不难。结果一上线就暴露了三个非常典型的问题。第一是规划不稳定。同一个问题今天它知道先查磁盘再查进程明天可能就反过来先跑了一堆无关命令。你问它“服务器是不是快满了”它可能先去查CPU占用再去查网络连接绕了一大圈才回到磁盘。倒也不是不能跑但每次执行的路径都不太一样你很难跟别人说“这个功能已经稳定了”。第二是上下文爆炸。Agent每调用一次工具工具返回的结果都要塞回对话里。运维场景里一条df -h返回几百个字符还算好的journalctl一条日志刷下来就是几千行模型既要读懂这些内容又要在后续的对话里继续记住之前的计划几轮下来上下文窗口就吃紧既慢又贵。第三是错误恢复能力几乎为零。模型调工具参数传错是常态。端口号写成了字符串、服务名拼错、路径不存在……一旦工具执行失败模型往往不是去修正参数重试而是开始“编造”一个看似合理的结果硬着头皮继续往下走。这在对话场景里只是有点蠢在运维场景里就是事故。这三个问题不是模型能力不够造成的而是架构问题Agent把所有能力都揉在一个巨大的“思考-行动”循环里缺少一个中间层把“会做的事情”显式地、稳定地定义出来。Agent Skills解决的就是这件事。1.2 Skill化之后变化发生在哪一层Agent Skills的思路说穿了并不复杂把Agent能执行的每一个原子能力比如“查磁盘使用率”“查指定端口连通性”“按关键字过滤日志”封装成一个独立的、带描述的、有输入输出契约的模块这个模块就叫一个Skill。Agent在运行时不直接面对一个个裸函数而是先看到一个“技能清单”根据用户需求决定调哪个Skill再由Skill内部去完成具体的工具调用和数据处理。这个分层带来的变化是结构性的。以前模型面对的是“一堆函数自由发挥”现在面对的是“一组能力卡片明确的调用规则”。模型需要做的决策从“怎么一步步实现”变成了“我要选哪个能力”复杂度降了一个量级。而真正怎么实现、怎么处理异常、怎么解析结果这些脏活累活被装进Skill内部可以由工程师用传统代码去保证质量。我把这套机制落地之后之前的三个问题有了明显改观执行路径稳定了因为每个Skill是一个固定流程上下文瘦身了因为返回结果可以在Skill内部先做结构化摘要错误恢复靠谱了因为Skill内部可以写重试、校验、降级逻辑而不是指望模型临场发挥。下面我会逐个拆开讲清楚一个Skill内部到底应该有什么以及怎么从零把它实现出来。2. Agent Skill到底长什么样拆开看它的四个组件2.1 能力卡片名字、描述与触发条件一个Skill首先要有一个明确的“身份”。我在系统里给每个Skill维护了一张能力卡片包含四个字段名字、一句话描述、适用场景、示例请求。名字要短描述要说清楚“这个Skill能干什么”适用场景要写清楚“用户在什么诉求下应该调用它”。这里最容易犯的错是把描述写成实现说明。比如“inspect_server”这个Skill最早我写的描述是“使用psutil检查服务器磁盘、CPU、内存”后来发现模型经常不调用它因为用户不会说“请使用psutil检查磁盘”用户只会说“看一下服务器还有多少空间”。换个说法描述改成“检查服务器磁盘使用率、CPU负载、内存剩余以及正在运行的进程适用于用户询问服务器资源状况的场景”命中率立刻高了不少。为什么会这样因为模型的意图匹配是语义层面的它根据你给的描述去判断“当前用户的请求是否落在这个能力范围内”。描述越接近用户真实问法匹配越准。所以能力卡片本质上是在替模型做“路由信号”写得好不好直接决定了Skill会不会被正确唤起。我还习惯在描述里放一个示例请求比如“用户说帮我看看服务器是不是要满盘了”相当于给了模型一个锚点实测下来对召回率提升非常明显。2.2 输入输出协议给Agent一把“合规”的钥匙第二件事是定义输入输出协议。Agent调用Skill本质上是一个函数调用输入必须是结构化的、可校验的输出必须是稳定的、可解析的。我在每个Skill里都用一套类似JSON Schema的格式定义输入参数包括每个参数的类型、是否必填、取值范围、默认值。例如“查端口连通性”这个Skill输入协议可以定义成这样{ type: object, required: [host, port], properties: { host: {type: string, description: 目标主机名或IP}, port: {type: integer, minimum: 1, maximum: 65535}, timeout: {type: integer, minimum: 1, maximum: 30, default: 5} } }输出协议也类似规定返回JSON必须包含哪些字段。我的习惯是统一返回三件套status表示执行结果状态data表示结构化的核心结果message表示给人看的摘要文本。这个统一的输出格式非常关键因为Agent拿到结果后需要把data转成自然语言回复用户如果每个Skill返回的字段都不一样下游解析逻辑会变得非常痛苦。有人可能觉得定义输入输出协议是小题大做但实际项目里模型生成Json参数时经常出现类型错误、字段名拼写错误、枚举值越界。有了协议之后我会在Skill入口处做严格校验不合法就直接返回一个“参数错误”的结构化提示让模型根据提示修正后重新调用。这比让模型在长对话里自我纠错要快得多也稳得多。2.3 执行器能跑路的代码而不是漂亮的描述能力卡片和协议解决的是“模型怎么理解Skill”真正干活的其实是执行器。执行器就是一段普通的代码可以在里面调用系统命令、访问数据库、请求外部API、做数据清洗什么都行。关键是它要完全可控、可测试不依赖模型临场发挥。我在实现执行器时有几条硬性约束。第一执行器内部不允许调用大模型所有逻辑必须是确定性的这样同样的输入永远有同样的输出排查问题才容易。第二执行命令时一定要设置超时时间像执行ping、traceroute这类命令一旦网络故障可能会卡很久有一个硬超时兜底Skill才不会拖垮整个Agent循环。第三执行器要能捕获底层异常并把异常转换成标准错误码返回而不是让异常穿透到Agent主流程里。拿服务器巡检场景举例磁盘检查这个Skill的执行器核心逻辑就是调用psutil.disk_usage拿到分区的总量、已用、可用空间然后计算使用率再根据使用率阈值比如80%、90%给出健康状态标签。这一层完全是用经典编程实现的不涉及任何模型推理自然也不存在“幻觉”的问题。所有不确定的部分都被关在笼子里这恰恰是Skill机制最有价值的地方。2.4 回退与错误处理Skill也要有“B计划”最后一个经常被忽略的组件是错误处理和回退策略。一个Skill如果没有想过“失败了怎么办”那它在真实环境里一定会失败得很惨。我在每个Skill里都内置了三级失败处理。第一级是参数校验失败。这种情况通常是模型生成的参数不合法Skill直接返回“参数错误具体原因”不执行任何实际操作。第二级是执行超时或外部依赖失败比如目标服务器连不上、API接口返回500这时会有一次自动重试重试间隔按指数退避仍然失败就返回一个明确的错误信息。第三级是结果不合理。比如查磁盘得到了一个明显异常的数据负数、NaN、空值Skill会在返回前做一次合法性检查宁可告诉用户“数据异常”也不要把垃圾数据交给Agent去编故事。我在实际使用中补了一个很重要的经验回退策略里不要写过于复杂的“自动修复”逻辑。早期我总想让Skill在失败时自作聪明地换个命令再试结果引入了一堆难以预期的分支线上问题反而变多了。现在我的原则是Skill失败要有明确响应但它不需要“伟大”把“失败”如实地、结构化地告诉Agent让Agent决定是换一个Skill还是向用户解释这才是职责清晰的架构。3. 手把手实现一套可用的Agent Skill以服务器巡检为例3.1 先写规格说明书把模糊需求翻译成可执行边界我习惯在写代码之前先给每个Skill写一份极简的规格说明书把需求翻译成可执行的边界条件。这一步看起来是文档工作但实际上是最重要的一步因为很多项目到后面都是炸在“需求边界不清晰”上。以我的“inspect_server”巡检Skill为例规格说明书长这样名称inspect_server输入可选的host参数默认本机、检查项列表disk、cpu、memory、process默认全部输出每个检查项的健康状态、核心指标数值、简要结论文本成功条件所有检查项在超时时间默认10秒内拿到结果并格式化输出失败条件目标主机不可达、某个检查项执行异常、结果数据合法性校验不通过权限范围只读操作不包含任何修改类动作如重启服务、删除文件写这份规格说明书的过程其实就是在逼自己想清楚两件事一是这个Skill到底能做什么、不能做什么二是Agent在什么情况下应该调用它、什么情况下不应该。边界定得越清楚后面写代码、写描述、写测试就都顺了。权限范围尤其值得重视最开始的巡检Skill我塞了一个“重启服务”的功能进去后来发现模型在用户一句“让系统跑快点”的模糊请求下真的会去调重启服务的Skill吓得我赶紧把它拆成了独立的、需要二次确认的高危Skill。3.2 代码实现Skill目录结构、注册表与执行器规格说明书就位之后代码实现其实是很标准的工程活。我采用的目录结构如下skills/ inspect_server/ SKILL.md execute.py requirements.txt tests/ test_execute.py port_check/ SKILL.md execute.py ...每个Skill一个目录目录里必须有一个SKILL.md作为能力卡片和协议描述一个execute.py作为执行器入口。整个Skill系统的核心是一个注册表模块它在启动时扫描skills/目录下的所有子目录加载每个Skill的SKILL.md把能力信息聚合起来传给Agent同时把执行器函数注册到一个字典里key是Skill名称value是执行入口。SKILL.md的内容其实就对应我前面说的能力卡片加输入输出协议用Markdown写成结构化文档。系统提示词里只需要保留一份“技能清单摘要”让模型知道有哪些Skill、每个Skill是干什么的就足够触发正确的调用决策了。这样做的好处是新增一个Skill不会增大主提示词只会增加一行技能摘要上下文占用增长非常有限。执行器层我习惯统一暴露一个入口函数接收解析后的字典参数返回标准格式的JSON。内部再按检查项拆分具体逻辑每个子功能一个独立函数方便单测。这里贴上磁盘检查的核心代码片段import psutil def check_disk(threshold_warn: int 80, threshold_error: int 90) - dict: 检查本机所有分区的磁盘使用情况 results [] for part in psutil.disk_partitions(allFalse): try: usage psutil.disk_usage(part.mountpoint) except PermissionError: continue percent usage.percent if percent threshold_error: status error elif percent threshold_warn: status warn else: status ok results.append({ mountpoint: part.mountpoint, fstype: part.fstype, total_mb: round(usage.total / 1024 / 1024, 1), used_mb: round(usage.used / 1024 / 1024, 1), free_mb: round(usage.free / 1024 / 1024, 1), percent: percent, status: status }) return {status: ok, data: {disk: results}}这段代码本身平平无奇但它体现了一个关键点Skill的价值不是“用AI实现”而是“把AI要做的复杂决策变成一次简单的函数调用”模型不需要知道分区、文件系统、挂载点这些概念它只需要传一个“检查磁盘”的意图剩下的全部交给确定性的代码去完成。这才是Skill跟“让模型自由操作工具”最本质的区别。3.3 让Agent学会调用系统提示词里的触发规则代码写完了接下来要让Agent真正学会在合适的时机调用Skill。这里有一个很容易被低估的环节系统提示词里关于Skill的描述怎么写。我踩过的一个坑是“情绪化描述”。早期我给某个Skill写了一句“当用户提到服务器很慢时可以调用此Skill诊断”结果模型真的只在用户说“慢”的时候才想起来用用户换了个说法比如“卡顿”“响应半天没反应”它就不调了。后来我改成“当用户反馈系统性能下降、页面加载缓慢、服务无响应、运行卡顿等任何疑似资源不足或异常的情况时应调用此Skill进行巡检”召回率立刻上来了。另外我还会在系统提示词里强制规定两条规则。第一满足触发条件时必须调用Skill不允许自己观察自己回答需要数据支撑的话一律以Skill返回为准。第二一次只能调用一个Skill等结果返回后再根据结果决定是否调用下一个。这个限制有些反直觉但非常有效它避免模型自作主张地“并行调用”多个Skill导致中间状态混乱。实际上等到跑通之后再放开“多Skill协同”也不迟但初始阶段一定要收敛住。还有一个小细节系统提示词里每个Skill的摘要描述不要直接从SKILL.md里整段复制因为SKILL.md通常包含给工程师看的实现细节而提示词里只需要给模型看的“调用指南”。我把这两份描述拆开SKILL.md里放完整版提示词里放精简版每个Skill不超过两行。这样既保证了模型能准确做路由又不会让主提示词变得臃肿。3.4 上下文瘦身与并发控制上线前的最后一公里最后一个环节是性能与资源控制这决定了Skill系统能不能在真实业务里长期稳定跑下去。先说上下文瘦身。Agent一次任务里可能会调用多个Skill如果每个Skill的原始返回都是一大坨数据多轮下来上下文还是会膨胀。我的做法是在执行器内部增加一个“摘要模式”默认情况下Skill返回给Agent的不是原始数据而是经过压缩后的结论摘要。比如磁盘检查原始数据可能是几十个分区的完整列表但Agent真正需要的可能只是一句话“根分区使用率92%已达危险级别”。我会把详细数据放在返回结果的detail字段里但在message字段里生成一句精简摘要并在协议里要求Agent优先基于message做回复。这样长期跑下来上下文占用能压缩掉一半以上。至于并发控制主要是避免多个Agent任务同时执行某些重型Skill时把下游系统打爆。我的做法是给每个Skill加一个简单的信号量限制比如“inspect_server”同时最多允许3个实例执行超出的请求直接排队或返回“系统繁忙”。这个策略不复杂但在生产环境里非常管用。另外所有执行器统一走一个执行超时配置默认单次不超过15秒超过就主动中断并返回超时错误。没有这道闸某些卡死的系统调用会无限期拖住整个Agent的请求。4. 调试、评估与避坑让Skill真正可交付4.1 离线回放用真实轨迹验证Skill边界Skill写完之后最忌讳的是直接上线。我这里的经验是先做一轮“离线回放”把历史上真实用户和Agent的对话记录找出来重新跑一遍看新增的Skill能不能被正确唤起、返回的结果是不是符合预期。怎么操作呢我会把历史对话里用户请求对应的输入采集出来做成一个数据集每条数据标注清楚“期望调用哪个Skill”和“期望输出什么结果”。然后写一个脚本用当前系统重新跑一遍自动比对实际输出和期望输出。这个过程不依赖线上环境完全可以在本地跑速度也快。我第一次做离线回放时发现一个叫做“日志分析”的Skill召回率只有四成仔细看回放记录才发现用户表达“看下日志报什么错”时模型经常不调用这个Skill而是自己尝试总结之后给出一段自认为合理的回复。问题就出在SKILL.md的描述里只写了“分析日志文件”没写“当用户询问日志中的异常或错误时也应调用”。改完描述再回放召回率直接涨到九成以上。这种问题如果不做离线回放几乎不可能被提前发现。4.2 四维评估准确率、召回率、延迟和成本回放只是手段要判断一个Skill系统好不好用我建议建一套四维评估指标每次改动都记录下来对比。这四个维度分别是唤起准确率、唤起召回率、端到端延迟和单次任务成本。准确率模型调用了某个Skill这个调用是否真的合理有没有该用A却用了B的情况召回率所有“应该调用Skill”的场景里模型有没有漏掉延迟从用户发请求到最终得到回复的总耗时重点看Skill执行占了多少。成本token消耗和外部API调用费用重点看上下文膨胀有没有被控制住。这四个维度不是孤立的它们之间存在权衡。比如我为了提升召回率把某个Skill的触发条件写得非常宽泛结果准确率降了很多不该调用的场景也调用了白白增加了延迟和成本。后来我学会了用“多问一句”的方式解决模棱两可当模型对是否调用某个Skill只有五六成把握时不直接调用而是先反问用户一句“你是指想检查服务器资源还是想分析访问日志”虽然多了一次交互但准确率、成本、体验都更好了。4.3 踩坑实录我这半年遇到最多的五个问题这里整理一下我在实际落地过程中遇到频率最高的五个问题每一个都花了不止一个下午去排查。第一个问题是Skill描述与模型微调风格不匹配。我用一个偏推理风格的模型做测试时它总是“理解”了Skill描述但就是不调用原因是它倾向于自己写代码调用底层工具而不是走Skill通道。解决方法是把系统提示词里改成“所有工具调用必须通过已定义的Skill完成禁止直接调用底层命令或编写临时代码”。第二个问题是参数里的自由文本字段成为注入入口。有些Skill会把用户原话拼进命令行参数结果用户输入“重启服务器rm -rf /”时模型原样传给了执行器。虽然底层有严格的白名单校验没出大事但这个教训很深刻任何用户输入进命令模板前必须先经过参数白名单检查和转义处理。第三个问题是Skill返回数据里包含敏感信息。巡检Skill返回的进程列表里可能有其他用户启动的可疑进程名直接把原始结果给Agent再转述给用户存在信息泄露风险。后来我在执行器里加了脱敏逻辑某些字段统一打码。第四个问题是重试机制没有上限。某个外部API故障时Skill内部的重试策略会连着重试三次每个请求又都很慢结果一次任务里光是等待重试就花了两分多钟。现在我的策略是总重试次数最多两次且每次重试前判断错误类型——只有网络类错误才值得重试参数类错误重试再多次也没用。第五个问题是“Skill幻觉”。模型在用户没明确要求的情况下主动推荐了某个Skill比如用户在问“明天天气怎么样”模型却调用了“服务器巡检”Skill。这个问题的根源是描述里“检查服务器资源状况”这个触发条件被模型理解得过于宽泛。我把描述改成“仅在用户明确询问服务器或系统资源状况、且用户问题与IT系统运维相关时调用”就基本没有再出现过了。5. 最后一件事Skill的维护与沉淀5.1 版本管理与灰度发布Skill也会过期很多人把Skill当成一次性开发物写完用起来就不管了但实际运行下来Skill一定是要持续迭代的。外部API会变业务规则会变用户问法也会变一个Skill上线三个月之后很可能已经“过时”了。我给每个Skill加了版本号并在SKILL.md里维护一个变更日志记录每次改动的原因和影响范围。改Skill描述会影响模型唤起行为改执行器逻辑会影响结果可靠性这两类改动要分开走。描述类改动风险高我会先在离线回放里验证召回率和准确率不掉再灰度上线。执行器类改动风险相对可控但要特别注意异常分支的回归测试尤其是新增了第三方依赖的时候。灰度发布的操作也简单在注册表里给每个Skill加一个enabled开关先让10%的流量用新版本观察延迟、错误率、用户反馈没有问题再逐步放大到100%。如果发现问题把开关一关就能立刻回退到旧版本整个操作比改代码重新上线要快得多。5.2 留给团队的一套“Skill开发规范”草案做了一段时间之后我沉淀出一套给团队用的Skill开发规范这里也分享出来供参考。写规范的目的不是管人而是防止每个人按自己的习惯写出来的Skill无法互相协作。我规定每个Skill必须包含以下内容一个SKILL.md其中要有名称、一句话描述、输入参数表、输出结构、错误码定义、权限声明一个execute.py入口函数必须接收字典参数、返回JSON字符串一套最小测试用例至少覆盖正常路径、参数错误路径、依赖失败路径三种情况。执行器内禁止调用大模型禁止无界循环禁止无超时的外部请求。所有返回给Agent的数据必须经过摘要处理或脱敏处理。这套规范看起来简单但它解决了团队协作里几个最头疼的问题别人写的Skill你能看懂、能测试、敢接手一个新Skill接入系统的成本降到半小时以内线上出问题的时候凭错误码就能定位到具体模块不用翻代码。5.3 我的一些真实体会做Agent Skills这段时间我个人最深的体会是AI应用里真正值钱的往往不是模型的“聪明”而是工程上的“确定性”。模型负责理解用户意图和做决策Skill负责把决策变成确定性的结果两者各司其职系统才能稳。还有一个技巧想分享给正在做这类系统的朋友给你的每个Skill想一句“人类验收语”。我在每次改动Skill之后都会用一句最自然的用户话术去验证比如“看看服务器还能撑多久”然后看Agent能不能正确唤起磁盘巡检和进程检查这两个Skill并把结论说得像一个靠谱的运维工程师。这句话不需要多复杂但它能帮你快速发现“描述偏离真实用户问法”这类最隐蔽的问题。最后再啰嗦一句Agent Skills这套思路并不只适用于运维场景。只要你的Agent需要执行多类外部操作无论是对接业务API、处理文档、操作浏览器还是调度数据分析流程把能力封装成带协议、带边界、带错误处理的Skill都能明显提升稳定性和可维护性。从最小的一个Skill开始试你会感受到这套机制的价值的。