“skills”这个词最近在技术社区里的出镜率高得有点吓人。大半年以前大家还在绞尽脑汁把各种能力塞进一段越来越长的系统提示词里现在风向已经变了讨论的重点变成“技能库”里该放几张技能卡、每张卡怎么写才不会让Agent犯迷糊。这篇文章不聊宏大的Agent理论就从一个很实际的需求出发如果我想给自己的Agent搭一套可复用、可维护、可排雷的技能库目录该怎么设计技能描述怎么写上线之后哪些坑会一个个冒出来。适合刚开始接触Agent开发的工程师也适合被提示词工程折腾到头秃、想换个思路的实践者。1. 为什么Agent需要“技能库”而不是更长的系统提示词1.1 塞进提示词的问题在哪先说我自己踩过的弯路。最早做Agent我的习惯是“能力不够提示词来凑”。聊天、检索、写周报、提取待办、生成表格……全部塞进一段系统提示词。一开始只有两三个功能还行等塞到七八个问题就开始冒头了模型经常抓不住重点用户说“帮我把今天的记录整理一下”它可能先触发检索再触发写稿最后输出一堆跟需求无关的内容改其中一个能力我得把其他所有流程重新测一遍因为互相干扰的边界说不清。这个现象背后其实有个朴素的原因系统提示词是一条线性排列的指令流模型要在一大段文本里自己判断“现在该用哪段规则”。能力越多规则之间的注意力竞争就越激烈决策就越不稳定。还有一个被很多人忽略的隐性成本——token。提示词越长每次请求的输入token越高响应速度越慢费用也越高。可那些规则真的每次都用得上吗多数时候Agent只需要其中一段规则完成任务其余内容是拖累。后来我换了个思路——把每项能力从提示词里拆出来做成独立的“技能卡”需要时由模型按场景选择再加载。这就像给Agent建了一个随取随用的工具架而不是把所有工具焊死在手术台上。1.2 技能库带来的三样好处抛开理论包装技能库真正给我的项目带来的是三样东西。第一是解耦。每项能力的规则、示例、边界都锁在自己的技能卡里改周报技能完全不影响会议纪要技能。版本回退、单点调优都变得特别轻。第二是复用。同一个“日期解析”技能可以在周报、会议纪要、事项提取里被反复引用换一个Agent项目把技能目录拷过去就能继续用不用重新写第二遍。第三是可测试。技能被独立后我可以用固定的测试用例单独验证“周报技能今天有没有把事情做对”而不是每一次都跑整个Agent流程。为了帮助理解我一直用一个类比请了个新员工你不会把公司所有制度塞进一次入职培训里而是给他几本岗位标准作业指导书——做什么、不做什么、遇到问题找谁。技能卡就是Agent的岗位SOP目录就是他的书架。1.3 技能和工具有什么区别这里还要澄清一个容易混淆的概念技能和工具不是一回事。很多Agent框架支持“工具调用”把函数暴露给模型执行那是给模型增加可执行的原子动作。技能通常是一整套处理流程它内部可能会调用工具但更重要的是它规定了“怎么把事做对”先做什么、按什么格式、有哪些禁忌、什么情况下该停下来问用户。工具负责能不能做技能负责做不做对、什么时候做。理解了这个区别再去设计技能卡思路就会清晰很多。2. 一张技能卡的完整解剖六个字段决定成败技能卡写成什么样才算合格我自己经过几轮迭代后总结出六个必填字段。先说结论下面这张表可以当速查卡。字段作用最容易踩的坑name技能唯一标识名字太泛或与目录不一致description告诉模型什么时候该用、什么时候不该用只写正面触发条件漏掉否定条件parameters调用技能需要的参数用JSON Schema声明类型太宽松模型传了非法格式instructions技能执行的具体步骤与输出格式步骤含糊模型自由发挥examples1到3个典型输入输出样例样例太少模型学不会constraints边界护栏和禁用行为不写结果不可控2.1 六个字段各自负责什么name的命名要克制。我习惯用小写字母加中划线比如weekly-report、meeting-minutes、date-utils。核心规则只有一个name只做标识不在name里表达业务细节。把语义留给description。否则一旦技能数量上了两位数光看名字根本分不清谁是谁日志排查也会变得很痛苦。description是整张卡片的灵魂也是决定路由质量的第一要素。它要回答两个问题什么时候该触发这个技能正例什么时候不该触发反例。很多初版技能卡只写“当用户需要生成周报时使用”效果很差。因为用户表达千奇百怪模型只能靠模糊语义猜。后来我改成双段式写法第一段描述意图场景第二段列出明确的否定条件。比如“当用户的话题与周报无关时不要使用”“如果用户只是让你总结邮件内容不要使用当前技能”。这段否定条件对降低误触发的作用比任何调参都明显。parameters用JSON Schema声明。模型拿到schema才知道要向用户收集哪些信息、以什么格式传给技能。这里有个关键经验能加pattern约束就加pattern约束。日期参数如果只声明type: string模型很可能传“上周五”这种自由文本后续格式化直接崩在schema里加上正则约束并配合instructions里的“先转换为YYYY-MM-DD再输出”基本能杜绝这类问题。instructions是技能的实际执行正文。它要足够具体但不要写成论文。我习惯按编号写操作步骤每步只说一件事并且明确输出格式。比如周报技能先按日期倒序汇总提交记录然后按“成果、问题、明日计划”三段归类最后输出的每条工作项必须包含完成度百分比。步骤越具体模型跑出来的结果越一致。examples给1到3个就行不用多。样例的作用是帮模型理解输入和输出的映射关系尤其是输出格式的细节。我给每个技能配置一个“用户提问→期望输出”的短样例模型看完样例基本能对齐格式。constraints是可选但强烈建议的护栏。它写的是“绝对不要做的事”比如“不要编造用户没提到的数据”“信息不足时先提问不要硬生成”。这个字段不参与正常执行但能在关键时刻拦住模型的自由发挥。2.2 一张可用的技能卡长什么样我用一个真实在维护的技能卡做完整示例。它叫weekly-report负责把本周工作内容整理成结构化周报--- name: weekly-report description: 当用户需要整理本周工作内容并生成周报时使用。 适用场景用户提供本周的工作记录、提交列表、会议要点。 不要使用的情况用户只是在讨论文档、邮件或其他内容 没有提到“周报/本周工作”用户要求的是周总结文章而非工作周报。 version: 1.3.0 parameters: type: object properties: week_start: type: string description: 本周起始日期格式YYYY-MM-DD pattern: ^\\d{4}-\\d{2}-\\d{2}$ highlights: type: array items: type: string description: 用户明确强调的重要成果 required: - week_start instructions: | 1. 把周起始日期换算成本周结束日期起始日加6天。 2. 按日期倒序整理各项工作内容去重。 3. 按“本周成果”“遗留问题”“下周计划”三类组织输出。 4. 每条工作项标注完成度百分比不能确定的标注“待确认”。 5. 如果用户没有提供足够信息先提问不要直接生成。 examples: - user: 这周做了登录模块和支付联调周五有个权限bug没解决 result: | 本周成果完成登录模块开发完成支付流程联调。 遗留问题权限校验bug未解决。 constraints: - 禁止编造用户没有提到的工作内容。 - 禁止把非工作类内容强行归类为本周成果。 ---看这个例子能发现几个细节version字段是我后来加的方便版本管理description的第二段就是前面反复强调的否定触发条件week_start的pattern把日期格式锁死examples用一个真实对话做示范。这些细节单看都不起眼组合起来却能让路由准确率明显提升。3. 从零搭一个可用的技能加载器目录、元数据与注册机制3.1 目录结构与加载器有了技能卡接下来要解决的问题是这些卡片放在哪里怎么被Agent识别并加载。我建议把每个技能放在独立目录里目录名就是技能名目录内至少有一个SKILL.md。目录结构长这样~/agent-skills/ ├── weekly-report/ │ └── SKILL.md ├── meeting-minutes/ │ └── SKILL.md ├── common/ │ └── date-utils/ │ └── SKILL.md └── registry.jsonregistry.json可以放一个白名单只有出现在白名单里的技能才允许加载避免目录里混入垃圾文件影响后续逻辑。如果项目刚开始也可以不做白名单直接扫描目录。加载器的核心逻辑其实很简单遍历目录解析每个SKILL.md的前置元数据把技能卡注册进一个字典。下面是我早期项目里用的一段极简实现适合拿来扩充import pathlib import yaml SKILLS_DIR pathlib.Path.home() / agent-skills def split_front_matter(text: str): if text.startswith(---): parts text.split(---, 2) return yaml.safe_load(parts[1]), parts[2].strip() return {}, text.strip() def load_skills(base_dir: pathlib.Path SKILLS_DIR) - dict: registry {} for skill_dir in base_dir.iterdir(): if not skill_dir.is_dir(): continue skill_file skill_dir / SKILL.md if not skill_file.exists(): continue meta, body split_front_matter(skill_file.read_text(encodingutf-8)) name meta.get(name, skill_dir.name) registry[name] {meta: meta, body: body} return registry skills load_skills()这段代码没有做参数校验、没有做缓存骨架就位后你会遇到三个我实际踩过的细节问题。第一个是元数据解析的容错。有的技能卡前面写了YAML front matter有的直接就是纯Markdown两种格式在split_front_matter里都要能处理。上面的代码已经兼容了这两种情况。第二个是名称一致性。name要跟目录名一致否则在日志排查的时候会出现“目录里叫weekly-report注册表里叫weeklyReport”这种让人抓狂的情况。我建议代码在加载时做一次强制校验meta里的name不等于目录名就抛出警告。第三个是加载顺序。如果技能之间有依赖比如weekly-report需要date-utils注册表的顺序不一定等于调用顺序。我的习惯是先加载common目录下的共享技能再加载业务技能避免调用时才发现依赖项还没注册。3.2 触发机制和参数校验加载完之后真正决定技能用不用得起来的环节是“触发机制”。现在主流做法不是硬编码规则而是让模型看着技能列表做语义路由把每个技能的name和description拼成一段候选列表交给模型判断“用户当前的需求该选哪个技能”。这也是为什么上一节反复强调description质量——在语义路由模式下description就是模型做决策的依据。路由对了一切好说路由错了后续全白搭。实际操作中还有个小技巧模型做出技能选择后不要立刻执行先做一次参数校验。你可以让模型输出结构化的调用意向再用JSON Schema校验参数是否完整、格式是否正确不合格就打回让模型补充。这一步看着多余却能挡掉相当一部分低级错误尤其是日期格式错误和漏参数。4. 技能复用与版本管理多人协同场景下的组织经验技能库从一个人用到多个人用问题会逐渐暴露。这里我讲几个比较实际的组织经验。4.1 公共技能不是抽越多越好先说技能之间的复用。很多技能其实有公共部分日期换算、文本摘要、去重合并。如果每个技能都自带一份改一个公共逻辑就要改十几个目录。比较好的做法是把公共能力抽成独立技能放进common命名空间让上层技能在instructions里引用它。weekly-report的instructions里可以写一句“日期换算请调用date-utils技能不要自行推算。” 配合Agent框架的依赖解析上层技能就能自动拉起底层技能。不过公共技能也不是越抽越多越好。我个人的判断标准是同一段逻辑被三个以上业务技能用到才值得抽出来。只被用一次的东西没必要上升到公共层否则项目里会积累一堆没人维护的“公共库”。技能库的维护成本是实打实的每多一个技能路由列表就多一项模型的选择空间就多一分噪音。引用关系还有个容易出错的地方循环依赖。技能A引用了技能B技能B又引用了技能A轻则无限递归重则整个任务卡死。我加依赖时一定会检查引用链凡是出现环的情况都拆掉一层。4.2 命名空间与版本锁定然后是命名空间规划。如果技能库由多个团队或模块共享我习惯分成两层common放全局共享技能业务目录按模块划分比如auth/、billing/。目录名字本身就是命名空间避免不同模块出现同名技能后互相覆盖。这个设计特别像代码仓库里的包管理只是对象从函数变成了技能卡。版本管理是多人协同里最容易翻车的部分。我的做法是用Git管理整个技能库目录每个SKILL.md的front matter里带上version字段。公共技能升级时要像发版一样记录变更比如date-utils从1.1升到1.2改了什么要写进changelog。关键是依赖锁定业务技能引用公共技能时要声明兼容的版本范围避免公共技能升级后把下游技能的行为静默改变。我还见过一种很实用的做法——给技能打tag。当某个技能在某次任务里表现得特别好或特别差就在技能卡里记录当时的输入输出样本并给版本打上标记。后续在多个版本的同一技能之间做对比时这个标记就是最直接的证据。多人协作时也要约定改了别人的技能卡要在提交信息里说明改动点和影响范围。这是基本礼仪但真没几个团队在做。4.3 定期用数据给技能库做体检最后说评估和淘汰。技能库不是建完就完事的静态资产它需要定期体检。我每个月会跑一遍自己整理的测试集把每个技能的真实触发率、误触发率、任务完成质量分记下来。下面是我常用的评估表模板技能名测试用例数触发准确率误触发次数输出质量评分结论weekly-report2095%14.6/5保持date-utils35100%05/5保持meeting-minutes1878%33.8/5重写描述触发率低、误触发多的技能通常不是逻辑问题而是描述问题质量评分低的技能往往需要扩充instructions或补充examples。用数据说话技能库的迭代方向会非常清晰。这套评估体系不用做得很重一个表格加一个定时提醒就够了重点是把“感觉某个技能不好用”变成“数据说明某个技能需要改”。5. 实测踩坑技能描述写不好Agent会怎么坑你这部分写成踩坑记录三个都是真实项目里反复出现过的。每个坑我都会还原排查链路希望你在上线前就能避开。5.1 坑一description漏写否定条件导致误触发现象是用户对Agent说“帮我总结一下这封邮件里这周的工作安排”结果Agent调用了weekly-report而不是邮件总结技能。单看模型决策其实没毛病因为weekly-report的描述里写着“当用户需要整理本周工作内容时使用”用户确实提到了“这周”。但这不是周报需求是邮件总结需求。排查链路打开会话日志看技能路由决策记录发现模型在候选列表中给weekly-report打了最高分再对比两个技能的描述发现问题出在weekly-report没有写“不要使用”条件。修复方式是给weekly-report的描述补上否定句“当用户只是总结邮件、文档或聊天记录中的日程时不要使用该技能。” 复测后误触发率从23%降到3%左右。这个案例给我一个教训写description时否定条件要和肯定条件一样认真对待。5.2 坑二参数schema太宽松模型传了自由文本现象用户说“从上周三到这周三的周报”Agent选择weekly-report后把week_start填成了“上周三”。pattern校验拦不住因为schema只是type: string。下游格式化日期时直接报错任务中断。排查链路从错误日志看到是日期解析异常回看模型生成的参数week_start是“上周三”不是标准格式。根因是parameters里只写了type: string没加patterninstructions里也没要求模型先把日期转成标准格式。修复两步走schema加pattern正则instructions加一条“所有日期参数必须降维成YYYY-MM-DD格式后再进入后续流程”。上线后此类错误基本清零。这类坑很隐蔽因为不是每次都触发。模型心情好就传标准格式心情不好就传自然语言稳定性完全看运气。只有把约束写死在schema里才能把变量变成常量。5.3 坑三两个技能抢活输出互相覆盖现象用户让Agent“提取会议记录里的待办事项”结果facts-highlight技能和meeting-minutes技能都被触发输出里既有高亮摘要又有会议纪要格式混乱。这不是模型抽风而是两个技能的description都包含“提取”和“会议”这两个词语义空间高度重叠模型拿不定主意就两个都选。排查链路看路由日志发现两个技能得分都超过阈值检查两个description发现它们都没声明边界。修复方式是在两个技能里都加上互斥声明facts-highlight加“本技能只处理事实性信息提取不负责会议纪要结构化”meeting-minutes加“本技能只处理会议纪要结构化不负责待办高亮”。简单两句冲突率肉眼可见地降了下来。这件事说明一个道理技能库的边界是用文字画出来的描述里没有边界模型就不知道哪里有边界。修复手段也出奇一致——把缺失的否定条件、格式约束、互斥声明补进description和instructions里而不是去调什么玄学参数。我在实际维护技能库的过程中最深的体会是技能卡是给Agent看的岗位说明书写得含糊Agent就含糊地执行。这套东西的成本主要在前三周一旦把常用技能的描述打磨到位后面基本是躺着收红利。最后分享一个小技巧在每条技能描述的最后加一句“如果你不确定是否匹配该技能请直接询问用户不要强行使用”。就这一句话误触发率能再降一大截。真不用怀疑技能库的收益就是这么来的。
