做Agent开发满打满算也有大半年了把几款主流大模型接进业务系统的流程我已经跑得很熟各类智能体框架也搭过好几套。但慢慢我发现一个扎心的事实真正决定一个Agent是“玩具”还是“生产力工具”的往往不是模型本身而是挂在它身上的那一堆“技能”。agent-skills说白了就是把Agent能做的事拆成一个一个可复用、可维护、可单独调试的“技能单元”让Agent从只会聊天变成真能干活的数字员工。这篇文章我打算把这套体系的完整思路、目录怎么搭、技能怎么写、坑在哪里以及怎么给技能库做规模化治理一次性讲透希望对正在搭建Agent能力层的朋友有点帮助。1. 为什么需要“技能化”Agent从设计思路说起1.1 Agent能力的三大痛点聊天、记忆、工具调用先把问题聊清楚。一个大模型Agent原始形态就是“对话模型系统提示词”。你让它回答问题没问题你让它写一段文案也凑合。可一旦你要它“去系统里查一下某台设备的实时状态然后根据告警级别生成处置建议”它就原形毕露了模型本身不产生动作它只产生文字。我最初是怎么处理的把所有指令都塞进系统提示词。结果就是提示词越来越长从两千字膨胀到八千字模型的理解开始飘忽不定经常答非所问。后来退了一步把一些固定动作写成函数Function Calling确实解决了一部分问题可函数之间的逻辑关系、触发条件、参数校验全散落在代码里加一个新能力要动主程序改一个参数要重新发版整套东西越来越像一座屎山。更麻烦的是记忆和上下文。Agent在处理一个任务时经常会用到多轮工具调用每一步的中间结果都要往上下文里塞。塞多了模型记不住前面的结论塞少了后面的推理就没有依据。你会发现单纯在提示词层面做加法根本解决不了能力扩展的问题。于是我开始琢磨一件事能不能把Agent的每一项能力都封装成一个独立的“技能包”这个技能包自带说明、自带参数定义、自带执行逻辑、自带示例Agent按需加载用完即走。这个概念就是agent-skills。1.2 Skill、Tool、Plugin三种扩展方式怎么选很多朋友容易把Skill和Tool、Plugin搞混我先做个区分。Tool是最小的函数级单元通常就是一个函数、一个API接口输入参数返回结果给模型直接调用。它的优点是轻、快、可控适合做单一动作比如查天气、算日期、发一条HTTP请求。Plugin偏集成通常是对接外部应用的能力扩展比如一套即时通讯软件里的插件或者一个IDE里的扩展。Plugin更看重和宿主环境的融合加载方式、权限模型往往跟着宿主走灵活性受限。Skill则是一种更完整的封装它不只是“一段可调用的代码”而是“一段代码一份使用说明若干示例可能的知识数据”的组合。Skill适合解决复杂任务编排它能在内部做多步骤判断也能把其他Tool串起来。我用一张对比表直接说明维度ToolPluginSkill粒度单一函数外部应用扩展任务级封装核心内容代码集成适配指令代码示例知识依赖关系无依赖或弱依赖强依赖宿主环境声明式依赖可复用性一般受平台限制高可跨项目复制适用场景原子操作平台集成复杂任务编排选型建议很简单如果你只需要一个动作比如“调用某接口查数据”用Tool如果你要Agent完成一个完整的子任务比如“诊断设备故障并生成报告”请用Skill。这也是agent-skills项目最核心的定位把任务级能力做成可交付的单元。1.3 一个技能就是一个可交付单元解耦的收益把技能拆成独立单元之后收益是立竿见影的。首先是调试独立。以前改一个工具函数要重新跑整个Agent流程。现在技能单元可以单独测试单独喂给模型看效果发现问题只改一个目录里的文件就行。其次是权限可控。每个Skill可以声明自己需要哪些权限、访问哪些系统、调用哪些外部API。加载时检查执行时隔离安全边界清晰得多。最后是可组合。一个技能的输出可以作为另一个技能的输入。比如“设备诊断”技能输出一份报告“报告摘要”技能再把报告压缩成一段话两个技能之间通过标准输入输出衔接互不干扰。这种解耦思路本质上是把Agent当成了一个“操作系统”各种Skill就是这个系统上的应用程序。你什么时候见过一个操作系统把所有软件功能都塞进内核里没有吧。Agent也一样核心要轻能力要外挂。2. agent-skills的核心结构目录、清单与依赖2.1 目录怎么组织按域分堆按版本隔离一个规范的技能库目录结构应该从一开始就定好。我建议按“领域/技能名/版本”三层来组织。举个例子skills/ diagnose/ device_diagnose/ v1/ v2/ network_diagnose/ v1/ ops/ restart_service/ v1/ data/ report_summary/ v1/这样组织有几个直接好处第一按领域分堆技能一多也不会乱找起来快第二版本目录隔离升级不破坏线上运行第三顶层目录名可以直接作为命名空间前缀防止不同团队写的同名技能互相覆盖。命名规则我说一下技能ID统一用小写字母加下划线不要用空格、连字符、中文。因为技能ID会作为加载器中的唯一标识出现特殊字符很容易在解析时出问题。这是我踩过的坑后面细说。2.2 SKILL.md清单技能的自述文件怎么写每个技能目录里最重要的文件是SKILL.md它是技能的“自述文件”。加载器靠它识别技能Agent靠它理解技能。这个文件写不好后面全白搭。我放一个完整的SKILL.md示例拿“设备诊断”技能来说--- name: device_diagnose description: 用于设备状态诊断输入设备ID输出诊断结论与处置建议。当用户询问设备异常、设备离线、设备告警、设备状态检查时使用。 version: 1.2.0 author: platform_team license: internal parameters: device_id: type: string required: true description: 设备编号如 DEV-2024-0001 check_depth: type: string enum: [basic, deep] default: basic description: 检查深度basic只查状态deep额外跑诊断脚本 dependencies: - requests2.31 - internal-monitor-sdk1.0.0 when_to_use: 当用户提到设备离线、异常告警、状态检查、故障排查等场景时激活 当用户只是询问设备型号参数时不要激活交给通用问答。 ---这里面几个字段最关键description是触发模型的依据决定模型什么时候调用这个技能parameters用类JSON Schema的方式定义方便加载器生成校验逻辑when_to_use是一个额外的触发约束用来写“什么情况下不要用”这个字段能大幅减少误调用。2.3 依赖与权限声明先声明后调用早期我写技能看到什么库就用什么库完全不考虑依赖问题。结果技能从A项目复制到B项目一跑就报ModuleNotFoundError。后来我强制所有技能必须在SKILL.md里声明dependencies加载时统一检查缺了就报错提示不允许隐性依赖。权限声明也是同样道理。我见过有人直接让Agent执行Shell命令来做系统运维一旦命令拼接出错后果不堪设想。我现在的做法是每个技能可以声明要执行的命令白名单加载器会拦截未声明命令所有文件写入操作限定在指定工作目录内。permissions: exec: - /usr/bin/ping - /usr/local/bin/device_probe network: allow: [*.monitor.internal] files: write_dirs: [/tmp/skill_runtime]执行时所有命令都在沙箱环境里跑网络请求只能访问白名单域名。这套“先声明后调用”的规矩是技能库能安全铺开的底线。3. 手写一个Skill温控设备诊断完整实操3.1 场景拆解先定义输入输出再动笔空谈概念没意思我带大家手写一个完整的“温控设备诊断”技能。第一步不是写代码而是拆场景。这个技能要解决什么问题用户会给一个温控设备编号Agent要查出设备当前温度、运行状态、最近告警记录综合判断设备是否异常最后输出一份简短诊断结论。输入定了设备编号。输出定了状态、温度、告警列表、诊断结论、处置建议。这个输入输出关系一定要在动手写代码前想清楚否则Skill内部的逻辑会越写越乱。尤其是输出结构直接决定后面Agent怎么引用你的结果。我通常会先定义好JSON输出结构再倒推逻辑代码。3.2 落地三步描述文件、执行脚本、对话示例定完输入输出下面按三步落地。第一步写SKILL.md描述文件。名称叫climate_diagnose描述里带上触发词温控设备、温度异常、过热、制冷失效。参数只有device_idrequired设为true。依赖声明requests库。这个文件写完后技能就能被加载器识别了。第二步写执行脚本diagnose.py。这个脚本负责调用内部接口拿设备状态然后基于阈值判断温度是否异常。代码我简化一下import json import requests def diagnose(device_id: str) - dict: # 1. 拉取设备实时状态和最近告警 status_url fhttps://monitor.internal/api/v1/climate/{device_id} resp requests.get(status_url, timeout5) resp.raise_for_status() data resp.json() # 2. 根据温度阈值给出诊断结论 current_temp data[current_temp] threshold_high data[threshold_high] abnormal current_temp threshold_high alerts [item[level] for item in data.get(recent_alerts, [])] if abnormal and critical in alerts: conclusion 设备存在过热告警建议立即停机检修 suggestion 优先检查压缩机与散热风扇 elif abnormal: conclusion 当前温度超过阈值设备运行异常 suggestion 降低负载并观察温度变化 else: conclusion 设备运行正常 suggestion 无需额外处理 return { device_id: device_id, current_temp: current_temp, threshold_high: threshold_high, recent_alerts: alerts, conclusion: conclusion, suggestion: suggestion, } if __name__ __main__: # 支持命令行传参方便单独调试 result diagnose(sys.argv[1]) print(json.dumps(result, ensure_asciiFalse, indent2))注意脚本提供命令行入口这是个小技巧。有了它你可以不经过Agent直接跑技能验证逻辑排查问题会快很多。第三步写examples.md放几个对话示例。千万别小看这个文件模型是个“看例子办事”的家伙同样的指令你给两个好例子它的调用准确率能提升好几个点。# 对话示例 ## 示例1用户报告温度异常 用户3号机房的温控设备好像有点问题温度一直降不下来。 助手应调用climate_diagnose参数 {device_id: DEV-TEMP-003} 输出后生成结论设备当前温度28℃已超过阈值25℃存在告警建议立即检修。 ## 示例2例行检查 用户帮我看一下这批温控设备哪些需要关注。 助手应调用climate_diagnose对设备列表逐个查询汇总异常项。3.3 注册与加载三种主流接入方式技能写好之后怎么让Agent用起来我试过三种主流方式各有优劣。第一种是全量注入。把所有SKILL.md的内容拼到系统提示词里。优点是实现简单模型对所有技能都“看得到”缺点是上下文爆炸技能一多Token开销巨大模型还会被大量不相关内容干扰。第二种是路由索引动态加载。系统提示词里只放一份“技能索引表”包含技能名和一行描述。模型根据用户问题先跳转到对应技能再触发技能执行。这种方式的上下文占用小、触发准确率高也是我目前最推荐的方式。第三种是基于向量检索的按需加载。把技能描述向量化用户问题进来先做相似度召回再注入命中的技能内容。这种方式适合技能库非常庞大、索引表都放不下几百个技能的场景但对工程能力要求更高还得维护向量库。如果你刚起步直接在系统提示词里维护一份静态索引表就够了。3.4 上下文注入策略控制Token消耗保住指令优先级很多朋友以为技能文件写得越细越好结果把SKILL.md里所有内容一股脑塞进提示词。这么做会带来两个问题Token浪费和指令优先级稀释。我的做法是三层注入第一层是技能索引非常精简第二层是当前激活技能的SKILL.md核心内容包括参数定义和when_to_use第三层是技能执行返回的结果数据。这三层分别对应“模型知道有什么技能”“模型知道怎么用当前技能”“模型拿结果做推理”。有一个细节值得注意技能结果返回后要明确告诉模型“下面的数据来自XX技能引用结果时注明来源”。否则模型经常把技能输出和用户输入混在一起乱改数值。我通常会在结果前加一行标准提示比如“【技能执行结果-请直接引用不要修改数值】”。4. 排坑实录我在落地过程中反复踩到的几个问题4.1 技能加载不生效八成是描述写得不像触发词这是最高频的问题。技能文件存在代码没问题但模型就是不调用。我排查过很多次最后发现病根几乎都在description上。比如有人把description写成“用于设备诊断”模型看到用户说“我的空调不制冷了”根本联想不到这跟设备诊断有关系。description必须写“触发词场景”最好的形式是当用户提到A、B、C等情况时使用。我实践下来给description加三到五个典型触发词调用准确率能提高一半。另外description不要写废话。什么“这是一个功能强大的...”完全没用模型不会因为形容词而更愿意调用它只认语义匹配。如果描述没问题还是不生效按这个顺序排查排查项检查要点技能ID是否包含空格、连字符、中文等非法字符清单格式YAML解析是否正常字段是否拼错索引表技能是否真的出现在系统提示词的索引里参数定义参数是否必填缺参时模型是否会放弃调用调试日志加载器是否成功读取了SKILL.md我每次排查都先看加载日志确认技能文件有没有被成功解析。很多时候YAML里一个中文冒号写成了全角解析直接失败模型自然看不见这个技能。4.2 多个技能“打架”命名空间与优先级技能多起来之后会出现“A技能和B技能都匹配同一个问题”的情况。最常见的冲突是两个技能的功能描述高度重叠比如“设备诊断”和“设备状态查询”用户问“设备现在怎么样”两个技能都觉得该自己上结果模型反复横跳。我的解决方案是两层第一强制用领域前缀做命名空间比如diagnose.device和query.device_status语义上先区分开第二在SKILL.md里增加优先级字段同一场景下优先匹配优先级高的技能。还有一个容易忽略的点技能参数名冲突。两个技能都用参数名target但含义不同模型很容易填错。所以在定义参数时建议带上技能前缀比如diagnose_target、query_target宁可丑一点也别让模型猜。4.3 环境依赖别让技能在半夜拉依赖某次线上环境一个新的诊断技能需要装一个内部SDK我没做预装只是在SKILL.md里声明了依赖。结果技能第一次被触发时才开始安装装到一半超时整个Agent流程直接报错用户体验非常差。从那以后我立了规矩所有依赖必须在技能发布前完成预安装和验证运行时不允许动态安装任何包。SKILL.md里的依赖声明只作为“环境检查清单”不作为“运行时安装指令”。依赖版本也要锁死用精确版本号不要用大于号这种浮动版本。今天能跑不代表明天能跑依赖库一发新版你的技能可能就挂了。为了这个事我连续吃过两次亏现在所有依赖都是精确到小版本锁定。4.4 安全边界热插拔脚本是双刃剑技能最大的优势是灵活最大的风险也是灵活。一个可动态加载的脚本如果权限控制不到位等于给Agent开了个后门。我的安全基线是这么做的第一禁止技能在运行时拼接任意Shell命令所有可执行命令走白名单第二网络访问走域名白名单第三文件读写限定在临时工作目录第四所有技能代码经过代码评审才允许上线。千万别觉得麻烦Agent一旦被提示词注入攻击恶意指令可能让技能去执行本不该执行的操作这个代价比评审成本高得多。还有一条看似不起眼但很重要的技能目录里的文件权限要设置好运行用户用低权限账号不要用root跑Agent服务。4.5 评测习惯不评测你根本不知道哪个技能在拖后腿很多团队把技能开发完、能跑通一次就觉得完事了从不做系统性评测。我一开始也这样后来发现技能多了之后某些技能会“隐性干扰”整体效果明明A技能没问题但加上B技能后模型调用的准确率反而下降了。现在我每个技能上线前都要过一遍黄金用例集。给技能准备十到二十个典型用户问题每个问题标好“期望调用的技能”和“期望输出”然后批量推理比对。评测指标有两个就够了技能命中率和输出正确率。命中率就是用户问题触发正确技能的比例低于90%就说明description还有问题要改。输出正确率看的是技能返回的数据是否符合预期这个主要暴露代码逻辑问题。评测不复杂但能让你在出问题前及时拦住大部分低级错误。5. 进阶治理从“有几个技能”到“技能平台”5.1 命名空间与版本一技能一名升级不破坏技能到了几十个之后治理问题会越来越突出。第一条铁律是一个技能只能有一个名字不允许同名不同技能也不允许一个技能有多个别称。你可以在description里写多个触发词但技能ID必须唯一。版本升级要遵守语义化版本规范。主版本号变化说明不兼容次版本号变化说明新增功能补丁号变化说明只修了Bug。我在加载器里做了兼容检查如果线上Agent正在使用v1你发布v2不会自动切换必须显式确认才迁移。5.2 共享与集市团队内部怎么流通技能开发出来不用放着发霉这是资源浪费。我见过比较健康的做法是团队内部做一个“技能集市”每个技能有独立的发布页包含SKILL.md文档、调用次数统计、使用评分和负责人信息。新项目要能力时先来集市里搜有现成的直接引用没有的才新开发。集市的门槛不要设太高至少要有完整SKILL.md、黄金用例集、通过安全评审这三样否则不允许上架。宁可技能少一点也别让一堆劣质技能把Agent的调用搞得一团糟。5.3 可观测日志、调用链与成本最后说可观测性。技能调用一旦频繁你必须有手段知道每个技能被谁调用、调了几次、花了多少Token、耗时多久。我的日志格式很简单但很有效每次技能调用打一行结构化日志包含技能ID、版本、输入参数、输出摘要、耗时、Token消耗。累积一段时间后你能看到很多有价值的信息哪个技能使用率极低考虑下线哪个技能Token消耗特别大考虑优化代码减少多余输出哪个技能频繁报错优先排查稳定性。成本这块也要算细账。技能本身不产生费用但技能产生的输出会占用上下文进而推高后续多轮对话的Token消耗。技能返回结果越精简越好只返回Agent做推理所需的关键字段不要为了“看起来完整”返回一大堆冗余数据。这个习惯长期坚持Token成本能省下可观的量。我在整个实战过程中最深的一点体会是Agent能力的上限不是模型决定的而是你的技能库决定的。模型再聪明没有好技能它也只能纸上谈兵技能库一旦建好模型就真的长出了手和脚。如果你正在搭自己的Agent能力层我建议你从最小的一个Skill开始跑通“描述-加载-执行-回填”整个闭环再慢慢扩充。先把前五个坑都踩一遍你就差不多入门了。