做Agent项目有一段时间了最让我头疼的其实不是模型能力不够而是同一个任务换个场景就要把Prompt重写一遍。比如让模型帮我抽取发票字段这周能用下周换个格式又得调半天。后来我认真研究了agent-skills这套思路才意识到问题出在哪我没有把Agent执行任务的经验固化下来每次都在让模型重新摸索。这篇文章就聊聊我对Agent技能体系的理解以及怎样从零构建一个真正能被复用的技能。这套东西解决的核心问题很直接让Agent不再靠一次性的Prompt碰运气而是像人一样拥有一本岗位操作手册。只要把任务拆解成结构化步骤、边界清晰的技能文件模型就能稳定地按流程执行而且技能可以积累、复用、迭代。不管你是刚接触智能体开发的新手还是在团队里负责Agent平台建设的技术同学这篇文章提供的设计思路、目录规范和避坑经验都能直接拿来用。1. 为什么我突然开始认真研究Agent的技能体系1.1 从一次每天都在重复造轮子的经历说起上个月我接了一个数据分析的需求需要让Agent每周自动汇总多份CSV报表提取关键指标并生成结论。第一次做的时候我在系统Prompt里写了一大段指令包括列名说明、指标计算规则、输出格式要求实测跑通效果还不错。结果第二周换了数据源列名变了、单位变了模型一下就懵了输出结果完全不可用。我又花了一个多小时去调试Prompt。后来我开始想一个问题如果我把这些任务执行的步骤、规则、示例整理成一份结构化的文档让Agent在需要的时候自己去查阅而不是把所有内容都塞进系统Prompt里效果会不会更稳定这就是agent-skills的核心思想——把任务经验封装成技能文件模型按需加载。这样既不会撑爆上下文窗口又能保证知识是结构化的、可维护的。1.2 Agent技能和Prompt、插件到底差在哪很多人第一次接触技能体系时会把它和传统Prompt工程混淆。我自己也踩过这个误区。举个直观的例子Prompt相当于你给一个实习生口头交代把这份报表处理一下说得再详细也是一次性的而技能相当于你递给他一份《报表处理作业指导书》里面写清楚了输入格式、处理步骤、异常情况怎么应对、最终输出长什么样。模型执行时按指导书操作而不是凭临场发挥。这里有个关键区别需要说透传统Prompt是把操作知识混在对话里模型需要在长文本中自行提取和回忆而技能体系把操作知识独立成文件通过元信息触发加载。从底层看技能减少了模型在无关内容上的注意力消耗也降低了知识被稀释的概率。我做了个对比表把几种常见方案放在一起看更清楚方案定位复用粒度上下文消耗维护成本与模型耦合度系统Prompt对话级指令任务级全部常驻改一次全量替换高Few-shot示例演示级引导任务级每次携带需持续扩充中Function Calling工具接入层函数级按调用携带需写JSON Schema中插件/Plugin平台绑定扩展应用级按插槽加载依赖宿主框架低Agent技能知识封装层任务级场景级按需加载独立文件迭代低从表格能看出来技能的独特价值在按需加载和独立迭代。我在实际项目中最大的体感是技能让Agent的行为变得可预期了。以前同一个任务跑十次可能有两种不同的处理逻辑现在技能文件里写清楚了先做什么、再做什么、遇到什么情况怎么办模型的选择空间被有效约束输出稳定性明显提升。2. 技能设计的核心原理与目录规范2.1 SKILL.md一份给模型看的操作手册Agent技能体系里最核心的载体是一个叫SKILL.md的文件。这个文件的特殊之处在于它服务的读者不是人类而是模型本身。也就是说编写这份文档的思路和写给人看的README完全不同——你是在为一个聪明但缺乏任务背景的模型写实操指南。我刚开始写SKILL.md时犯过一个错误用写技术文档的习惯去写大段背景介绍、原理说明、设计动机洋洋洒洒几千字。结果模型执行任务时抓不住重点。后来我调整了策略SKILL.md要解决的是当模型面临这个任务时第一步做什么、每一步做到什么标准而不是这个任务的背景知识是什么。合理的SKILL.md应该包含这几块内容技能名称与一句话描述、生效条件与适用边界、执行前的前置检查、逐步操作指引、输出格式与质量标准、常见误区提示。其中执行前的前置检查特别容易被忽略但恰恰是稳定性的关键。比如PDF发票抽取这个技能执行前必须检查文件是否可解析、是否为扫描件这能帮模型避免在错误的输入上硬做。2.2 前置元信息让模型在0.1秒内做出调用决策每次任务到来时模型要决定要不要调用这个技能。这个决策过程非常快几乎是基于直觉判断。所以技能文件顶部的前置元信息frontmatter设计得是否清晰直接决定技能能不能被正确触发。我看过一些技能设计规范把元信息分成三个层级一句话描述、多句话展开、新增示例。一句话描述要精准概括技能能做什么便于模型快速匹配多句话展开是让模型在模糊场景下做进一步判断新增示例则是通过正反例帮助模型理解触发边界。这套设计的本质是给模型一个决策漏斗——先用低成本信息过滤再逐步深入。举一个我在实践中的写法示例--- name: pdf-invoice-extractor description: 从PDF发票中抽取关键字段并输出结构化JSON。支持增值税电子普通发票、专用发票的常见格式。不适用于手写小票、非中文票据。 proficiency: - 一句话能从PDF发票提取发票号码、金额、税额、购买方、销售方等字段。 - 详细说明适用于清晰可解析的电子发票PDF若文件为加密或扫描件应先执行OCR预处理。输出为固定JSON结构金额单位为元保留两位小数。 - 新增示例当用户上传一个PDF文件且内容含发票关键词时优先调用本技能。当文件无法解析文本层时不直接返回失败而是引导用户提供扫描件并转OCR流程。 ---前面说过这段元信息中新增示例非常关键。我发现模型在调用决策时最依赖的不是抽象描述而是具体的触发样例。你给它一两个正反例它判断的准确率会明显上升。这和我调试Prompt时的经验一致——模型的理解往往建立在实例之上而不是抽象规则之上。2.3 技能启动器与调用时机有人会问技能文件放在那里模型怎么知道现在该用这个技能了这就涉及技能启动器skill launcher的机制。启动器本质上一段被注入到模型上下文里的技能清单——当任务与某个技能匹配时模型会打开对应的SKILL.md按里面的步骤执行。我在搭建时采用的方式是在系统Prompt中维护一个轻量级的技能索引只保留每个技能的name和一句话description当检测到用户请求与技能相关时再动态加载完整的SKILL.md到上下文。这样可以避免把所有技能全文都塞进系统Prompt节省大量token。要特别提醒的是技能索引的描述不能太长。假设你有二十个技能每个描述两三行字光索引可能就占掉几千token这个开销没必要。我把索引描述控制在30字以内只要能让模型完成触发决策剩下的详细内容交给SKILL.md正文来解决。3. 手把手构建一个可复用的Agent技能3.1 选型为什么我选择了这个案例理论讲再多不如直接动手做一个。我选择PDF发票信息抽取作为示例是因为这个任务有三个典型特征边界清晰、输出结构固定、并且有很多隐藏的异常情况。这三个特征恰好能把技能设计的各个要点都覆盖到。先说边界清晰——发票格式相对统一字段名称基本固定模型不需要在做什么上产生歧义。再说输出结构固定——我们要的最终结果是一份JSON字段、类型、精度都是确定的这方便验证技能执行是否正确。最后是异常情况丰富——扫描件、加密文件、表格变形、字段缺失这些都能检验技能文档中异常处理部分写得是否完备。基于这三点我确定了一个技能的设计目标当用户上传PDF文件模型能自动识别是否为发票抽取指定字段以固定JSON格式返回并且在遇到无法处理的输入时给出明确的路由建议而不是硬生成错误结果。3.2 搭建技能目录结构与配置一个干净的技能目录结构决定了技能在扩展时的下限。我采用的是以技能名称为根目录、按用途分子目录的方式pdf-invoice-extractor/ ├── SKILL.md # 主技能文档 ├── assets/ # 静态资源如字段映射表、样例模板 │ └── fields-map.json # 发票字段与输出字段的映射配置 ├── scripts/ # 可执行脚本如PDF解析工具 │ └── parse_pdf.py # 基于pdfplumber的文本层抽取脚本 └── examples/ # 示例输入输出 ├── sample-output.json └── sample-input.pdf这个结构的设计逻辑是SKILL.md负责告诉模型怎么做scripts负责替模型做具体的事情examples负责给模型提供参考比对三者解耦。我在实践中的体会是不要把解析逻辑写死在SKILL.md里而是封装成脚本让模型通过执行命令来调用。这样当解析库升级时只需要改scripts目录下的脚本不需要改动技能文档。3.3 编写SKILL.md正文与示例资源在SKILL.md正文部分我按执行前检查、分步操作、输出规范、异常处理四块来写。下面是我的实践模板你可以直接参考# PDF发票信息抽取技能 ## 执行前检查 - 确认输入文件为PDF格式文件大小不超过20MB。 - 确认PDF包含文本层。使用 python scripts/parse_pdf.py --check-only --file input 检测。 - 若检测结果为扫描件输出提示并要求用户先进行OCR处理。 ## 分步操作 1. 解析PDF文本层定位发票号码开票日期购买方信息销售方信息价税合计等关键词位置。 2. 根据关键词上下文提取对应值。注意金额字段以¥符号出现保留两位小数。 3. 若同一字段多次出现以价税合计区块为准避免取到优惠前金额。 4. 将提取结果映射为输出JSON结构字段命名遵循 fields-map.json 中的定义。 ## 输出格式 严格按照格式输出不要额外添加字段 { invoice_code: string, 发票代码, invoice_number: string, 发票号码, issue_date: string, YYYY-MM-DD, buyer_name: string, seller_name: string, amount_total: number, 价税合计金额, amount_tax: number, 税额 } ## 异常处理 - 若PDF文本层解析失败输出{error: pdf_parse_failed, message: 文件可能为扫描件请先执行OCR}。 - 若关键字段缺失将缺失字段置为null并在 warnings 数组中列出缺失项不要猜测默认值。 - 若金额转换时出现多币种符号以CNY为准其他币种在warnings中提示。这里有个细节值得展开说为什么步骤描述要写成定位关键词→提取上下文→映射字段而不是直接给一句提取发票字段因为模型在输出时往往会脑补它认为合理的值尤其是金额这种数字。只有给了明确的定位策略它才会真正去文本里找而不是猜。我在实际测试中也验证了这一点。在没写关键词定位策略之前模型偶尔会把小写合计金额当成价税合计写了以价税合计区块为准后这种错误基本消失。这不是模型变聪明了而是技能文档把正确路径写得足够明确。3.4 测试与迭代技能写完后最忌讳直接上线。我有一套自己的测试流程分四步走第一步是文档独立测试。把SKILL.md和示例资源丢给一个没有任何业务提示的模型只靠技能文档执行任务看它的输出是否符合预期。这一步检验的是文档自足性——如果文档写得不清楚模型需要借助外部知识才能完成任务那这个技能就是不合格的。第二步是边界测试。准备一批特殊输入扫描件、多页PDF、带盖章遮挡的发票、字段缺失的发票、金额为0的红字发票。每个用例都跑一遍看技能里的异常处理是否真的生效。第三步是回归测试。同一个技能文件隔一周再测同样的用例确认输出保持稳定。这一步防止技能文档里的描述被模型过度理解或习惯性忽略。第四步是多模型兼容测试。我用不同厂商的模型跑同一个技能观察输出差异。这一步不是为了追求完全一致而是为了发现文档中歧义过大的表述尽量用最通用的语言消除歧义。迭代策略上我坚持每次只改一处。比如这次修改了金额提取的定位规则那就只测和金额相关的用例不要同时调整关键词列表和输出格式。否则出了问题你根本不知道是哪处改动引起的。4. 常见问题与排查技巧实录4.1 技能不生效的排查链路我在实际使用中遇到频率最高的一个问题技能文件放好了但任务来时模型完全不调用。遇到这种情况我建议按下面的顺序排查不要上来就怀疑框架问题。先检查元信息里的description是否覆盖了用户的表达方式。比如用户说的是帮我看看这张发票而技能描述写的是抽取PDF发票字段模型可能觉得看看不等于抽取就不触发。解决方法是把用户在真实场景里的各种说法都收进proficiency里的示例部分。再检查模型上下文里是否真的加载了技能索引。很多框架默认只加载当前会话相关的技能如果你把技能放在全局目录但没配置自动加载模型根本不知道它的存在。我犯过这个低级错误排查了两个小时才发现是索引没生效。还要检查技能文件格式是否被正确解析。YAML前置元信息里的冒号、引号、缩进一点都不能错。有一次我在description里写了个英文冒号结果解析器把整个元信息都读错了模型完全没看到技能描述。4.2 描述冲突与技能打架当技能数量多起来以后技能打架问题会非常突出。我建了十来个技能时发现两个技能的description都包含发票关键词模型经常调错。解决这个问题的核心手段是在元信息里明确排除项。比如发票信息抽取技能里写明不适用于行程单、收据、合同而合同关键条款提取技能里写明不适用于发票、订单。另外触发优先级也需要设计。我采用的是精准优先、宽泛兜底的策略用户明确表达抽取发票字段时触发精确技能用户只说处理一下这个文件时触发兜底技能由兜底技能内部再做判断。这个方法能大幅减少错误调用。4.3 上下文膨胀问题有些人把技能设计成加载了就全程不卸载结果一个复杂任务下来上下文里堆了三四个技能的全部内容不仅浪费token还干扰模型注意力。我的做法是执行完后主动清理当技能完成核心输出后在Prompt中注入一个技能已完成标记要求模型不再引用技能中的操作步骤。框架层面也可以在任务结束后重置加载状态。对长任务可以考虑把技能拆成前置检查技能和字段提取技能按阶段加载避免所有内容同时驻留。上下文膨胀对模型的影响不是线性的而是到了某个阈值后准确率会显著下降。我实测下来当上下文里技能文档占比超过60%时模型开始忽略技能里的细节。所以控制加载量不只是省token的问题它直接影响任务质量。4.4 常见问题速查表我把这段时间遇到的高频问题和对应解法整理成了一张表方便你对照排查现象可能原因排查方向解决方案模型完全不调用技能description与用户表达不匹配检查触发样例补充用户常见说法的示例技能调用了但输出格式错误SKILL.md中输出规范描述模糊检查输出格式段落给出完整JSON示例明确字段类型同一个任务两次执行结果不同技能步骤描述不够确定检查分步操作用如果/那么消除选择空间技能间互相抢任务description有重叠检查触发边界补充排除项设计优先级技能加载后上下文暴涨技能全文被常驻检查加载策略执行完卸载或拆分技能阶段模型忽略技能中的警告警告措辞不强烈检查异常处理使用必须禁止等强约束词YAML解析失败引号或缩进错误检查frontmatter用编辑器格式化校验这张表里的最后一条值得多说两句。模型对可以和必须的敏感度完全不同。我在技能文档里写明输出必须为合法JSON不要添加任何解释性文字模型遵守的概率远高于输出应该为JSON。5. 工具链选型与生态扩展5.1 主流技能框架怎么选目前市面上做Agent技能加载的框架大体上分三类独立技能规范生态各类Skills市场、通用Agent框架自带的技能机制、以及介于两者之间的开放工具协议型方案。它们的核心逻辑是一样的——提供一种元数据行为描述的封装格式但在加载方式、生态丰富度、语言绑定上各有侧重。选型时我的建议不是追新而是看三个问题团队最常用的模型能否直接识别这套技能格式技能能否独立于会话存储和版本管理技能库能否吸收现有工具链而不需要推倒重来如果你和我一样主力模型经常切换那就选前文提到的SKILL.md 脚本解耦方案。这个方案的兼容性最好无论底层模型是哪个厂商的技能文件本身都是纯文本加可执行脚本不绑定运行时。即使你后面换框架技能资产也不会报废这是它最值的优势。5.2 版本管理、复用与团队协作技能文件本质上是一份代码资产就应该用代码的方式管理。我给每个技能建了独立的git仓库或者至少要单独建目录绝不能把技能文件散落在各处。每次修改都要写清楚变更日志我一般按新增触发示例、更新异常处理、修复字段映射三个维度记录。团队协作时我还会为每个技能设置一个技能负责人。负责人负责评审外部提交的技能修改保证SKILL.md的质量标准一致。有人会觉得这太重了但我的实际体验是技能文档的风格一旦不统一不同人写的技能之间会出现严重的表述差异模型的表现也跟着忽高忽低。统一评审是性价比最高的维护方式。关于技能复用还有一个实用技巧把常用的原子操作拆成微技能。比如PDF文本层抽取JSONSchema校验CSV列名标准化这类底层操作单独做成技能后被上层技能调用。我在发票抽取技能里就用到了PDF文本层抽取这个微技能这样如果哪天要换成更快的解析库只需要改微技能所有依赖它的技能自动受益。写在最后的一点个人体会做agent-skills这段时间我最深的一个感受是技能体系的价值不在于帮你写好一个Prompt而在于把Agent的能力沉淀成可积累的资产。以前每接到一个新任务我都从头开始调Prompt不同项目之间完全没法复用现在积累了十几个技能新来的场景只要能在已有技能基础上做组合开发效率提升了一个量级。还有一个技巧想分享给你别急着把技能设计得很庞大从一个最小可用版本开始跑通后再逐步补充异常分支。我第一个版本的发票抽取技能只有简单的字段提取步骤经过三轮迭代才加上扫描件识别、金额去重、字段缺失警告这些细节。慢慢打磨出来的技能比一次性写完的更经得起真实场景考验。如果你也在做Agent相关的项目建议从手头最重复的那个任务开始尝试把它抽成一个技能你会明显感受到一次封装、处处复用的快乐。