最近在重构一套基于大语言模型的智能体应用我遇到一个特别烦的问题技能越来越多调用却越来越乱。今天临时塞一个函数明天又加一个工具描述技能之间互相依赖参数命名随心所欲迭代一次就崩一次。折腾了几轮之后我把整个技能体系推倒重来做了一个叫agent-skills的技能库项目。它是给智能体做的一套技能基础设施核心解决一个问题技能的定义、开发、验证、注册和检索怎么才能变成一条可复制、可维护的工程链路。这篇博文就来拆一拆这个项目的完整落地过程适合正在做智能体应用、工具链设计、复杂任务自动化的朋友参考哪怕你只是刚接触大模型应用开发也能从这里看懂一套规范的技能库该怎么搭。1. 项目定位agent-skills 到底在解决什么问题先说清楚背景。现在很多团队做智能体应用功能需求很容易描述但落到工程实现上就尴尬了。你让大模型去完成一个任务比如“整理本周工单并生成汇报邮件”模型本身没有能力执行它得借助外部工具。最常见的做法是把工具包装成函数再在模型的对话框架里声明这个函数能干什么。这个思路本身没问题问题是随着工具数量增加声明越来越长参数越来越复杂函数之间的耦合也开始失控。我见过一个项目工具描述文件到了第三周已经堆了两千多行任何人改一个参数都要全局搜索生怕把别的功能带崩。agent-skills的定位不是再提供一个零散的工具封装框架而是一整套面向智能体的技能治理体系。技能在这里被定义为“一个可以被智能体规划和调用的最小能力单元”。项目本身包含四部分内容技能的开发规范、技能脚本模板、技能注册表生成器以及配套的测试验证台。我把它定位成一个横向基础设施任何智能体应用都可以把自己的业务能力按这套规范拆成技能注册进技能库然后统一被模型调度。这个项目能给谁用第一类在做智能体产品的开发者需要让大模型安全、稳定地调用外部工具第二类在做企业自动化的团队想把一系列业务流程沉淀成可复用能力而不是每次从零开发第三类还在学习和研究智能体应用的人通过这套项目能理解一个能力从业务需求到被模型真正调用的全流程是什么样。我在搭建过程中最大的体会是很多人以为技能的难点在于“让模型学会调用”实际上真正的难点在于“如何定义技能的边界”而agent-skills恰恰把这部分规范化和工具化了。做这个项目的时候我给自己定了一个原则不能只做一个能跑的 Demo要让每一个技能都经历开发、验证、注册、检索四个环节缺一不可。后面所有章节都会围绕这条链路展开这也是整套体系跟我之前直接写函数调用最大的差异。2. 技能三层模型为什么不能把技能简单丢给模型在开始写第一个技能之前我先解决了一个最基础的问题一个完整可用的技能系统应该分成哪几个层次我用了很长一段时间只有一个层的概念——把函数声明丢给模型就行。后来我发现一旦技能多了模型面对几十个函数声明会出现两种典型问题要么选择困难不知道怎么选要么过度自信拿一个不合适的技能硬执行最后结果完全偏离预期。最后我把技能体系拆成了三层技能层、行动层、规划层。这个模型是整个agent-skills项目的理论基础。技能层Skill Layer定义这个库“会做什么”也就是能力清单。每个技能在这里表现为一组独立的能力描述比如“查询工单列表”“汇总工时数据”它不关心底层由哪个系统来执行只描述能力的输入输出和约束条件。行动层Action Layer定义技能具体怎么被某个系统执行。这是真正的函数实现包括 HTTP 调用、本地脚本、命令行工具执行等。行动层是技能层背后的“锅炉房”你可能感知不到它但一切具体工作都发生在这里。规划层Planning Layer定义智能体如何选择技能、按什么顺序组合技能以及处理技能失败后的降级策略。它直接对接大模型的推理过程是技能库和应用大脑之间的接口。我可以用一个生活化的类比来帮助理解技能是工具箱里的电钻行动层是那把电钻的参数和供电系统规划层则是老师傅心里在盘算“这里应该先钻孔再上螺丝钻孔要用平钻头还是下沉钻头”。没有这三层划分工具箱只是一个没有秩序的仓库有了规划层你实际上是在给模型配置一个虚拟的现场项目经理。这三层模型直接影响了我怎么写技能描述和工具声明。技能层不能直接写得太细比如不要在这个层次暴露“调用内部工单系统的 v2 接口参数格式为 JSON”这属于行动层的职责。技能层只需要告诉模型“技能会返回按状态分类的工单列表以及每条工单的标题、创建时间和当前负责人”。这样模型做选择时不需要理解底层接口细节决策负担大幅降低。同时这层抽象还解决了多智能体协作时的通病不同智能体可能对接不同的底层系统比如一个管销售数据一个管售后工单如果没有技能层统一抽象你要为每个智能体维护一套完全独立的工具描述最终会在差异中失控。行动层可以完全不同但技能层可以实现很好的统一这才是技能库能被多个应用复用的前提。3. 第一步对工具接口做侦察而不是闷头写技能很多人在做技能的时候第一步就错了。拿到业务需求立刻开始设计函数签名然后哗啦啦写代码。等你写完发现参数跟实际系统的返回结构对不上改来改去折腾一整周。我在开发agent-skills时定了一个硬规矩写技能之前先完成工具侦察。所谓工具侦察就是对要打交道的底层系统做一次完整的接口调研。无论你要对接的是内部 API、第三方服务还是本地的数据库查询侦察这一步都不能省。我通常会填写一张表格表格包含六项内容系统名称、服务入口、验证方式、核心字段、鉴权要求、错误返回样例。这张表背后的逻辑是你首先要回答清楚三个问题数据从哪来、怎么获得、拿回来以后要做什么。拿我曾经做的一个模拟场景来举例。假设某公司内部有一个工单系统需要开发一个“查询本周工单并生成汇总”的技能。如果我没做侦察我会想当然地认为接口会返回工单列表然后直接设计一个generate_weekly_summary()函数。但实际上那个工单系统的查询接口有分页限制单次最多返回 50 条工单的“本周”并不等于自然周而是从每周五下午六点开始结算还有一个字段assigned_to底层存的是用户 ID而不是用户名需要额外关联员工表。这些细节不侦察根本写不出可用的技能。接口侦察还包含一项关键操作最小验证。就是用命令行工具或者是简单的脚本脚本脚本先用真实凭证打一次这个接口确认返回样例跟文档一致。这一步成本很低却能在早期就捕捉到大量文档坑。比如有的接口文档写的是 GET 请求实际要用 POST有的接口要求请求头里带X-Tenant-Id文档里却隐藏在权限说明末尾。我用侦察时发现的最离谱的一件事是某内部接口的返回字段message在成功情况下是字符串在失败情况下是数组这种隐藏的不一致性等技能上线之后才暴露排查代价特别高。侦察完接口下一步是设计“参数映射”。每个技能对外暴露给模型看的参数必须能无歧义地映射到底层接口的参数。不要怕麻烦这一步值得多花时间。参数映射表我通常包含四个字段技能参数名、底层接口参数名、参数类型约束、必填还是可选。当这层映射表做好后写技能本身就会变得很快因为你要决定的逻辑都已经清楚了代码只是翻译而已。4. 技能脚本的关键写法从入口到返回结果的完整链路侦察结束就可以进入技能脚本的开发了。我把技能脚本设计得尽量简单——一个技能对应一个目录目录标准结构如下skills/ └── weekly-report/ ├── SKILL.md ├── tool.py └── test-cases.jsonSKILL.md是这个技能的说明书它给模型看的描述全在这里tool.py是实际的执行代码test-cases.json是预置的测试用例。这个目录结构看起来简单但每一部分都有细节。先看SKILL.md。它相当于把技能暴露给规划层的窗口内容太多模型会困惑太少又不够模型做决策。我一般写四个部分技能名称、用途描述、参数说明、输出说明。其中参数说明要写清楚取值范围和约束比如“日期范围”的格式必须是YYYY-MM-DD“排序方式”只能是asc或desc。这些约束写得越清楚模型就越不容易传入乱参数。下面是我为“周报生成”技能写的摘要版示例# 技能生成周报汇总 - 用途查询指定时间范围内的工单并按负责人和状态做汇总统计输出结构化结果。 - 参数 - start_date字符串开始日期格式 YYYY-MM-DD必填。 - end_date字符串结束日期格式 YYYY-MM-DD必填。 - 输出返回 JSON包含 total_count、by_status、by_owner 三个字段。注意编写这份文档的核心是“让模型在做选择时一目了然”。它不需要知道工单系统的数据库结构也不需要知道有没有缓存那是tool.py的事。tool.py的核心实现则要遵守一个比较新鲜的约束技能脚本内部不允许直接输出任何面向最终用户的内容它必须返回结构化数据由上层应用负责讲语言转成自然语言。这样做的原因是每个技能都应可以被不同交互形式复用——同一个查询技能可以被对话式智能体调用也可以被定时任务调用最终展示方式不同但技能本身的输出保持统一。为了让输出保持可控我在tool.py里固定了一个返回模板import json def main(params: dict) - dict: start_date params.get(start_date) end_date params.get(end_date) if not _valid_date(start_date) or not _valid_date(end_date): return {ok: False, error: 参数格式错误日期须为 YYYY-MM-DD} try: records _fetch_tickets(start_date, end_date) summary _summarize(records) return {ok: True, data: summary} except Exception as exc: return {ok: False, error: f执行失败: {exc}}这段代码体现的几个原则值得展开。第一参数校验必须在业务逻辑前执行并直接返回错误不给模型留下任何“参数传错还能继续”的想象空间。第二异常处理要捕获并包装成结构化返回不能任由异常往上层抛。第三返回结构固定为ok加data或error的形态这能大幅简化上层应用的解析逻辑。我在真实项目里还遇到过一个问题多个智能体要复用同一个技能但它们的调用上下文不同。比如一个智能体返回工单详情时希望附带评论信息另一个却只要标题和状态。为了避免技能变成一堆 if 分支我在技能参数里增加了detail_level选项由调用方显式决定需要什么粒度的结果。这比在技能内部判断调用方是谁要干净得多也让跑测试的时候更方便。技能脚本写完之后别急着注册先做一件事用test-cases.json跑一遍典型场景。我的习惯是至少准备三个典型用例一个完全合法的参数用例、一个缺失必填参数的异常用例、一个底层服务返回非预期格式的容错用例。尤其是第三种用例它能暴露技能代码里最常出现的问题——对上游数据结构“过度假设”。5. 技能设计的第一性原则原子性、确定性与幂等性技能脚本怎么写可以学语法解决但设计一个技能到底该包含多少内容、怎么拆分、边界在哪这些属于设计决策。我在agent-skills项目里沉淀了五条第一性原则基本每条都是从实战的坑里爬出来的。第一条单一职责。一个技能只做一件能被用户清晰感知的事。我在某次开发时一开始把一个“查询工单并生成周报”的功能写成了一个技能因为自己觉得“这俩本来就是一个流程”。运行起来发现一个大问题模型只要调用这个技能就必须同时执行查询和生成两个步骤哪怕用户只想问一句“这周有没有紧急工单”它也要跑完完整的报表逻辑不仅浪费 token速度也慢体验很差。后来拆成“查询工单”和“生成周报”两个技能规划层能自由组合反而效率更高模型也更不容易出错。第二条确定性优先。一个技能在同样输入下返回结构必须是稳定一致的。这意味着技能内部最好不要有依赖当前时间的随机逻辑不要用不可控的列表排序更不要在前端脚本里做“智能判断”。我在排一个诡异 bug 时发现某技能偶尔会在返回数据里丢失字段排查半天发现是内部代码用了一个默认字典遇到缺失键就返回空值这次有这个字段下次没有。这种不确定性会直接破坏上层应用对技能结果的信任。第三条幂等性。同样的技能连续调用两次不会产生额外的副作用。对查询类技能这很容易做到但涉及写操作的技能就需要仔细设计比如在一个“创建工单”的技能里要利用外部系统的幂等键来避免重复创建在“发送通知”的技能里要支持去重机制。一个不幂等的技能会导致模型在任务重试时重复操作后果相当严重。第四条参数自解释。技能的参数名必须做到“看一眼就知道含义”。我曾经见过一个技能参数名是p1和p2代码里要加注释才能理解含义模型参数生成时更是一头雾水。参数名还应该避免歧义例如date不如start_datetype不如ticket_type。别觉得这是小事技能一旦多了光靠这个习惯就能省下大量沟通成本。第五条无隐形副作用。技能脚本执行过程中不应该偷偷修改任何外部状态除非这是技能的职责。比如一个查询技能内部悄悄写了一个日志文件这算隐形副作用因为调用方没有预期到这个行为会在系统里留下文件。如果某些操作确实需要就要显式声明比如在SKILL.md里写明“此技能会将查询记录写入审计日志”。沿着这些原则还有一个无法回避的问题技能的粒度怎么定我给出的经验法则是以“用户能否直接感知到这个结果”为标准。如果用户能直接看到技能返回的数据这个粒度就合适如果用户拿到结果还要经过很长一段加工才能用那说明技能拆得太细如果技能内部包含了多个不同阶段的输出说明拆得太粗。这个标准不一定适合所有场景但在大多数业务技能上都挺好用的。6. 注册与版本管理让智能体在几百个技能里快速找到正确的那一个技能写好了还需要进入一个智能体可以查询的注册表不然技能和没写一样。这是我从agent-skills中收获最明显的一环因为技能一多普通的“全部塞进系统提示词”方案立刻崩溃。这个项目里我用的是基于清单文件的注册机制每个技能目录里的SKILL.md被扫描生成一份全局技能清单智能体通过这份清单快速检索候选技能。技能清单的核心字段包括技能 ID、名称、用途、参数摘要、版本号、依赖项、执行文件路径。为了提高检索效率我把用途描述做成了两个版本的摘要——详细版和标签版。标签版只保留 10 到 20 个字的关键概念比如“工单 汇总 周报”详细版则是完整描述。这样模型在规划层做粗选时只需要扫描标签版确定候选后再阅读详细版文档长度天然就控制住了。技能入库时我还加了版本管理。每个SKILL.md文件里都声明了version字段并在技能目录内维护CHANGELOG记录。注册表生成时用技能文件的SHA-256哈希做指纹当技能内容变更而版本号没升时注册工具会警告防止有人改了代码忘了升级版本。这个做法在多人协作时特别有用避免出现“明明改了技能但其他应用还在用旧缓存”的尴尬局面。让智能体加载技能时权限控制也要提前想好。技能本身没有黑白名单的话模型在做规划时可能会调用超出当前上下文的敏感技能。我推荐每个技能在清单里声明访问级别例如只读、读写、管理员。规划层在筛选技能时会先根据当前任务的权限上下文过滤掉不合法的选项。这一步不是可有可无的安全加固而是一个技能库成熟的设计。某个技能的权限声明有误在我这里发生过不止一次一个只能读已归档工单的技能因为忘了约束时间范围结果被模型拿去查了几年前的敏感数据。版本管理的另一层用途是解决跨智能体复用。我维护了一套统一的技能清单生成命令项目里任意一个智能体附加到同一个技能库时可以按需拉取全部技能或某个分组技能。某 B 团队想要复用 A 团队的“过期工单催办”技能并不需要复制代码只需要在自己的智能体配置里声明依赖这个技能 ID 和版本号。这个机制让不同业务线的智能体共享同一套底层能力避免了一次又一次地重复造轮子。7. 测试与验证搭建一个能兜底的最小测试台技能注册进库之后最怕的是某天接口偷偷变了技能返回结构全乱模型还蒙在鼓里继续调用。所以agent-skills里特意安排了一个轻量级测试台用来在技能出问题前拦截住。测试台的核心逻辑非常简单就是一个循环遍历技能目录下的所有test-cases.json依次执行技能脚本比对返回结果的ok字段和data的 key 集合是否符合预期。不要小看这个粗粒度验证它能拦截 80% 的回归错误。我自己遇到过一个典型问题底层接口某天突然把字段timestamp改成了created_time测试台的 key 校验立刻报了错而如果没有这套测试这个变化会在智能体实际调用时才暴露最终用户看到的是一堆解析异常。真正实践过程中测试台有几个容易踩的坑我必须多说几句。第一个坑是超时分类混乱。技能调用外部接口时必须区分三类超时连接超时、读超时、整体超时。我之前只设了一个总超时时间结果外部接口偶发变慢时所有技能都卡到极限才返回任务执行链路被拖得非常严重。在agent-skills测试台里我引入了一个规范每个技能必须显式声明自己的总超时上限默认 10 秒有特殊需求的技能可以覆盖但需要写明理由。这个规范主要是为了逼开发者思考技能的耗时特征而不是让它自然长成怪物。第二个坑是 stderr 污染。技能脚本执行时很多内部日志会打到标准错误输出这本来没什么但当我把 stderr 内容一起带回给模型作为执行反馈时模型的上下文很快就被无关日志塞满反而忽略了真正的返回数据。解决办法就是测试台和技能脚本之间约定好正常运行只消费 stdout 里的结构化数据stderr 只用于调试且绝对不能包含业务结果。这个约定看起来平淡无奇但能帮你免掉一大半调试时间。第三个坑是缓存状态影响测试稳定性。有些技能为了性能加了内存缓存测试台连续执行同一用例时第二次结果因为缓存已经存在返回速度极快掩盖了真实的接口延迟。我的做法是测试台支持cold_run参数强制每次执行前清理技能自身的缓存状态保证每次测试都从一致的起点开始。技能本身也要注意不要把缓存状态写进持久化文件避免一个测试污染下一次执行。测试台跑通了技能库的闭环也就形成了技能从接口侦察开始经过编码、设计审查、注册、版本管理、测试验证最终成为智能体可以稳定调用的一块“积木”。每次新增技能我都按这条链路走完整流程这套做法现在在我这里已经成了基础设施级别的默认动作。项目跑到现在我最大的感受是做智能体应用看起来难的是模型提示词怎么调、外接工具怎么接实际上真正的分水岭是有没有人愿意把技能治理当成工程来做而不是当成临时脚本去堆。agent-skills这个项目让我沉淀了一套从技能定义到测试验证的完整方法论过程里有重构、有反复、也有过推倒重来的纠结但眼前的回报是新需求过来时团队不再担心改动一个技能会惊动另一个系统——因为边界清晰了风险就可控了。最后再分享一个小技巧每写一个新技能我都会先手写一遍它的SKILL.md版本号也好参数描述也好先写下这份“说明书”再动代码。别问为什么试两次你就知道了。 
长河君 · 2026/10/13 5:20:10 · 阅读 1.2k 智能体技能库实战：从工具混乱到工程化治理
最近在重构一套基于大语言模型的智能体应用我遇到一个特别烦的问题技能越来越多调用却越来越乱。今天临时塞一个函数明天又加一个工具描述技能之间互相依赖参数命名随心所欲迭代一次就崩一次。折腾了几轮之后我把整个技能体系推倒重来做了一个叫agent-skills的技能库项目。它是给智能体做的一套技能基础设施核心解决一个问题技能的定义、开发、验证、注册和检索怎么才能变成一条可复制、可维护的工程链路。这篇博文就来拆一拆这个项目的完整落地过程适合正在做智能体应用、工具链设计、复杂任务自动化的朋友参考哪怕你只是刚接触大模型应用开发也能从这里看懂一套规范的技能库该怎么搭。1. 项目定位agent-skills 到底在解决什么问题先说清楚背景。现在很多团队做智能体应用功能需求很容易描述但落到工程实现上就尴尬了。你让大模型去完成一个任务比如“整理本周工单并生成汇报邮件”模型本身没有能力执行它得借助外部工具。最常见的做法是把工具包装成函数再在模型的对话框架里声明这个函数能干什么。这个思路本身没问题问题是随着工具数量增加声明越来越长参数越来越复杂函数之间的耦合也开始失控。我见过一个项目工具描述文件到了第三周已经堆了两千多行任何人改一个参数都要全局搜索生怕把别的功能带崩。agent-skills的定位不是再提供一个零散的工具封装框架而是一整套面向智能体的技能治理体系。技能在这里被定义为“一个可以被智能体规划和调用的最小能力单元”。项目本身包含四部分内容技能的开发规范、技能脚本模板、技能注册表生成器以及配套的测试验证台。我把它定位成一个横向基础设施任何智能体应用都可以把自己的业务能力按这套规范拆成技能注册进技能库然后统一被模型调度。这个项目能给谁用第一类在做智能体产品的开发者需要让大模型安全、稳定地调用外部工具第二类在做企业自动化的团队想把一系列业务流程沉淀成可复用能力而不是每次从零开发第三类还在学习和研究智能体应用的人通过这套项目能理解一个能力从业务需求到被模型真正调用的全流程是什么样。我在搭建过程中最大的体会是很多人以为技能的难点在于“让模型学会调用”实际上真正的难点在于“如何定义技能的边界”而agent-skills恰恰把这部分规范化和工具化了。做这个项目的时候我给自己定了一个原则不能只做一个能跑的 Demo要让每一个技能都经历开发、验证、注册、检索四个环节缺一不可。后面所有章节都会围绕这条链路展开这也是整套体系跟我之前直接写函数调用最大的差异。2. 技能三层模型为什么不能把技能简单丢给模型在开始写第一个技能之前我先解决了一个最基础的问题一个完整可用的技能系统应该分成哪几个层次我用了很长一段时间只有一个层的概念——把函数声明丢给模型就行。后来我发现一旦技能多了模型面对几十个函数声明会出现两种典型问题要么选择困难不知道怎么选要么过度自信拿一个不合适的技能硬执行最后结果完全偏离预期。最后我把技能体系拆成了三层技能层、行动层、规划层。这个模型是整个agent-skills项目的理论基础。技能层Skill Layer定义这个库“会做什么”也就是能力清单。每个技能在这里表现为一组独立的能力描述比如“查询工单列表”“汇总工时数据”它不关心底层由哪个系统来执行只描述能力的输入输出和约束条件。行动层Action Layer定义技能具体怎么被某个系统执行。这是真正的函数实现包括 HTTP 调用、本地脚本、命令行工具执行等。行动层是技能层背后的“锅炉房”你可能感知不到它但一切具体工作都发生在这里。规划层Planning Layer定义智能体如何选择技能、按什么顺序组合技能以及处理技能失败后的降级策略。它直接对接大模型的推理过程是技能库和应用大脑之间的接口。我可以用一个生活化的类比来帮助理解技能是工具箱里的电钻行动层是那把电钻的参数和供电系统规划层则是老师傅心里在盘算“这里应该先钻孔再上螺丝钻孔要用平钻头还是下沉钻头”。没有这三层划分工具箱只是一个没有秩序的仓库有了规划层你实际上是在给模型配置一个虚拟的现场项目经理。这三层模型直接影响了我怎么写技能描述和工具声明。技能层不能直接写得太细比如不要在这个层次暴露“调用内部工单系统的 v2 接口参数格式为 JSON”这属于行动层的职责。技能层只需要告诉模型“技能会返回按状态分类的工单列表以及每条工单的标题、创建时间和当前负责人”。这样模型做选择时不需要理解底层接口细节决策负担大幅降低。同时这层抽象还解决了多智能体协作时的通病不同智能体可能对接不同的底层系统比如一个管销售数据一个管售后工单如果没有技能层统一抽象你要为每个智能体维护一套完全独立的工具描述最终会在差异中失控。行动层可以完全不同但技能层可以实现很好的统一这才是技能库能被多个应用复用的前提。3. 第一步对工具接口做侦察而不是闷头写技能很多人在做技能的时候第一步就错了。拿到业务需求立刻开始设计函数签名然后哗啦啦写代码。等你写完发现参数跟实际系统的返回结构对不上改来改去折腾一整周。我在开发agent-skills时定了一个硬规矩写技能之前先完成工具侦察。所谓工具侦察就是对要打交道的底层系统做一次完整的接口调研。无论你要对接的是内部 API、第三方服务还是本地的数据库查询侦察这一步都不能省。我通常会填写一张表格表格包含六项内容系统名称、服务入口、验证方式、核心字段、鉴权要求、错误返回样例。这张表背后的逻辑是你首先要回答清楚三个问题数据从哪来、怎么获得、拿回来以后要做什么。拿我曾经做的一个模拟场景来举例。假设某公司内部有一个工单系统需要开发一个“查询本周工单并生成汇总”的技能。如果我没做侦察我会想当然地认为接口会返回工单列表然后直接设计一个generate_weekly_summary()函数。但实际上那个工单系统的查询接口有分页限制单次最多返回 50 条工单的“本周”并不等于自然周而是从每周五下午六点开始结算还有一个字段assigned_to底层存的是用户 ID而不是用户名需要额外关联员工表。这些细节不侦察根本写不出可用的技能。接口侦察还包含一项关键操作最小验证。就是用命令行工具或者是简单的脚本脚本脚本先用真实凭证打一次这个接口确认返回样例跟文档一致。这一步成本很低却能在早期就捕捉到大量文档坑。比如有的接口文档写的是 GET 请求实际要用 POST有的接口要求请求头里带X-Tenant-Id文档里却隐藏在权限说明末尾。我用侦察时发现的最离谱的一件事是某内部接口的返回字段message在成功情况下是字符串在失败情况下是数组这种隐藏的不一致性等技能上线之后才暴露排查代价特别高。侦察完接口下一步是设计“参数映射”。每个技能对外暴露给模型看的参数必须能无歧义地映射到底层接口的参数。不要怕麻烦这一步值得多花时间。参数映射表我通常包含四个字段技能参数名、底层接口参数名、参数类型约束、必填还是可选。当这层映射表做好后写技能本身就会变得很快因为你要决定的逻辑都已经清楚了代码只是翻译而已。4. 技能脚本的关键写法从入口到返回结果的完整链路侦察结束就可以进入技能脚本的开发了。我把技能脚本设计得尽量简单——一个技能对应一个目录目录标准结构如下skills/ └── weekly-report/ ├── SKILL.md ├── tool.py └── test-cases.jsonSKILL.md是这个技能的说明书它给模型看的描述全在这里tool.py是实际的执行代码test-cases.json是预置的测试用例。这个目录结构看起来简单但每一部分都有细节。先看SKILL.md。它相当于把技能暴露给规划层的窗口内容太多模型会困惑太少又不够模型做决策。我一般写四个部分技能名称、用途描述、参数说明、输出说明。其中参数说明要写清楚取值范围和约束比如“日期范围”的格式必须是YYYY-MM-DD“排序方式”只能是asc或desc。这些约束写得越清楚模型就越不容易传入乱参数。下面是我为“周报生成”技能写的摘要版示例# 技能生成周报汇总 - 用途查询指定时间范围内的工单并按负责人和状态做汇总统计输出结构化结果。 - 参数 - start_date字符串开始日期格式 YYYY-MM-DD必填。 - end_date字符串结束日期格式 YYYY-MM-DD必填。 - 输出返回 JSON包含 total_count、by_status、by_owner 三个字段。注意编写这份文档的核心是“让模型在做选择时一目了然”。它不需要知道工单系统的数据库结构也不需要知道有没有缓存那是tool.py的事。tool.py的核心实现则要遵守一个比较新鲜的约束技能脚本内部不允许直接输出任何面向最终用户的内容它必须返回结构化数据由上层应用负责讲语言转成自然语言。这样做的原因是每个技能都应可以被不同交互形式复用——同一个查询技能可以被对话式智能体调用也可以被定时任务调用最终展示方式不同但技能本身的输出保持统一。为了让输出保持可控我在tool.py里固定了一个返回模板import json def main(params: dict) - dict: start_date params.get(start_date) end_date params.get(end_date) if not _valid_date(start_date) or not _valid_date(end_date): return {ok: False, error: 参数格式错误日期须为 YYYY-MM-DD} try: records _fetch_tickets(start_date, end_date) summary _summarize(records) return {ok: True, data: summary} except Exception as exc: return {ok: False, error: f执行失败: {exc}}这段代码体现的几个原则值得展开。第一参数校验必须在业务逻辑前执行并直接返回错误不给模型留下任何“参数传错还能继续”的想象空间。第二异常处理要捕获并包装成结构化返回不能任由异常往上层抛。第三返回结构固定为ok加data或error的形态这能大幅简化上层应用的解析逻辑。我在真实项目里还遇到过一个问题多个智能体要复用同一个技能但它们的调用上下文不同。比如一个智能体返回工单详情时希望附带评论信息另一个却只要标题和状态。为了避免技能变成一堆 if 分支我在技能参数里增加了detail_level选项由调用方显式决定需要什么粒度的结果。这比在技能内部判断调用方是谁要干净得多也让跑测试的时候更方便。技能脚本写完之后别急着注册先做一件事用test-cases.json跑一遍典型场景。我的习惯是至少准备三个典型用例一个完全合法的参数用例、一个缺失必填参数的异常用例、一个底层服务返回非预期格式的容错用例。尤其是第三种用例它能暴露技能代码里最常出现的问题——对上游数据结构“过度假设”。5. 技能设计的第一性原则原子性、确定性与幂等性技能脚本怎么写可以学语法解决但设计一个技能到底该包含多少内容、怎么拆分、边界在哪这些属于设计决策。我在agent-skills项目里沉淀了五条第一性原则基本每条都是从实战的坑里爬出来的。第一条单一职责。一个技能只做一件能被用户清晰感知的事。我在某次开发时一开始把一个“查询工单并生成周报”的功能写成了一个技能因为自己觉得“这俩本来就是一个流程”。运行起来发现一个大问题模型只要调用这个技能就必须同时执行查询和生成两个步骤哪怕用户只想问一句“这周有没有紧急工单”它也要跑完完整的报表逻辑不仅浪费 token速度也慢体验很差。后来拆成“查询工单”和“生成周报”两个技能规划层能自由组合反而效率更高模型也更不容易出错。第二条确定性优先。一个技能在同样输入下返回结构必须是稳定一致的。这意味着技能内部最好不要有依赖当前时间的随机逻辑不要用不可控的列表排序更不要在前端脚本里做“智能判断”。我在排一个诡异 bug 时发现某技能偶尔会在返回数据里丢失字段排查半天发现是内部代码用了一个默认字典遇到缺失键就返回空值这次有这个字段下次没有。这种不确定性会直接破坏上层应用对技能结果的信任。第三条幂等性。同样的技能连续调用两次不会产生额外的副作用。对查询类技能这很容易做到但涉及写操作的技能就需要仔细设计比如在一个“创建工单”的技能里要利用外部系统的幂等键来避免重复创建在“发送通知”的技能里要支持去重机制。一个不幂等的技能会导致模型在任务重试时重复操作后果相当严重。第四条参数自解释。技能的参数名必须做到“看一眼就知道含义”。我曾经见过一个技能参数名是p1和p2代码里要加注释才能理解含义模型参数生成时更是一头雾水。参数名还应该避免歧义例如date不如start_datetype不如ticket_type。别觉得这是小事技能一旦多了光靠这个习惯就能省下大量沟通成本。第五条无隐形副作用。技能脚本执行过程中不应该偷偷修改任何外部状态除非这是技能的职责。比如一个查询技能内部悄悄写了一个日志文件这算隐形副作用因为调用方没有预期到这个行为会在系统里留下文件。如果某些操作确实需要就要显式声明比如在SKILL.md里写明“此技能会将查询记录写入审计日志”。沿着这些原则还有一个无法回避的问题技能的粒度怎么定我给出的经验法则是以“用户能否直接感知到这个结果”为标准。如果用户能直接看到技能返回的数据这个粒度就合适如果用户拿到结果还要经过很长一段加工才能用那说明技能拆得太细如果技能内部包含了多个不同阶段的输出说明拆得太粗。这个标准不一定适合所有场景但在大多数业务技能上都挺好用的。6. 注册与版本管理让智能体在几百个技能里快速找到正确的那一个技能写好了还需要进入一个智能体可以查询的注册表不然技能和没写一样。这是我从agent-skills中收获最明显的一环因为技能一多普通的“全部塞进系统提示词”方案立刻崩溃。这个项目里我用的是基于清单文件的注册机制每个技能目录里的SKILL.md被扫描生成一份全局技能清单智能体通过这份清单快速检索候选技能。技能清单的核心字段包括技能 ID、名称、用途、参数摘要、版本号、依赖项、执行文件路径。为了提高检索效率我把用途描述做成了两个版本的摘要——详细版和标签版。标签版只保留 10 到 20 个字的关键概念比如“工单 汇总 周报”详细版则是完整描述。这样模型在规划层做粗选时只需要扫描标签版确定候选后再阅读详细版文档长度天然就控制住了。技能入库时我还加了版本管理。每个SKILL.md文件里都声明了version字段并在技能目录内维护CHANGELOG记录。注册表生成时用技能文件的SHA-256哈希做指纹当技能内容变更而版本号没升时注册工具会警告防止有人改了代码忘了升级版本。这个做法在多人协作时特别有用避免出现“明明改了技能但其他应用还在用旧缓存”的尴尬局面。让智能体加载技能时权限控制也要提前想好。技能本身没有黑白名单的话模型在做规划时可能会调用超出当前上下文的敏感技能。我推荐每个技能在清单里声明访问级别例如只读、读写、管理员。规划层在筛选技能时会先根据当前任务的权限上下文过滤掉不合法的选项。这一步不是可有可无的安全加固而是一个技能库成熟的设计。某个技能的权限声明有误在我这里发生过不止一次一个只能读已归档工单的技能因为忘了约束时间范围结果被模型拿去查了几年前的敏感数据。版本管理的另一层用途是解决跨智能体复用。我维护了一套统一的技能清单生成命令项目里任意一个智能体附加到同一个技能库时可以按需拉取全部技能或某个分组技能。某 B 团队想要复用 A 团队的“过期工单催办”技能并不需要复制代码只需要在自己的智能体配置里声明依赖这个技能 ID 和版本号。这个机制让不同业务线的智能体共享同一套底层能力避免了一次又一次地重复造轮子。7. 测试与验证搭建一个能兜底的最小测试台技能注册进库之后最怕的是某天接口偷偷变了技能返回结构全乱模型还蒙在鼓里继续调用。所以agent-skills里特意安排了一个轻量级测试台用来在技能出问题前拦截住。测试台的核心逻辑非常简单就是一个循环遍历技能目录下的所有test-cases.json依次执行技能脚本比对返回结果的ok字段和data的 key 集合是否符合预期。不要小看这个粗粒度验证它能拦截 80% 的回归错误。我自己遇到过一个典型问题底层接口某天突然把字段timestamp改成了created_time测试台的 key 校验立刻报了错而如果没有这套测试这个变化会在智能体实际调用时才暴露最终用户看到的是一堆解析异常。真正实践过程中测试台有几个容易踩的坑我必须多说几句。第一个坑是超时分类混乱。技能调用外部接口时必须区分三类超时连接超时、读超时、整体超时。我之前只设了一个总超时时间结果外部接口偶发变慢时所有技能都卡到极限才返回任务执行链路被拖得非常严重。在agent-skills测试台里我引入了一个规范每个技能必须显式声明自己的总超时上限默认 10 秒有特殊需求的技能可以覆盖但需要写明理由。这个规范主要是为了逼开发者思考技能的耗时特征而不是让它自然长成怪物。第二个坑是 stderr 污染。技能脚本执行时很多内部日志会打到标准错误输出这本来没什么但当我把 stderr 内容一起带回给模型作为执行反馈时模型的上下文很快就被无关日志塞满反而忽略了真正的返回数据。解决办法就是测试台和技能脚本之间约定好正常运行只消费 stdout 里的结构化数据stderr 只用于调试且绝对不能包含业务结果。这个约定看起来平淡无奇但能帮你免掉一大半调试时间。第三个坑是缓存状态影响测试稳定性。有些技能为了性能加了内存缓存测试台连续执行同一用例时第二次结果因为缓存已经存在返回速度极快掩盖了真实的接口延迟。我的做法是测试台支持cold_run参数强制每次执行前清理技能自身的缓存状态保证每次测试都从一致的起点开始。技能本身也要注意不要把缓存状态写进持久化文件避免一个测试污染下一次执行。测试台跑通了技能库的闭环也就形成了技能从接口侦察开始经过编码、设计审查、注册、版本管理、测试验证最终成为智能体可以稳定调用的一块“积木”。每次新增技能我都按这条链路走完整流程这套做法现在在我这里已经成了基础设施级别的默认动作。项目跑到现在我最大的感受是做智能体应用看起来难的是模型提示词怎么调、外接工具怎么接实际上真正的分水岭是有没有人愿意把技能治理当成工程来做而不是当成临时脚本去堆。agent-skills这个项目让我沉淀了一套从技能定义到测试验证的完整方法论过程里有重构、有反复、也有过推倒重来的纠结但眼前的回报是新需求过来时团队不再担心改动一个技能会惊动另一个系统——因为边界清晰了风险就可控了。最后再分享一个小技巧每写一个新技能我都会先手写一遍它的SKILL.md版本号也好参数描述也好先写下这份“说明书”再动代码。别问为什么试两次你就知道了。