写了好几个Agent项目之后我越来越觉得Agent本身的模型能力反而不是最要命的瓶颈真正决定一个Agent好不好用的是你到底喂给了它多少高质量的“技能”。GitHub上那个热度一直不减的agent-skills话题聊的就是这件事。很多人把Agent当成一个啥都能干的万能盒子结果真用起来发现它经常“这也不会、那也不会”问题恰恰出在技能库太薄、太散、太随意。今天的这篇东西我就是想把自己在这块踩过的坑和攒下来的方法完整摊开讲一讲。内容不只适用于搞AI工程的人只要你的工作里需要接触Agent、需要梳理能力边界、甚至只是想把个人经验做成可复用的积累这篇文章都能给你一套可以照抄的框架。1. agent-skills到底在拆解什么1.1 技能不是prompt也不是工具很多人刚接触agent-skills的时候第一个困惑就是技能到底是什么它跟prompt有什么区别跟工具调用又是什么关系我把这三者的边界先捋清楚后面所有的设计和实操才有讨论的基础。Prompt是你跟模型对话时的“一次性指令”说白了就是你此时此刻想让模型干什么。工具是Agent与环境交互的“肢体”比如搜索、调API、读写文件。而技能是介于两者之间的、可以沉淀和复用的“操作能力包”。用一个生活化的类比来说Prompt相当于你临时教一个新人“今天把这份表格归档好”工具相当于给他电脑和文件夹而技能相当于一套已经写成文档的《归档标准操作手册》里面包含了判断规则、执行步骤、异常处理、常见错误案例。有了这本手册你不需要每次从头教新人也知道什么叫“归档完成”。这也就是agent-skills的核心含义——把Agent能做的事情从“临时吩咐”升级为“稳定调用”。技能一旦沉淀下来就可以像搭积木一样被复用到不同的任务场景里。这也是为什么现在主流的Agent框架比如Anthropic、OpenAI都在专门定义Agent Skills的规范和目录结构而不是让你把啥都塞进system prompt里。1.2 技能体系的三层结构会做、能做、可复用实际构建agent-skills的时候我习惯把技能体系拆成三层每一层的目标和设计要求都不一样千万别混在一起。第一层是“会做”。这一层决定了Agent面对一个具体问题时有没有对应的处理路径。比如“给定一份CSV输出数据质量报告”——这个动作有没有标准化还是每次都要临时想会做层的设计要求你对Agent的常用任务做穷举和归类把高频动作固化成流程。第二层是“能做”。会做不等于做得可靠。技能真正落地的时候必须考虑边界条件和异常处理。拿上面的数据质量报告举例如果文件有100万行怎么办如果有乱码编码怎么办如果列名重复怎么办这些细节如果不写进技能里Agent就会在压力场景下“变形”结果看着像做了实际上全是坑。第三层是“可复用”。这是agent-skills里最容易被忽略的一层。很多团队把技能写得跟临时脚本似的只针对某个特定任务换个数据源、换个场景就完全不适用了。设计良好的技能应该像接口一样——输入参数清晰、输出标准固定、中间逻辑与具体业务解耦这样才可能跨项目、跨Agent地复用。三层技能叠加起来才是真正意义上的agent-skills体系。只追求第一层做出来的东西就是个“花架子”只追求第二层做出来的东西是个“孤岛”三层的目标都兼顾技能库才能滚雪球一样自我放大。2. 技能拆解与设计思路2.1 从任务反推技能清单构建agent-skills的第一步不是去写技能而是去盘点你到底需要哪些技能。这里有一个非常实用的方法叫任务反推法。把你的Agent想象成一个人。你可以问自己我希望他每周帮我完成哪些工作把这些工作一条条写下来不需要严谨想到什么写什么。比如每周汇总项目进度生成周报监测关键词的舆情动态输出简报清理和归档临时文件解析客户邮件并提取待办事项定时抓取竞品价格并生成对比表写完这个清单之后再逐个分析完成这件事需要哪些前置知识需要调哪些工具需要遵守什么规则这个分析过程自然会产出一张“能力缺口列表”也就是你当前Agent还不具备、但完成这些任务必须有的技能。我在实际操盘项目时会用一个简单的表格来做这个盘点把任务、需要的技能项、当前状态、优先级列出来。这里的关键经验是先不要追求技能覆盖的广度先把最影响周报、月报或者核心业务流的三个任务做成扎实技能。把三五个技能打磨透效果永远好过一次性铺二十个半成品技能。2.2 技能的用户视角谁在用达成什么目标技能设计这个环节特别容易犯“自嗨”的毛病。我自己早期也会这样觉得某个技能好酷就写进去了结果实际落地的时候根本没有人用。后来我学乖了每设计一个技能都先问自己两个问题。第一这个技能的“用户”是谁是你自己在跟Agent对话时零散调用还是其他团队成员也会用到如果是后者技能的可读性、可解释性就非常关键不能只是你一个人看得懂。第二这个技能到底帮用户达成了什么目标节省了时间减少了出错还是处理了以前处理不了的事这两个问题背后其实是一套“目标导向”的设计思路。技能本质上是让Agent在执行任务时有一套更可靠的“行为准则”如果行为准则的目标不清晰那写出来的东西就很容易变成四不像——既不像文档又不像代码更不像规范。我建议你在为agent-skills定义目标时遵循“一个技能只做一件可量化的事”。比如“将非结构化的会议录音转换为带行动项的结构化会议纪”就是一个合格的目标描述。它边界清楚、结果可验证、任务颗粒度适中。反过来“智能处理音频文件”这种描述就太虚了写出来的技能一定也是虚的。2.3 技能的颗粒度多大才合适颗粒度是agent-skills里争议最大、也最难把握的话题。技能写小了变成一堆碎渣调用起来要考虑步骤编排技能写大了变成一个大杂烩Agent执行起来反而不知道到底该按哪条路径走。我的经验是一个技能的内部复杂度应该控制在“一个人30分钟内能从头讲清楚怎么做”这个程度。如果30分钟讲不清楚就拆成两个如果5分钟就讲完了而且跟别的技能有高度重叠就考虑合并。举个例子“网页信息抓取”可以拆成“抓取静态页面内容”、“抓取动态渲染页面内容”、“抓取需要登录的页面内容”这几个细分技能吗从技术上可以但从使用角度不推荐。因为对用户来说他关心的是抓取这件事能不能成不关心页面是静态还是动态。合理的做法是保留一个“网页信息抓取”技能内部写清楚判断逻辑和分支处理先尝试静态解析发现是动态页面就切换渲染模式需要登录就走认证流程。这样用户使用成本最低Agent内部的复杂度由技能文档来消化。判断颗粒度还有一个很务实的指标看这个技能被调用时的“入口描述”是否自然。如果用户在对话里很自然地会说出“帮我把这个页面抓下来”那这个技能的存在是有意义的。如果他需要很费力地描述一堆前置条件才能唤起技能那说明颗粒度已经错了。3. 核心细节解析与实操要点3.1 技能文件的结构化标准从工程实现的角度来看一个能被Agent稳定识别和调用的技能通常以文件夹为单位组织。我在这块沿用了比较通用的项目结构但做了一些自己的取舍。这里给大家展示一个模板skill-name/ ├── SKILL.md # 技能的核心描述文件Agent主要读它 ├── scripts/ # 可执行的脚本代码按需放 │ ├── main.py │ └── utils.py ├── assets/ # 非代码资源模板、参考样例等 └── tests/ # 测试样例验证技能是否可用SKILL.md是整个技能的“灵魂”。很多人在写SKILL.md时喜欢长篇大论写背景、写动机、写抽象描述这些对Agent来说基本都是噪音。Agent真正需要的是识别我什么时候该用这个技能、正确使用它的步骤是什么、有哪些输入输出参数、有哪些边界和陷阱。以下是我长期迭代后固定下来的SKILL.md模板你可以直接拿去做底稿--- name: 技能名称 description: 一句话说明技能用途以及什么时候触发 when_to_use: 触发条件尽量写具体场景 version: 1.0.0 --- ## 目标 这个技能用来解决什么问题成功的标准是什么 ## 输入 需要的参数每个参数的类型、含义、示例 ## 执行步骤 1. 第1步操作及理由 2. 第2步操作及理由 3. 第3步操作及理由 ## 输出格式 产出的数据结构或文档格式要求 ## 边界与注意事项 哪些情况不该用这个技能哪些情况会引发什么已知问题 ## 常见错误示例 曾经犯过的错以及如何避免这个模板看起来简单但每一节都有它的设计理由。加粗和缩进不是为了好看是为了让Agent在解析时能更快定位关键信息。description和when_to_use这两个字段尤其重要——它们决定了Agent能不能在合适的时机主动想到调用这个技能。3.2 技能描述怎么写才不被大模型“无视”写SKILL.md有一条心法描述你的技能时你不是在写给同事看而是写给一个“理解能力强但视野狭窄”的实习生看。大模型能读懂复杂的逻辑但如果你的描述太抽象、太模糊它就没法把当前任务和这个技能关联起来。我踩过的一个很深的坑是有一版技能描述里写“本技能用于资料处理”结果Agent在用户提出“帮我整理一下这份文档里的客户名单”时完全没有触发这个技能。原因就是“资料处理”这个描述太泛了没有任何一个词能让模型跟“客户名单”这个具体任务产生联系。后来我把描述改成了这样description: 当用户需要从PDF、Word或网页内容中提取联系人信息姓名、电话、公司、职位 并整理成结构化表格时使用。常见用户表达包括 “提取客户名单”、“整理一下联系方式”、“把这段内容里的公司信息列出来”。改完之后技能触发率肉眼可见地上升了。这里面有一个底层逻辑大模型做意图识别时本质上是在做“语义匹配”你给出的描述里包含的具体场景词越多匹配的命中率就越高。所以在设计技能库的时候你必须在描述的detail和flexibility之间找平衡——既不要太泛也不要太窄最好把高频的用户表达原话直接写进去。3.3 技能覆盖的场景是否需要有明确的“不做什么”技能文档里最难写、但最见功力的一节是“边界与注意事项”。很多人会觉得技能嘛当然是能做什么写得越全越好为什么要写“不做什么”这不是给自己设限吗恰恰相反。Agent在调用技能或执行技能的时候最怕的就是“权力过大”。你不划定边界它就会在模糊地带自由发挥而自由发挥的结果往往是不可控的。举个例子你给Agent设计了一个“自动生成报告”的技能。如果你只在描述里写“生成营销周报”没有写“不要对数据进行杜撰和推测”Agent遇到缺失数据时可能会强行编一个数字填进去而不是标记“数据缺失”。这是一件非常可怕的事因为不明真相的人看到报告会当成真的。所以在设计skill时我要求每个技能必须回答这几个“不做什么”哪些输入是你明确不处理的比如“超过10万行的数据不予处理请在输入前先抽样”哪些动作是禁止的比如“不修改客户的原始数据文件只生成新的结果文件”什么情况下应该中止执行并请求人工介入比如“检测到敏感信息时停止输出并告警”这些边界写清楚之后Agent的行为可靠程度会提升一个量级。你以为你是在“限制”技能其实你是在给技能灌入“判断力”。3.4 技能测试不能只在顺利路径上验证Agent技能的测试跟传统软件测试有相似之处但有一个非常显著的区别软件的输入空间是相对有限的而Agent技能的输入空间几乎是无限的——自然语言表达千变万化同样的意图可以有几十种说法。所以我做技能测试的时候会专门建立一个“刁钻输入集”。里面包含几类典型场景措辞口语化的输入、带噪音信息的输入比如用户倒了一堆背景故事、边界条件输入比如文件为空、数据全是缺失值、以及最容易触发幻觉的歧义输入。拿“客户名单提取”这个技能举例测试集至少包括标准输入“从附件PDF里提取客户名单”口语化输入“把那个文件里的老板们拉个表”歧义输入“给我列一下联系人”——没说清楚是邮件里的还是文档里的异常输入“附件是图片格式没有文字层”测试的目的不是为了追求100%的正确率——这不现实。而是用来明确两件事一是技能的触发边界在哪里二是技能执行后输出的质量下限在哪里。如果测试过程中发现“口语化输入”触发了别的技能代码或者“歧义输入”导致Agent胡乱猜了一个方向那这些case不能简单归类为“用户表述问题”而是要回炉去改技能描述和决策流程。另外技能测试还有一个特别值得做的动作让一个没有看过你技能文档的人直接只读SKILL.md来执行一次任务。如果这个人能顺利按文档完成操作那么这个文档对模型的可用性大概率是合格的。这个方法实操成本低但效果出奇地好强烈推荐。4. 实操过程与核心环节实现4.1 实操第一步搭建技能库的目录索引等你手上的技能数量开始变多比如超过五个你就不能只靠一摞散乱的SKILL.md过日子了。这时候需要做一个技能索引文件。它的作用类似于图书馆的目录卡片让Agent在调用任意技能之前能快速感知到自己手上有哪些“武器”。我目前项目里的技能库结构是这样的agent-skills/ ├── index.md # 全量技能目录概述每个技能的能力 ├── skills/ │ ├── meeting-minutes/ # 会议纪要技能 │ ├── report-generator/ # 报告生成技能 │ ├──># Agent技能目录 ## 会议纪要meeting-minutes - 用途录音/文本转结构化纪要 - 入口描述整理会议纪要、记录会议要点、提取行动项 - 文件位置skills/meeting-minutes/SKILL.md ## 数据清洗data-cleaner - 用途清理不规范表格数据 - 入口描述清洗数据、处理缺失值、统一格式 - 文件位置skills/data-cleaner/SKILL.md技能索引的body不需要大重点在于精确。每一条都保证“一眼就知道这个技能是干嘛的、什么表达会触发它、真正的内容去哪找”。4.2 实操第二步用SKILL.md让Agent从“想”到“做”技能功能的高低除了文档写得好不好之外还在于Agent的执行链路。很多人以为写了SKILL.mdAgent就会自己照着执行——真实情况没那么简单。Agent在执行一个技能时本质上要经历“理解技能目标 → 解析当前任务 → 拆解执行步骤 → 调用工具或代码 → 校验输出”五个阶段。SKILL.md写得再漂亮如果执行链路的衔接有缝隙技能就会在运行中“漏气”。我常用的做法是在每个技能内部配置一个轻量级的“执行脚本壳”。它不干实际的业务而是负责协调整个流程。比如会议纪要技能主脚本的逻辑骨架大概是def run_meeting_minutes(input_path, templatedefault): # 1. 校验输入文件存在性 # 2. 判断是音频还是文本 # 3. 若是音频做转写若是文本直接解析 # 4. 按SKILL.md里的输出模板生成结构化纪要 # 5. 提取行动项与负责人单独输出清单 # 6. 校验结果发现缺失字段则标记并请求确认这个“壳”的重要价值在于把Agent的“判断动作”和“执行动作”区分开来。判断动作可以由大模型完成比如判断输入是音频还是文本但一旦判断完成后续的机械操作转写、解析、格式化交给确定性代码既快又不会犯错。4.3 实操第三步打通技能与项目的上下文技能库建好之后另一个必须处理的问题是技能如何跟具体任务上下文对接。因为技能是通用的而每次任务是有具体背景的。如果Agent不把任务的三要素数据源、输出要求、关联项目跟技能的输入结构对齐技能便无法正确被调用。我在这块踩过一个非常典型的坑。最初的技能库设计里数据的传入方式非常单一——只接受“输入一条文本返回一个结果”。直到有一天需要Agent批量处理一个文件夹里的几十份简历我才发现单个输入式的技能设计完全不可用Agent每次只能处理一份处理完还要手动喂下一份。后来我把技能的输入抽象成了两层任务输入task input和上下文输入context input。任务输入是技能执行时真正需要的核心信息上下文输入是技能理解这份任务所处环境的辅助信息比如“这是某项目三月的简历池”、“这个表格来自某系统的导出”。上下文信息不直接参与算法逻辑但能显著影响Agent对结果的判断口径。你在设计任何技能时建议一开始就预留context这个输入维度。它不一定每个技能都用得上但一旦用上技能的泛用性和正确性都会有一个质的提升。4.4 实操第四步验证与迭代闭环技能开发完之后不是扔进技能库就万事大吉。真正的agent-skills体系必须跑在“开发-测试-反馈-迭代”的闭环上。我建议每个技能在执行后都强制Agent输出一段简短的执行日志记录三点调用了哪个技能、任务输入是什么、输出结果是否符合预期。这些日志不要丢进垃圾桶它们是你迭代技能库的一手素材。比如你某天发现接触提取技能开始频繁出错翻开执行日志一看原来是最近输入的文档格式换了PDF变成了扫描件。那你就可以有针对性地在技能里加一步“先做OCR文字层检测”而不是在整个系统层面瞎找原因。还有一个容易被忽视的迭代方向观察Agent每次做完之后用户是不是还要手工修正很多地方。如果有千万别先骂Agent笨先把那些修正动作收集起来看看能不能把它们写成技能里的处理分支或者新的子技能。真正好用的技能库是在一次次“用户修正”的反馈中“长”出来的——而不是一开始就设计得十全十美的。5. 常见问题与排查技巧实录5.1 技能不被触发或触发错乱的排查路径这是agent-skills实践里遇到频率最高的问题。技能明明写好了也放在技能库里但用户提出需求时Agent就像没看见一样完全不调用或者偶尔调用了调用的却是另一个八竿子打不着的技能。我排查这个问题的顺序基本上固定是三步。第一步查“路由”看一下Agent最终拿到的系统提示和上下文里到底有没有包含技能描述。如果技能描述压根没被塞进上下文那这个技能永远不会被触发。第二步查“描述”如果技能描述确实在上下文里就看描述里有没有覆盖用户这次表达的关键词和场景。大模型的匹配机制更依赖“语义聚类”你的描述越贴近用户的自然表达越容易被唤起。第三步查“冲突”检查一下是否有多个技能的触发条件重叠了导致模型不知道选哪个。尤其是新技能跟老技能功能相似的时候容易触发错乱。如果你做完了这三步还没解决可以试试一个暴力但有效的方法在技能库里加一个“用户澄清钩子”——让Agent识别到“任务尴尬地带”时反过来问用户一句“你是想提取联系人还是想做整个客户信息的格式整理”这能快速把路由问题从模型侧转移到交互侧降低了误触发的风险。5.2 技能执行结果不稳定的原因与修正同一个技能第一次调用效果很好第二次调用却翻车了。这在agent-skills里很常见也最容易让人抓狂。我遇到过的一个典型案例是数据清洗技能。第一次用户给的表格列名是“姓名、年龄、城市”技能跑得很顺利第二次用户给的表格列名是“name、age、city”技能直接罢工了。原因很简单我的技能文档里写死了中文列名的处理逻辑没有加英文列名映射这一步。这类问题的根源在于技能设计时隐含了过强的格式假设。大模型很擅长从语义理解中“脑补”缺失信息但当它面对的输入结构跟文档描述存在偏差时它又很容易僵化地按文档执行。解决方向有两个。一是给技能加“前置适配器”在执行主逻辑之前先检测输入格式做格式归一化把“英文列名”映射成“标准中文列名”之类的步骤前置掉。二是给技能文档加“输入变形提示”明确列出哪些输入字段可能出现变体以及遇到变体时的处理策略。把这两件事做好技能执行的稳定性会大幅提升。另外还要强调一个容易忽略的点技能里一旦涉及时间、日期、金额等数据一定要写明时区和格式规范。不然Agent会在1,000和1000之间、在“3月5日”和“2026-03-05”之间反复横跳。5.3 技能库维护的“熵增”困境技能库是有生命周期的它在使用中会不断膨胀、不断变化。如果不做主动维护就会进入我所说的“熵增”状态技能越来越多互相重叠没人清理最后谁也说不清哪个技能是有效的、哪个是废弃的。我常用的维护策略是给每个技能打上生命周期状态active真正在用且效果稳定deprecated不再推荐使用但保留文档防止旧任务触发误伤archived已经彻底下线不再被索引只留档备查每次技能有更新时至少更新三个地方技能版本号、变更说明、适用场景示例。很多人只改主体逻辑忘了更新说明结果迭代几个月之后文档和实际行为完全是两套东西。这里有个很实用的检查技巧每季度做一次技能“体检”。把技能库里的所有技能从头到尾跑一遍测试用例看哪些通过、哪些失败、哪些执行时间明显变长。通过的继续留着失败的排查修复明显冗余的合并或下线。每一次体检做完技能库都会瘦身一圈但同时好用一大截。5.4 问题速查表症状根因方向快速排查路径技能完全不被触发技能路由未生效确认技能描述进入了模型上下文检查触发关键词与用户表达的距离技能触发错乱多个技能描述重叠逐一比对技能描述的when_to_use压缩重叠区域同样的输入两次结果不同执行链路依赖模型自由发挥过多把确定性的处理步骤下沉到代码脚本减少模型临场发挥空间遇到新格式数据就翻车缺少前置适配或格式归一化在技能里加入格式检测与转换步骤输出看起来合理但实际是编的边界条件未约束检查技能是否明确写了“不做什么”和“遇到缺失数据时的要求”技能执行太慢链路编排过大涉及过多工具检查是否可以在技能内提前终止分支减少不必要的中间步骤这张表不能覆盖所有情况但绝大多数我遇到过的技能故障都能归到这几类里。排查的思路其实有一个共同的内核不要指望Agent自己就什么都会技能库的本质是你把确定性交给流程、把不确定性交给模型让二者各得其所。6. 从单技能到技能生态的扩展路径6.1 技能目录的横向复制与垂直深耕当你的技能库已经稳定运行之后可以考虑做扩展。扩展有两条截然不同的路线横向复制和垂直深耕。横向复制是把同一个技能模板复制到不同的业务场景里。你做了一个“营销周报生成技能”那能不能快速复制出一套“研发周报生成技能”两者的底层逻辑都是“汇总一段时间内的关键信息按固定格式输出报告”差别在于数据源和信息维度。这种复制不是简单的CtrlC而是要抽取共同核心把差异化的部分做成配置项。垂直深耕则是在某个特定领域把技能做深做透。比如你在做“销售线索清洗”那么你可以沿着这条线继续往下扩展线索评分、行业分类、跟进计划生成、客户画像构建。这些子技能如果是孤立开发的效率很低但它们如果共享一套数据模型和术语体系就能形成强大的协同效应——上一层技能输出的结构化数据直接成为下一层技能的输入链条跑起来之后系统能处理的复杂度远超过任何单一技能。我的建议是把两条路线混合使用先在核心业务流里垂直深耕出几个旗舰技能再通过横向复制扩展覆盖面。不要一开始就全面铺开技能库过大而维护不足最终只会变成负担。6.2 技能与技能的编排从独立到协作单技能做得再强也只是点。真正能产生质变的是技能之间的编排与协作。举一个实际例子我在一个项目里同时部署了三个看起来风马牛不相及的技能——“纪要技能”、“需求拆解技能”、“周报生成技能”。最初它们各自独立跑。直到有一天我尝试把三个技能串起来会议纪要技能先产出结构化内容需求拆解技能从纪要里提取“待办事项”并拆解到具体负责人和时间节点周报生成技能再基于以上数据自动汇总成一份完整周报。这个串联一旦打通原先需要三个人、三套流程、半天时间才能完成的事情Agent在一个小时以内就能跑完。而且每一环的产出都有结构性中间不用人工做二次转写。编排的核心是统一数据接口。你不需要让所有技能共享同一个代码库但你一定要让它们共享同一种“数据语言”——字段命名的规范、日期的格式、实体的定义方式。这些底层契约如果不统一编排就会变成一场噩梦技能越多、链条越长出错概率越高。6.3 让技能库具备“成长性”最后我想聊一个稍微偏“软”但很重要的话题技能库的成长性。一个技能库交付上线之后最怕的就是变成“死库”。什么叫死库就是所有技能都停留在上线当天的状态没有更新、没有新增、没有淘汰。任何真实世界的业务都在变化技能库不做持续演化三个月后一定开始跟实际需求脱节。我在自己的项目里给技能库设计了一个“技能提案箱”。任何人在使用Agent的过程中如果发现“这个任务不该这么处理”、“缺一个动作能搞定的事”的情况都可以往提案箱里丢一个提案。提案不需要长篇大论只要写清楚任务是什么、现状是什么、期望的改进是什么。每个月我过一遍提案箱挑出出现频率最高的三个需求把它们转成技能开发任务。这个机制的背后逻辑是技能库不是你一次性设计出来的而是你用着用着“长出来”的。你隔离出来的每个流程、修正过的每个错误、沉淀下来的每份经验都值得被转化成技能。这才是agent-skills体系真正成熟的特征——它会变成一面反映你工作模式的镜子你有多会总结它就有多会用。我自己的体会是与其费尽心力去追求一个“全能Agent”不如老老实实把agent-skills这件事做扎实。每多沉淀一个技能你的Agent就多一点解决问题的能力每多一次迭代你的技能库就离“顺手”更近一步。这个方向需要耐心但回报是实打实的。