1. 为什么Agent开发正在被上下文膨胀拖垮1.1 一个Agent项目里prompt到底占了多少空间做Agent开发的都知道模型推理能力再强也架不住输入里塞的东西越来越多。我最初写Agent时用的是最朴素的方法把每一个工具的函数说明、参数示例、边界条件全部拼进system prompt里。一开始只有两三个工具还好等工具数量到了十几个prompt基础体积就已经四五千个token。这种做法的代价是隐性的。模型窗口大小固定system prompt占了越多的空间留给用户真实输入、历史对话和中间推理的空间就越少。更麻烦的是一旦上下文接近窗口上限长文本记忆就会挤掉前面或者中间的内容产生一种很诡异的现象Agent在对话的前半段还正常到后半段突然失忆开始重复、请求重述甚至干脆报错。排查到最后发现根本不是模型出了问题而是Prompt工程把窗口塞满把模型逼到死角。我自己测过一组对比同样一个周报汇总Agent只包含3个工具时单轮平均耗时正常塞到12个工具时同样的请求平均延迟上升了将近一倍在很多样本上的摘要质量也明显下降。这类问题在社区里被叫做上下文膨胀——它不是某一个工具写错了而是整体设计没有考虑上下文的经济学。1.2 更隐蔽的成本跨平台重复建设上下文膨胀只是第一个坑第二个坑是跨平台。同一个能力在不同平台上几乎都要重写。早期我在某平台把发送邮件工具用函数调用方式接好跑到另一个平台上发现平台对工具描述格式的解析逻辑完全不同有的用OpenAPI schema有的要纯文本描述有的要求固定前缀。这导致同一个业务逻辑被翻译成好几套方言。这种重复不只是改格式的问题。每换一个平台工具描述里的措辞、示例、边界条件都需要重新调试。模型的tool calling行为对描述文本极其敏感哪怕只是把发送邮件改成执行邮件投递某些模型在特定场景下的调用命中率都会出现波动。所以在实际项目里跨平台迁移一个Agent真正花时间的不是代码而是把每个工具的提示工程在目标平台上重新调一遍。我身边有做Agent基础组件的朋友后来普遍达成一个共识工具本身不是稀缺资源可复用的、带有良好描述与验证示例的技能才是。而技能一旦被定义为一种开放标准就能同时解决两个问题——上下文膨胀和跨平台重复建设。这也是我看到Agent Skills开放标准时觉得思路对路的原因。1.3 三个数字背后的信号标题里的三个数字值得逐个拆着看。85000个技能说明这个生态里已经把大量高频任务沉淀成了标准模块。天气查询、日程管理、数据分析、报告生成、HTTP请求这些常用能力几乎都能直接找到现成的技能定义。对普通开发者来说这意味着Agent开发正在从自己写工具变成在仓库里找技能。27家平台说明基于统一标准的技能文件已经能跨平台运行不再是一套封闭的孤岛协议。90%上下文节省这不是一个理论值而是把技能定义与实现分离之后得到的结构性红利。省下来的上下文可以留给用户历史、长文档和推理链条。这三个数字指向同一个趋势Agent开发正在从手写prompt走向装配技能。后面我会从标准本身的结构、实际写一个技能的过程、上下文节省的实现机制以及跨平台兼容的真实经验逐一展开。2. Agent Skills开放标准的核心设计一个技能由什么组成2.1 该标准将一个技能组织为一个自包含目录我第一次接触到Agent Skills的实践形态时最大的感受是它把技能变成了一个自包含的文件目录。一个标准技能通常长这样pdf-report-skill/ ├── SKILL.md ├── SKILL.yaml ├── reference/ │ └── render.py └── assets/ ├── input-example.json └── output-example.pdf这种结构有几个很明显的好处。第一SKILL.md是人类和模型共享的说明书里面描述了技能的使用场景、输入输出、注意事项和示例第二SKILL.yaml是机器可读的元数据负责给平台做索引、检索和权限控制第三reference目录放的是真实实现代码运行时按需加载第四assets目录放示例数据用于给模型做few-shot参考。关键在于加载进上下文的只有前两个文件实现代码和示例文件不会进入模型上下文。平台通过元数据建立技能索引模型在运行阶段只需要看到标准化的描述和输入输出schema真正的业务逻辑是在沙箱里完整执行的。这个设计直接决定了后面要讲的90%上下文节省率是怎么做到的。2.2 元数据字段的筛选逻辑哪些字段真正影响可用性写SKILL.yaml时字段并不是越多越好。早期社区里经常出现五六百行元数据的技能文件后来大家发现真正影响可用性的核心字段其实就几个。name是全局唯一技能ID通常采用命名空间加技能名的形式比如acme/pdf-report。description是最关键的一个字段因为模型是根据这段文本来决定什么时候该调用这个技能的。description必须说清楚在什么情况下、为了完成什么目标、使用这个技能而不是复述功能清单。version采用语义化版本号平台升级时靠它判断兼容性。license和author是分发时的基础信息方便做权益归属。allowed-tools也非常重要它声明了技能运行时允许调用的外部工具白名单平台据此做沙箱隔离。从标准演进的角度看元数据字段的取舍原则是少而必要。每新增一个字段所有平台、所有技能的迁移成本都会上升。所以标准对字段的态度是可选的尽量可选带默认值的绝不强制。2.3 description的写作质量决定了模型能否正确选中技能在Agent Skills标准里description的写作优先级比我预想的高很多。因为模型选择技能的过程本质上是把一个自然语言任务映射到一段技能描述文本上。模型先对用户请求做语义理解再在各技能description之间做相似度匹配最后才是在被选中技能内部做参数对齐。我见过不少质量不高的描述写法比如只是堆砌关键词邮件、发送、SMTP、附件、群发。这种描述在技能少的时候也许能碰对技能一多就会频繁误选。更合理的做法是写成场景化的触发条件当用户要求发送邮件、回复邮件、或创建带附件的邮件草稿时使用本技能。输入为收件人、主题、正文、附件路径输出为发送状态。一个直观类比技能描述是给模型看的使用说明书里的触发条件页。用户说帮我把合同发给王总模型需要在几百个技能里快速排除掉邮件模板生成合同审批企业通讯录等相近技能精准命中邮件发送。此外多数质量较高的技能还自带1-2个输入输出示例。示例能让模型用模仿的方式填充参数经常能避免参数缺失的尴尬。比如天气查询技能中给出{city: 上海, days: 3}的输入示例模型遇到上海未来三天天气时只需做极小的参数映射就能完成任务而且错误率明显更低。3. 手写并发布一个跨平台Skill以PDF报告生成为例3.1 确定技能边界什么应该进技能什么不应该在动手写技能之前先要明确边界。不是所有能力都应该做成Skill。Agent Skills适合封装的是输入输出稳定的原子能力不适合封装业务编排流程。以PDF报告生成为例合理的技能边界是接收一个JSON数据对象输出一份PDF文件。至于这份数据从哪里来、报告里要放哪些指标、要不要做图表这些是上层Agent的编排逻辑不该塞进技能里。我把这个技能定义后才体会到Agent层负责什么时候调用、传什么参数、怎么消化结果Skill层负责把数据变成成果物。职责边界划分得越清晰技能的复用性就越高。比如同样的PDF生成技能既可以给周报Agent用也可以给销售复盘Agent用区别只在于传入的数据结构不同。3.2 逐个文件写出一个可运行的技能下面是我实际用过的PDF报告生成技能的四个核心文件去掉业务敏感信息后的结构。首先是SKILL.yamlname: acme/pdf-report description: 当用户需要把结构化数据生成PDF报告、导出业绩汇总或创建可视化摘要时使用。 输入为report_dataJSON对象与template可选输出为PDF文件路径。 version: 1.2.0 license: MIT allowed-tools: - files.write - files.read然后是SKILL.md它比yaml更强调自然语言描述用于给模型补充使用规则和注意事项# PDF报告生成技能 将结构化数据渲染为带标题、表格和简单图表的PDF文件。 ## 使用场景 - 用户上传数据后要求生成报告 - 用户要求把周报数据导出为PDF - 用户要求生成销售汇总图表 ## 输入格式 json { title: 报告标题, sections: [ {heading: 章节名, body: 文本内容, chart: line} ], data: {series_name: [A, B], values: [1, 2]} }输出生成文件的绝对路径。如失败返回错误信息并保持当前目录不变。注意数字要按千位分隔符显示图表数据为空时报错而不是生成空白图。接下来是reference/render.py这是平台运行时的实际实现。因为标准只规定文件结构不限制实现语言所以这个文件可以用Python、TypeScript或任何平台支持的运行时编写 python import json import sys from pathlib import Path def render_to_pdf(input_data: dict) - str: # 简化实现使用报告引擎将数据渲染为PDF # 实际项目中会调用底层的设计模板与字体资源 report_path Path.cwd() / output / f{input_data[title]}.pdf # 省略具体渲染逻辑…… return str(report_path) if __name__ __main__: data json.loads(sys.stdin.read()) print(render_to_pdf(data))最后是assets/input-example.json这个文件会给模型做参考。比如{ title: Q3销售复盘, sections: [ {heading: 整体趋势, body: 整体增长 12%, chart: line} ], data: {series_name: [7月, 8月, 9月], values: [10, 12, 13]} }其实真正手写这个技能所花的时间并不长。要特别留意的反而是描述文本的措辞比如最后一行关于图表数据为空时报错而不是生成空白图的规则这属于典型的边界条件描述能避免模型用错误示例学习出显式错误行为。3.3 为什么同一个目录能在27家平台运行一个常见疑问是这里面的代码是Python的如果目标平台只支持Node.js怎么办。Agent Skills标准在这里的边界划得很清楚标准规定的是技能定义文件的格式与语义不规定技能实现的具体语言或运行方式。平台侧的做法通常有两种。一些平台直接内置多语言运行时能运行Python/JS等主流实现另一些平台则要求技能把reference执行包装成本地服务或通过语言无关的RPC协议调用。技能目录本身保持原样平台负责在运行时上做适配。这就和浏览器兼容标准一个道理。HTML/CSS标准定的是文档语义渲染引擎由各家自己实现。一个网页能在不同浏览器里打开不是因为所有浏览器代码相同而是因为语义一致。Agent Skills同样如此只要SKILL.md与SKILL.yaml符合标准不同平台就可以用自己的运行时来执行同一个技能这也是27家平台、85,000个技能能够互通的基础。3.4 发布到仓库的规范与版本治理发布技能时有几个细节容易忽略。首先是文件名大小写和目录结构必须严格符合规范很多平台在索引时会直接按约定路径查找SKILL.md与SKILL.yaml大小写不对就会静默跳过。其次是schema校验可以在发布前用官方校验器跑一遍避免字段类型错误。版本治理方面标准推荐语义化版本。主版本号变更意味着行为不兼容副版本号表示向后兼容的功能新增补丁版本则是错误修复。平台在升级技能时也会参考版本号做灰度。技能进入仓库后通常还会做一轮质量分级。质量判定主要看三方面元数据完整度、实现代码的安全审计结果、以及示例数据的多样性。等级高的技能会被优先推荐质量低的则在搜索结果中靠后。这个分层的存在让85,000个技能不只是一堆文件的堆砌而是一个有治理逻辑的生态。4. 90%上下文节省的实现机制从文件到token的数学账4.1 基线方案 vs 技能方案要理解90%这个数字先算一笔账。假设一个Agent需要集成PDF报告生成能力。基线做法是在system prompt里写清楚生成规则、格式要求、字段说明、各种示例加起来往往要1200到1500个token。如果Agent要集成20个类似能力这个数字会线性增长到2到3万个token直接逼近中等模型的上下文预算。技能方案的做法不同。Agent启动时只是挂载一个技能索引比如技能列表与一行场景描述当用户请求触发某个技能时平台再按需加载这一个技能的定义通常是description加schema加起来只有200到300token。也就是说同样20个能力基线方案要常驻2万token技能方案只需要常驻一个索引比如几十个token的概览实际调用时再多加载命中技能的几百个token。一个Page的Agent如果在一轮任务里只实际用到两三个技能上下文占用从几万token降到几百token是完全正常的90%的节省就是这么来的。4.2 三个关键机制按需加载、索引路由、描述缓存90%这个结果不是靠单一技巧达成的而是由几个机制叠加出来的。按需加载是最核心的。技能定义文件不被当作系统初始指令而是作为一个可检索的外部资源库。Agent在处理任务时先把用户意图和索引里的场景描述做一次匹配只把命中的技能定义注入上下文。没有命中就继续在资源库里找而不是一次性把所有技能全塞进去。索引路由是引擎侧的能力。平台维护一份技能元数据索引包括name、description、标签、依赖关系等路由时用检索或语义匹配的方式挑选候选技能。这个过程通常在几十毫秒内完成用户的体感几乎无延迟。描述缓存是节省成本的小技巧。对热门的技能平台可以把它的描述和schema预编译成固定的token序列缓存起来命中时直接拼接省去重复的编码开销。更进一步平台还能缓存技能生效后生成的系统指令补丁让Agent在多次会话中复用同一个补丁。4.3 什么样的场景达不到90%不是所有场景都能拿到90%的节省。如果一个Agent的任务需要同时调用大量技能比如一次提问涉及20个工具的复杂工作流那所触及技能的定义总体积可能只会比基线方案小一点点。还有一种情况是任务描述本身非常依赖技能内嵌的长文本规则技能定义本身就很大比如某些技能里附带了20个JSON Schema示例加载体积并不小。但即便如此技能方案的上限也比基线方案低一个量级。因为技能是按需撕裂的不存在一个Agent常驻几百个技能描述的场景。生态里85,000个技能共享的是一套索引机制而不是把85,000份文件全部读进内存。4.4 节省下来的上下文到底用在了哪里有一点值得想清楚节省上下文本身不是目的目的是把有限的窗口预算花在更值钱的地方。同样的上下文开销在基线方案里被用来反复描述PDF文件的格式规则在技能方案里则被用来承载用户上传的数据、更长的历史对话、以及模型在复杂推理过程中的中间步骤。很多Agent在长对话中出现的失忆现象根源都是上下文预算紧张。技能方案相当于把环境描述压到最小把任务空间扩到最大模型看到的信息从一堆工具说明一小段用户请求变成完整用户请求正在处理的实时数据这对最终质量的影响非常直接。这类提升很难用一个精确指标量化但从我自己的对比测试来看在同窗口模型上技能方案的Agent在长对话稳定性、多步工具调用准确率上都要优于基线方案。5. 生态治理27家平台如何在一个标准下共存5.1 兼容性三层的真实分工初看27家平台这个数字可能会误以为大家都用同一套代码实现。实际上Agent Skills生态的兼容性分成三层。第一层是文件格式与字段语义这是标准本身的部分所有平台都必须遵守。第二层是运行时执行引擎各平台差异最大的一层负责把技能里的reference代码运行在自家沙箱里不同平台的执行方式、资源限制、安全策略都完全不同。第三层是分发渠道与技能仓库平台可以维护自己的索引也可以聚合第三方仓库。三层各自独立演进好处很明显标准层可以保持稳定运行时层可以发挥各平台的优势分发层可以做垂直推荐。一个技能从一个平台迁移到另一个平台不需要改动SKILL.md与SKILL.yaml最多需要确认目标平台的运行时是否支持该reference语言。5.2 技能质量的雷池安全、校验与权限控制27家平台愿意共用一个标准必然有一套大家都信赖的质量底线。安全是最基础的一条。平台在加载技能时会做静态检查确认reference代码是否符合沙箱规则比如有没有访问网络、读取系统文件、执行任意命令等敏感操作。SKILL.yaml里的allowed-tools字段就是对这些操作的显式声明平台会把它和代码实际行为做对照校验不一致的直接拒绝。元数据校验也有一套严格流程。description必须有明确的触发场景schema必须合法可用示例必须能通过读取校验。新技能入库时如果不符合这些规则会被打回。权限控制上标准鼓励平台一定要让用户知道这个技能会做什么。部分平台在技能首次运行时会在界面展示将读取你的文件目录并生成PDF文件之类的权限说明由用户确认后才放行。这也是生态规模能持续增长而没有陷入信任危机的原因。5.3 标准演进与向后兼容的几条原则标准只要还在演进就必须平衡新增功能和存量生态的关系。实际运营中比较有效的几条原则是新增字段必须提供默认值不允许破坏已有技能的正常加载不修改已有字段的既有语义只做增量说明重大不兼容变更必须走废弃期流程旧版本继续可用一段时间。这意味着一个两年前发布的技能到今天依然能被新平台正常加载只是新平台能额外读取新增的可选字段。这种向后的克制是85,000个技能能够持续积累的前提。如果标准隔几个月就大改一次字段语义整个技能库早就变成维护地狱了。现实中标准本身的迭代速度比社区预想的慢得多。核心原因是改动成本极高27家平台都需要同步测试任何草率的字段变更都会引发连锁问题。这也是为什么标准的维护者们倾向于少加字段、少动语义、多出指南。6. 实际落地时容易翻车的几个细节6.1 技能一多模型反而选择困难技能数量上来以后一个新问题出现了当平台一次性把几十个候选技能的description展示给模型时模型在选技能上会出现摇摆。我在一个内部项目里挂载了30多个技能结果某些请求会让模型反复横跳前后两次调用选了不同的技能导致执行结果不稳定。解决办法是给技能加分组或标签维度。平台先把高维分组信息给模型看比如数据处理类沟通协作类文件操作类模型先选组再在组内做细粒度选择思路类似给一个超大目录加导航页。另一种做法是在技能的description里把高频场景写得更具体降低歧义。另外要提醒的是技能索引本身也别做成精确的全量列表。在这个生态里一个Agent真正高频使用的技能往往在10个以内超出这个数量后优先考虑把多个技能合并成一个组合技能减少模型的选择面。6.2 示例数据的毒丸效应assets里的示例数据有时候会反噬。如果示例写得过于单一比如PDF技能里只给了一份纯文本报告的例子模型遇到需要图表、表格、分页等复杂场景时会倾向于模仿示例产出简化版的报告。我踩过一次坑某个技能里示例数据包含了固定的季度数字Q3、销售额、增长率结果这个Agent在用户输入生成一份最新周报时把示例里的旧数据当成了真实数据生成了和示例几乎一样的报告。排查后才发现是示例数据里没有标注这是示例不要作为业务数据来源。所以在示例文件里要明确加注释说明其仅用于格式参考同时尽量多放几组不同形态的样例覆盖稀疏输入、富数据输入、异常场景。示例的质量直接影响模型的few-shot行为值得多花时间打磨。6.3 跨语言实现与运行时差异的适配reference实现语言在标准上没有限制但实际落地时不同平台的运行时能力不一样。有些平台只支持Python有些只支持JavaScript还有一些支持多语言。一个技能要让27家平台都能跑通常有几种取舍方式。第一种是自包含纯函数实现不依赖系统外部服务尽量用原生标准库写第二种是把重逻辑封装成独立服务reference里只做HTTP等协议转发第三种是维护多语言实现并在SKILL.yaml里用runtime字段声明支持的目标平台。我个人的建议是优先保一个最小实现核心调用链尽量短、依赖尽量少、错误处理尽量明确。这样一个技能在绝大多数运行时里都能跑通而不用为每个平台维护一套代码。6.4 监控是技能生态的最后一公里技能发布之后不是完事大吉。每次运行过程中的命中率、参数完整度、执行失败率、token消耗都是重要指标。用数据驱动下一个技能的优化方向比靠感觉迭代可靠得多。我在实践里发现一些技能在单一平台命中率很高换一个平台后命中率会掉十几个百分点。这类差异通常来自平台对description的分词或语义检索算法不同。解决方案是建一套平台兼容性测试集每次改动技能描述后做全平台回归至少能保证不会出现迁移后找不到技能的尴尬。监控的另外一头是用户反馈。技能执行出错时标准允许技能返回结构化错误信息平台再把这些信息和调用链路一起记录下来。这些数据既能帮助技能作者定位问题也能让平台看清哪些技能在哪些场景下表现不佳。从我自己的工程经验来讲Agent Skills这类开放标准最大的价值不是它秀出的那几个数字而是把Agent开发变成了可复用、可治理、可观测的工程过程。如果你也在做Agent相关的东西建议先别纠结要不要上大规模技能库而是挑两三个常用能力按标准写成技能跑一个端到端的跨平台流程。这套标准到底顺不顺手跑完一遍你心里就有数了。