我在大模型应用这块混了几年最近半年最明显的一个感受是圈子已经从“怎么让模型答得对”全面转向了“怎么让模型干得成事”。而“干成事”的关键恰恰不在模型本身的参数规模而在它能不能稳定地调用外部工具。2025年热度最高的词之一就是“Skill调用机制”——无论是Codex团队开源的那套架构设计还是Spring AI 2.0的Skill体系还是GIS空间分析Skill、AI短剧Skill、语言学习Skill本质上大家都在做同一件事把模型与工具之间的协作方式工程化、产品化。这篇我结合自己落地Skill系统、给项目组搭内部技能仓库、以及在各种Agent框架里写Skill配置的经验把Skill调用机制的架构设计、工程实践和常见坑一次说清楚。无论你是刚接触Agent开发的新手还是已经在自研Agent平台的工程师希望这篇文章能帮你少走点弯路。1. Skill到底是什么先把这个概念的边界划清楚1.1 从Function Calling说起再看Skill的区别要理解Skill绕不开Function Calling函数调用。2023年ChatGPT把Function Calling带火之后大家的普遍做法是把你系统里的API、数据库查询、计算函数都定义成一个个function把参数schema丢给大模型模型在生成回复时决定要不要调用某个function、传什么参数然后你的程序去执行并返回结果。这套机制很直接但它有一个天生的痛点function的粒度太细了。比如你可以定义一个get_weather(city)但要完成“帮我安排周末杭州两日游”这个任务你需要十几个function配合还要处理上下文传递、中间状态、异常恢复……全是胶水代码。而且不同任务之间大量处理逻辑是重复的。Skill的概念从2024年底开始逐渐成型到2025年彻底爆发。它的核心思想是把某个任务域内所需要的提示词、工作流、脚本、工具定义、参数模板打包成一个“可复用的技能单元”。模型面对一个复杂任务时不再需要从零拼接一堆function而是先“检索”到对应Skill然后按照Skill里写好的流程去执行。我用一句话总结两者的区别Function Calling是给模型提供单次动作的“零件”Skill是给模型提供完成一整类任务的“作业指导书工具箱”。1.2 Skill的标准构成与通用目录结构虽然不同平台的Skill格式有差异但成熟Skill的骨架是大同小异的。我参考过OpenAI的GPTs、Anthropic的Skills、Spring AI 2.0的Skill模块以及社区里流行的Codex Skill实践提炼出一个通用结构目录大致长这样skill-name/ ├── SKILL.md # 技能说明文档包含用途、触发条件、使用流程 ├── manifest.json # 技能元信息名称、版本、作者、依赖、权限 ├── prompts/ # 可复用的提示词模板可按步骤拆分成多个 ├── scripts/ # 需要执行的外部脚本或API调用代码 ├── tools/ # 注册的工具定义OpenAPI schema或自定义JSON Schema ├── examples/ # 示例输入输出给模型做few-shot参考 ├── assets/ # 非代码资源比如参考文档、图片、模板文件 └── tests/ # 技能自测用例最关键的是最上面三层SKILL.md、manifest.json、prompts/。SKILL.md决定了模型“什么时候该用、怎么用”manifest.json决定了调度系统“能不能加载、有没有依赖冲突”prompts/则决定了“具体步骤怎么执行、输出怎么格式化”。很多人在刚开始写Skill时会犯同一个错把Skill当成一个超大号的System Prompt只有说明没有执行逻辑。这样模型确实能“理解”你的要求但没法真正“调用”外部能力Skill和普通指令之间的边界就被模糊了。一个合格的Skill必须至少包含一段可执行的逻辑——要么是脚本要么是API调用定义要么是带明确分支条件的提示词流程。1.3 为什么大家都在做Skill它解决的三个核心问题聊完结构再说说Skill到底解决了什么。我在自研Agent平台的过程中遇到的核心问题有三个Skill恰好给出了漂亮解第一是复杂任务的拆解与复用。业务方给的需求经常是“帮我把这个PDF里的数据提取成结构化Excel并生成分析报告”这种任务涉及文档解析、字段映射、数据清洗、统计计算、报告生成等多个环节。如果每次都用Function硬拼每个新case都要重新编排。但你要是把整条流程沉淀为一个“数据处理Skill”后面所有类似需求都是“加载Skill→填参数→跑流程”。第二是提示词与执行逻辑的联动。纯提示词的问题在于模型“想一套做一套”——它嘴上诉说着教科书步骤实际执行走的却是另一条路径。Skill允许你在提示词的关键节点绑定具体的脚本或工具让“说什么”和“做什么”强关联模型的行动可控性大幅提升。第三是能力的横向共享。不同Agent项目之间、不同业务线之间很多能力是重叠的。通过Skill仓库统一管理A项目沉淀的“PDF表格抽取Skill”B项目可以直接复用。这个价值在组织内尤其明显省掉大量重复开发。2. Skill调用机制的架构设计从注册到执行的全链路2.1 分层架构Skill不只是提示词而是一套完整的模块在我眼里一个相对成熟的Skill调用系统在架构上至少得分成四层技能仓库层、调度决策层、执行引擎层、观测评估层。技能仓库层管的是“技能存哪、怎么被发现”。本地目录、Git仓库、对象存储桶都可以核心是维护一份可检索的索引。调度决策层管的是“这次请求要不要用Skill、用哪个Skill、怎么编排”。这一层是大模型推理的核心涉及到技能检索、匹配排序、参数抽取。执行引擎层管的是“Skill被选中之后怎么落地”。脚本跑不跑、API调不调、中间结果怎么传回给模型。观测评估层管的是“跑完效果怎么样”。日志、追踪、评估集缺一不可。这几层的边界一定要清晰否则你就会掉进“Skill里面套Skill”的泥潭。我见过一个项目把HTTP请求直接写死在提示词里让模型去执行出了问题连日志都没有排查起来跟大海捞针一样。正确的做法是模型只负责决策执行动作全部交给代码。2.2 技能检索与匹配让大模型在几百个Skill里找到最合适的所有Skill架构里最难设计的一环不是写Skill而是让模型在正确的时间选出正确的Skill。如果你的平台未来会有几十、几百甚至上千个Skill光靠把全部Skill塞进Prompt让模型挑选是完全不现实的token消耗、注意力分散、选择准确率都会崩盘。我采用了两阶段检索方案。第一阶段是embedding召回把用户请求和每个Skill的SKILL.md描述向量化用余弦相似度召回Top 10候选。第二阶段是LLM精排把Top 10候选的简要描述、适用场景、样例输入交给主模型做一次轻量选择由模型带着Intent信息确定最终使用的Skill。这里有个经验Skill的描述信息必须分“模型可读摘要”和“完整SKILL.md”两层。召回阶段用短摘要精排阶段给完整文档确定使用后再加载完整内容能省大量token。我还习惯在manifest.json里给每个Skill加trigger_examples字段存储三四条典型的触发提问既有助于embedding质量也能让LLM精排时更稳。2.3 参数注入与上下文拼接Skill执行时的数据流设计Skill选定之后紧接着的问题就是请求里的信息如何映射成Skill需要的参数。比如“帮我对西湖区2024年的GDP数据做空间分布分析”需要抽取区域范围、数据年份、分析维度等多个参数。如果你设计了一套结构化Schema比如定义好参数名、类型、取值范围、默认值那模型抽取参数的准确度会高很多。注意Skill的参数Schema里一定要写清楚哪些参数是必须的、哪些是可选的、哪些要回问用户。最忌讳的是把必须参数设为可选然后默认值拍脑袋——宁可让Skill运行到一半停下来问用户也不要让模型带错误假设跑完整个流程。数据流方面我的建议是遵循“一次请求多轮工具调用”的模型。模型先执行Skill第一步拿到执行引擎返回的结果再结合结果决定第二步调用哪个脚本。整个过程不是一锤子买卖而是模型和执行引擎交替前进。上下文管理上至少要在系统提示中保留最近三轮的工具返回结果摘要防止模型在执行长链路时“忘了自己在干什么”。3. 工程实现中的关键环节从0到1把Skill跑起来3.1 技能文件怎么写才规范Manifest与策略分离我见过太多人把Skill写成一个几万字的Markdown然后指望模型“顿悟”后照着执行结果模型要么漏步骤要么步骤顺序颠倒。我的经验是Skill文件必须把“声明”和“策略”分离。Manifest负责“声明”名称、版本、依赖、运行环境、需要的外部权限。这部分对应manifest.json关注的是系统能不能加载、要不要装依赖、要不要检查授权。SKILL.md负责“策略”什么时候触发、怎么规划步骤、每一步做什么、输出格式怎么保证。在一份合格的SKILL.md里你应该能看到清晰的流程式描述但不能是小说式长文。我一般控制在1500字以内超过这个长度就要拆子模块。举个反面例子我一个同事写了个“财报分析Skill”SKILL.md开篇就用了1500字讲财务报表的CCTV基础模型读完确实“懂了财报”但它不知道接下来到底要调哪个函数、先算哪个指标。后来我让他改成“第一章识别财报来源文件类型第二章根据文件类型调用对应解析器第三章计算毛利率时调用gross_margin_calculator工具”模型的表现就立竿见影。3.2 变量的作用域Skill内部参数与外部系统参数的隔离Skill要跑得稳定参数作用域必须拎清。我把变量分成三类请求参数用户请求里抽取出来的比如要分析的年份、地区、文件路径。内部参数Skill内部流程产生的中间值比如解析后的临时表、清洗后的数据集。外部参数由执行平台注入的比如API密钥、当前用户ID、服务地址。这三类变量最好不要混在一起我用两套机制做隔离。Manifest里声明外部参数的获取方式由平台统一注入Skill内部代码不允许硬编码外部参数内部参数则全程在Skill执行上下文中传递不暴露给上层模型。踩过一次很实在的坑当时有个Skill内部用了os.environ[API_KEY]读密钥结果Skill被复制到另一个环境跑环境变量没配报错信息还特别晦涩排查了两小时才定位到是密钥读取失败。后来我把所有外部参数统一迁移到平台配置中心Skill内只定义可兼容的注入接口问题就再也没犯过。3.3 执行器怎么选脚本执行、API调用还是纯提示词同一个Skill可以搭配不同的执行方式我把执行器分为三类实际用哪个要看任务类型纯提示词执行器只靠模型推理完成的技能比如文案风格改写、数据解释话术生成。这类技能不需要外部依赖适合知识型技能但缺点是结果不可穷举验证。脚本执行器靠Python/Node等脚本完成确定性计算比如数据清洗、PDF解析、图像处理。这类技能我强烈建议把脚本封装成独立命令行或子进程吃标准输入输出Skill只负责传参和拿结果方便单测也方便隔离。API执行器调用外部服务的OpenAPI比如地图服务、天气服务、网盘上传。这类执行器需要把鉴权、限流、重试都封装在统一的HTTP客户端里。执行器选型的经验是能用代码算的别让模型算能用API拿的别让模型猜。模型擅长的是理解和编排不是精确计算。很多人写Skill的时候总想让模型“推断”出某个数据其实去执行引擎里写两行代码查一下又快又准。3.4 一个真实示例将“GIS空间分析”做成Skill“GIS空间分析Skill”在热搜里出现了我把它作为一个完整例子拆一下。假设用户问“请根据杭州各区的POI密度做空间聚类分析标出餐饮业态高密度区域。”第一步Skill的manifest里会声明依赖项GeoPandas、Shapely、DBSCAN、一个本地GeoJSON的基础设施图层。同时声明外部参数地图服务token。第二步SKILL.md里定义触发条件和流程用户请求里包含“空间分布”“聚类”“密度”等关键词时触发。流程是解析目标区域范围发现数据源本地矢量边界或远程WFS读取POI点数据做坐标系统一调用内部脚本poi_density_cluster.py输入区域范围和数据路径脚本执行DBSCAN聚类输出高密度簇的多边形GeoJSON生成结果说明和可视化建议第三步实现脚本时封装好参数接口python poi_density_cluster.py --region 杭州市西湖区 --poi-type 餐饮 --eps 500 --min-samples 20执行引擎拿到模型抽取的参数跑完脚本后把输出的GeoJSON和统计摘要回传给模型。模型再根据用户偏好生成结论性回答。这个例子体现了一个核心原则模型负责“读懂请求、拆解步骤、解释结果”执行引擎负责“跑计算、出精确数据”两边各干各擅长的事Skill就是中间那座桥。4. 部署与分发从单机验证到内网生产环境4.1 本地开发调试先跑通再说兼容Skill的调试是迭代速度的关键。我的习惯是先维护一个本地技能沙箱把代码改动直接跑起来用固定的测试集验证输出质量再决定是否发布到远端仓库。调试工具最顺手的方式是把Skill加载函数做到一个本地CLI里比如skillctl.debug(财务分析, 请分析2024年某公司年报)它会打印模型决策链路和每一步执行结果方便快速定位问题是出在检索、参数抽取还是脚本执行。这是一个调试器的执行效果示例[1] Skill 检索: 命中 财务报告分析 (score: 0.87) [2] 参数抽取: {file_path: /tmp/xxx.pdf, year: 2024, metrics: [roi, gross_margin]} [3] 加载执行器: PDFParserExecutor [4] 执行结果: parse_oktrue, tables12, error [5] 模型生成: 输出分析报告整个链路一眼就能看到瓶颈在哪。如果第2步抽取的参数缺了那就是Schema写得不够明确如果第4步执行报错那就是脚本实现的问题。本地先跑通再谈上线这句话在Skill工程里比什么都重要。4.2 局域网/内网部署Skill离线环境下的技能分发与安装授权热搜词里有“deepseek harness附带skill怎么部署到内网服务器”“请安装夸克网盘skill并授权账号”这其实反映了实际落地里的一个高频场景很多企业要求Agent平台部署在内网不能访问公网源所有的Skill包都必须通过内网渠道分发。内网部署Skill我走的方案有三步第一步内网架设一个私有Skill仓库一般采用Git或Oss为底层存储配合默认的索引服务。把Skill包打成标准zip格式内含manifest.json和全部依赖声明上传到内网仓库后平台扫描更新索引。第二步各内网Agent节点配置仓库地址通过skillctl install skill包名从内网拉取。拉取过程会做完整性校验和依赖解析。依赖有两种来源Python的pip、Node的npm都指向内部镜像源系统级依赖用Docker镜像提前打包。第三步涉及第三方账号授权的技能比如网盘类Skill需要做两级授权。一级是平台级授权审批通过后预留授权凭据二级是用户级授权在Skill运行时由用户完成OAuth授权。内网环境里OAuth回调需要特别注意必须把回调地址改成本地localhost:port或内网网关地址否则授权流程根本走不通。隔离环境下最容易踩的坑就是“以为装上了就完事”结果脚本一跑发现依赖缺失。建议在Skill包的manifest里加一个runtime_checks字段安装时脚本自动检查关键依赖是否满足省得运行时才炸。4.3 版本管理与灰度发布Skill这东西不是写一次就能永流传的。提示词调整、脚本更新、依赖升级都会带来行为变化。我强烈建议像管理代码一样管理Skill版本。Skill的版本管理有几条经验版本号遵循SemVer语义化版本主版本号变动代表不兼容行为变化比如执行入参改了次版本代表新增能力补丁代表修复。Skill包必须保持不可变性一旦发布这个版本就冻结了。仓库里永远只能追加新版本不能修改旧版。Agent平台要做灰度发布比如先让10%的请求流量使用新版本Skill评估效果稳定后再全量。我在项目里就是这么做的有指标异常能快速回滚到旧版本。Skill的版本回滚要能自动迁移数据和用户定义比如用户在旧版本里写的参数模板要在新版本里可兼容。5. 典型场景与热词里的Skill们行业落地实录5.1 编码类Skillskill编码193、194、247到底代表什么热词里反复出现“skill编码193”“skill编码194”“skill编码247”其实这是当前渠道生态下的一种玩法。在部分Skill分享社区作者会把Skill按类别和难度编号发布从而方便推荐位索引——比如193类偏向AI短剧脚本生成194类偏向提示词优化247类偏向专业工具生成。你可以把它们理解成“技能版本库的索引”。这类Skill热词的高频出现恰恰说明Skill已经从小圈子工具变成大众化的内容分享对象和当年GPTs的玩法有异曲同工之处。从工程视角看我不太建议一股脑装一堆“编码Skill”。更重要的是在平台里建立你的自有技能分类体系。我给团队的分类法是按任务域划分内容生成类、数据抽取类、分析计算类、自动化执行类、垂直业务类。每个域下一套独立的检索索引和测试集比单纯堆技能数量要高效得多。5.2 内容创作类SkillAI短剧、像素动画、去AI味“AI像素动画Skill”“打斗动作提示词Skill”“去AI味的Skill”这一群落选本质上都是内容生产流程的结构化封装。比如AI短剧Skill我在项目里实际落地过它的结构大致是输入短剧主题和目标平台调用“剧本结构分析脚本”拆解成开场、冲突、高潮、结尾四步根据每一步从素材库中匹配镜头描述、角色状态、对白风格调用“分镜脚本生成器”输出带中景/近景/特写提示的拍摄脚本最后用“画面风格统一器”保证同一剧集中画面质感一致“去AI味”这个需求特别有意思。它本质是通过改写规则约束模型输出痕迹——比如减少“首先、其次、总之”这类结构性废话避免每段开头重复的排比句式增加具体案例和数据。这类Skill用纯提示词就能写但要做成可复用的好版本需要建立“AI味检测文本集”反复迭代提示词里对“味”的定义。5.3 专业领域SkillGIS空间分析、语言学习、Rational Rose垂直领域Skill是壁垒最高的部分。为什么壁垒高因为一个真正能用的专业Skill需要把领域知识高度结构化模型才能操作。比如“用Agent制作Rational Rose的Skill”这里要求的不是让模型会画UML而是让它理解Rational Rose的模型文件格式能调用控制脚本批量创建类图、序列图。这种Skill的复杂度直接来源于领域建模的颗粒度。做领域Skill我从一个原则先让模型懂得“读取”再让它懂得“转换”最后才让它“生成”。也就是先提供文件的读取解析器再做领域模型的中间表示最后再做生成输出。这样即使模型每次生成的细节有偏差也至少能保证语法正确、结构可控。语言学习Skill也是同理。我见过一个效果不错的英语学习Skill它拆成了三部分关卡测评、定制化课件、即时反馈纠错。每个部分对应独立的prompt模板和脚本。模型授课讲得再活底层的词汇库和难度分级一定是固定的数据文件——这就对了不确定的内容靠模型确定的内容靠数据。5.4 个人工具型Skill夸克网盘这类技能的安装与授权热词里有个具体示例“请安装夸克网盘Skill并授权账号”这类技能属于“外部服务接入型”Skill。它的安装流程有代表性价值我拆成四步从Skill仓库下载安装包校验签名安装时读取manifest中的declared_permissions提示用户要访问的权限范围上传、下载、列表、离线转存用户配置平台级第三方账号凭据完成授权安装完成后Skill自动注册到平台的技能索引和外部服务适配器里授权这块有一个反复被问的问题为什么有些Skill装完还是没法上传文件大概率是因为授权没绑定用户会话。平台的第三方授权是跟着用户ID走的Skill的调用上下文里也必须把用户身份传进去。我见过好多次调用链里丢user_id的情况授权明明通过了但运行时报401查半天才发现是上下文里的身份信息没透传。6. 踩坑实录我在Skill工程化过程中遇到的真实问题6.1 高频问题排查速查表把我在各种Skill工程化实战中遇到的问题整理成速查表方便大家按图索骥症状可能原因排查步骤Skill没有被触发模型答非所问检索召回没命中检查SKILL.md里的触发关键词和示例提问是否覆盖了用户表达方式模型选错了Skill候选列表排序问题检查embedding后的向量检索阈值LLM精排是否被无关候选干扰参数抽取缺字段Schema描述不清晰检查参数描述里有没有说清楚取值来源和默认逻辑脚本执行报错依赖缺失或环境不一致检查manifest里的dependency声明跑一遍runtime_checks调用外部API报401/403授权失败或鉴权未透传检查授权上下文确认用户会话传递到执行层输出不稳定格式反复变提示词约束太弱增加few-shot示例强化输出格式模板用代码做格式校验Skill效果时好时坏模型版本变化锁定模型版本或针对新模型重跑测试集记录Prompt版本长链路中途失败上下文窗口溢出或状态丢失增加执行状态持久化定期总结中间结果摘要排查工具上我现在坚持“链路日志必打通”的原则。Skill执行链路要记录检索得分、选中结果、参数抽取结果、执行结果、模型生成内容五个环节的日志。出了问题打开日志对照表看一步比瞎猜快十倍。6.2 关于Skill编码和热词的一点冷知识顺着热搜词多说一句。你会发现市场上突然冒出来大量“某平台Skill安装教程”“某Skill编码下载”的内容这里面鱼龙混杂。某些“Skill编码”其实只是内容农场的引流序号同号跑不同内容的差异也很大。所以遇到新Skill我的判断路径是三条先看manifest是否完整先看README是否说明依赖先跑tests是否通过。满足这三条的Skill不管编码是几号至少是认真做的啥都没有只有一串编码和一个“亲测有效”的标题大概率直接跳过。另外Skill生态正在快速融合。Spring AI 2.0把Skill作为一等公民Codex团队论文也给出了“技能库→调度→执行”的参考架构各大平台互相借鉴Skill的格式有渐趋统一的苗头。但越是这样越要做好自己的平台内部抽象别把业务代码和某个平台的Skill格式深度耦合否则后面迁移成本会很高。6.3 Spring AI等框架下的Skill适配差异Spring AI 2.0把Skill引入Java生态后不少原先只写Python的应用开始纠结要不要迁移。我的建议看现状如果团队本来就是JVM栈那Spring AI的Skill组件值得试如果团队已经在Python的LangGraph或其他框架上跑通了那就别为技术新鲜感乱动。适配层面有一点要注意不同框架对Skill内部脚本的执行方式不一致。有的框架允许Python脚本子进程执行有的只允许JS沙箱有的只支持声明式工具调用。所以跨框架迁移Skill时不能只迁移SKILL.md要连执行器接口一起重新适配。阶段上可以先把纯提示词型Skill平滑迁移脚本型Skill按优先级排队适配。不要指望Skill包100%跨平台无缝迁移至少在2025年这个阶段统一格式的愿景还没完全落地。我在实际使用中还有个体会框架选型不必追求“覆盖全部Skill能力”的框架而是选一个能让你快速定义、测试和迭代Skill的框架把更多决策留给自己的技能体系。框架的下层机制反而是次要的。这和写代码一个道理框架只是地基房子盖成什么样靠的是你自己的架构水平。6.4 关于成本与性能的平衡最后说说成本。Skill调用机制虽然好用但它比简单的Prompt对话要贵得多——因为多出了检索、精排、多轮工具调用、结果验证等多个步骤。以我自己线上一个Agent服务为例单次普通问答耗token约800而带一次Skill完整执行的任务平均耗token会到3000以上调用外部API的次数也增加两到三次。要想控制成本有几个成熟手段第一嵌入向量是固定开销用便宜的Embedding模型精排再让强模型上。第二SKILL.md按需加载不要在每轮对话里都贴出完整文档。第三脚本和API能处理的事情就不要让模型反复推理减少模型“胡思乱想”的步骤。第四对高频简单场景直接走快捷路径跳过检索精排比如固定模板任务。第五对长链路任务设置最大步骤数比如最多调用5次工具超了自动收敛并总结避免模型绕圈烧钱。这几招组合下来我实测可以把单次Skill任务的token成本压回到传统方案的一半以下而且执行效率和稳定性反而更高。做工程嘛效果不是唯一指标成本也是要认真算的账。这也是为什么我一直强调“执行引擎多做、模型少做”的原因之一。现在再看这套架构我最大的感受是Skill调用机制把Agent应用从“模型驱动的单点问答”推向了“模型工具协同的工作流平台”。这个方向不会因为某个具体产品火不火而改变因为它的核心价值——让模型干成具体的事——永远是刚需。后续值得持续投入的方向包括更强大的技能检索排序、更细粒度的技能安全隔离、以及更标准的跨平台技能交换格式。