做AI Agent开发这一年多我发现在“Skill开发”这件事上很多人跟我最初一样陷入一个误区以为写Skill就是写个Python脚本本地跑通了就算完事。结果一到云端平台模型不会调用、参数传不进去、环境依赖装不上、返回格式不被解析一堆问题接踵而至。这篇内容不是一份标准教程而是我把一个完整的Skill从本地实操到云端落地的全过程复盘包括思路拆解、参数设计、调试技巧、云端部署的坑以及在开发过程中对“Skill到底是什么”这件事的认知转变。如果你正在折腾智能体、插件开发或者准备把本地脚本封装成云端可复用的技能模块这篇复盘应该能帮你少走不少弯路。1. 整体设计与思路拆解1.1 Skill到底是个什么东西先说结论Skill不是你写的一段普通脚本而是“给大模型准备的一个标准化乐高块”。大模型本身什么都不缺缺的是“出去干活的手”——它需要调用外部工具去搜索、去查库、去算数、去处理文件。但你不可能在对话里一句“帮我算个东西”就让模型凭空调用你的代码所以需要一种机制把“模型的意图”翻译成“程序能执行的指令”再把“程序返回的结果”翻译回“模型能理解的语言”。这个机制就是Skill。所以我后来总结了一句话Skill的核心不是代码而是“描述”。代码只是执行体真正决定一个Skill有没有用的是——它有没有把“什么时候用、需要什么参数、返回什么结果”这件事说清楚说给模型听。这就解释了一个现象为什么同样一个能力有的人封装的Skill模型一用一个准有的人封装的Skill模型根本不知道什么时候该调用。差别不在编程水平而在“描述能力”。你在本地写脚本机器替你执行你写Skill是让另一个“智能体”替你判断和执行本质上你是在跟模型协作而不是在给机器下指令。这个思维转换如果不完成后面写多少Skill都是照猫画虎。1.2 先想清楚“谁会调用你的Skill”动手之前我强烈建议你先回答三个问题。这是我在踩了无数次坑之后总结出来的自检清单。第一个问题这个Skill的触发场景是不是足够清晰比如你做一个“网页内容解析”的Skill那你必须想清楚——模型在什么情况下会使用它是用户丢了一个链接让总结内容还是用户提到某个网址需要提取信息场景越清晰你给模型写的描述就越准确调用率就越高。反过来你要是描述得含含糊糊模型就会选择更保守的策略——不调用。第二个问题输入参数到底是模型能从对话里抽出来的还是需要用户手动填的这个问题决定了你的参数设计复杂度。比如做“聚合搜索”功能关键字这个参数模型很容易从用户对话里抽出来但如果是“查询指定商品的历史价格走势”你就必须考虑用户是不是得先提供一个商品ID或链接这个信息模型不一定能凭空生成。参数来源不清晰的话模型会频繁向用户追问体验很差。第三个问题你的Skill返回的结果是“给人看”还是“给模型加工”如果返回结果直接展示给用户那你的输出格式可以自由一点但如果返回结果还要让模型二次加工——比如总结、翻译、对比——那你输出的结构就必须足够规整最好是JSON而且是平铺字段越少越好嵌套越浅越好。我见过很多开发者在返回结果里塞了一大段HTML模型根本抽不出有效字段整个Skill就等于废了。这三个问题想清楚再动手后面基本不会返工。想不清楚就写大概率是边写边改改到怀疑人生。1.3 本地开发与云端落地的核心差异很多人忽略了一个关键事实本地调试成功只是万里长征走完了一半。Skill在本地跑的是Python进程一切都在你掌控之中但到了云端Skill的运行环境、调用方式、参数来源、资源限制全都变了。我总结下来本地与云端的核心差异集中在四个方面。第一参数来源不同。本地开发时你可以在代码里硬编码参数写死一个链接去测试云端落地时所有参数都必须依赖大模型从用户对话中抽取然后按照你定义的JSON Schema生成。模型的理解能力直接决定参数质量——它可能漏参、可能传错类型、可能把用户的一句口语硬塞进一个枚举字段。第二运行环境不同。你本地可能是Python 3.10云端可能是3.11甚至更高你本地安装了requests、pandas云端可能只有基础环境需要你手动声依赖。更麻烦的是云端沙箱的网络策略、文件系统权限、超时时间你本地根本感知不到。第三文件结构不同。云端平台通常要求一个规范化的目录结构比如有个配置文件描述Skill的基本信息有个说明文件告诉模型怎么用主脚本才放在特定位置。你本地随便建个一个文件扔进去平台根本识别不了。第四调试反馈周期变长。本地改代码跑一次几秒钟出结果云端部署后每次调试要经历上传、构建、配置、调用一次至少几分钟。所以你得把大部分逻辑问题在本地解决掉把云端留给“环境适配”和“模型调用验证”这些事情。这些差异决定了开发策略本地把逻辑焊死云端只做适配。2. 核心细节解析与实操要点2.1 Skill目录结构与文件职责一个规范的Skill目录结构大概长这样my_skill/ ├── skill.json # 技能配置文件声明名称、描述、参数 ├── SKILL.md # 给大模型看的说明文档指导模型何时调用 ├── main.py # 主执行脚本 ├── requirements.txt # Python依赖清单 └── assets/ # 静态资源目录可放模板、字典、参考数据先说skill.json。这个文件是整个Skill的“身份证”里面包含了开发这个Skill的元信息。我第一次写的时候觉得这种东西随便填填就行结果平台构建直接拒绝原因是缺少必填字段。一个典型的skill.json长这样{ name: web_content_summarizer, description: 抓取指定网页正文内容并返回纯文本摘要。当用户提供链接并要求总结、提取关键信息时使用。, version: 1.0.0, parameters: { type: object, properties: { url: { type: string, description: 需要解析的网页完整URL地址。 }, max_length: { type: integer, description: 摘要最大字符数默认500。, default: 500 } }, required: [url] } }这里有一个很多初学者没注意的细节description字段不只是给人看的大模型也会读。你在skill.json里写“当用户提供链接并要求总结时使用”模型就会在对话中检测这个意图。这块描述写得好坏直接决定模型能不能在用户说出“帮我看看这篇文章讲了啥”的时候果断调用你这个Skill。然后是SKILL.md。如果说skill.json是给平台看的元数据SKILL.md就是给模型看的“使用手册”可以说是整个Skill文件里最容易被低估的组件我当然也是花了不少冤枉时间才真正重视它。通常我会在SKILL.md里写下这个Skill是做什么的边界是什么不该管的事情不要管什么时候必须调用什么时候不应该调用参数的详细说明特别是格式、单位、取值约束返回结果的结构说明和示例让模型知道拿到的数据长什么样、能用来干嘛。与直觉相反SKILL.md写得越细致模型调用得越准。你以为简短点省token实际上模型拿到的信息太少就会猜测你的意图而猜错的代价远比省下的token大得多。2.2 JSON Schema参数设计的几个关键细节参数设计是整个Skill开发中最容易踩坑的地方。我常用一个生活化的类比来解释JSON Schema就像给模型发了一张“标准入住表格”模型中文学得再好也得逐栏填写不能自由发挥。你表格设计得越清楚填表的人越不容易出错。但表格太复杂填表的人又容易怯场乱写。这里面有几个关键尺度值得多花笔墨展开。第一个关键点是参数类型要“窄而准”能填枚举就填枚举。比如你要做一个“情绪分析”的Skill情绪类别你就直接写死emotion: { type: string, enum: [positive, neutral, negative], description: 文本情绪类别 }不要写“请填写情绪类型可以是开心、难过、生气等”——模型会发挥想象力填出五花八门的值你的代码就被迫处理各种方言变体。枚举的好处是双向约束模型只能单选你的代码也只需要处理固定的几个值谁都不用猜对方的想法这能省下无穷多的边缘情况。第二个关键点是参数描述要包含“同义词提示”。比如参数名叫“q”你光是写“查询关键词”模型可能从对话里抽取不准。更好的写法是q: { type: string, description: 搜索查询词。支持自然语言短语、品牌名、商品名等例如无线蓝牙耳机、最近热门的AI工具。 }所谓同义词提示就是在描述里把用户可能表达这个参数的各种说法都列出来相当于告诉大模型用户说“帮我找找XX”、“XX有什么推荐”、“XX怎么样”这些都算这个参数的值。这种做法能显著提高参数抽取准确率大概是我调试几个月后总结出的最有效的技巧之一。第三个关键点是必填字段越少越好。在你的Schema里我强烈建议只把“没有它功能就无法运行”的参数设为必填其他全部给默认值。原因很简单模型每次抽取参数都是一次“翻译任务”多抽一个参数就多一分出错风险。能靠默认值兜底的就不要逼模型去猜。比如summary_length这种参数给它默认值500用户没说需要多长你就按500处理完全不影响功能还少一个出错点。还有一个很多人忽略的细节参数类型要跟你的脚本实际接收时做好容错。模型从自然语言里抽取数字的时候可能给你一个字符串例如“500字”或者“五百”你的脚本入口就不能直接int(x)一把梭做好类型清洗和兜底转换。最开始我不理解为什么明明没有“长文本”的输入模型还会硬传后来才明白——对话框里用户的问题千奇百怪大模型经常把所有可能相关的信息都塞进去。做一个健壮的解析层比在云端一遍遍调试代码要有用得多。2.3 本地调试的黄金法则让脚本先学会“装傻”本地调试阶段很多人犯的一个错误是直接用真实参数跑脚本跑通了就以为大功告成。但我踩过的坑告诉我你有必要反过来让脚本先学会“装傻”——也就是专门喂一些刁钻的输入来测试它的抗干扰能力。什么叫刁钻的输入就是用户平时说话那种充满冗余信息的表达方式。比如用户说“帮我看看这篇文章到底写的啥就是这个链接 https://example.com/article大概500字以内吧”模型在抽参数时很可能把“500字以内”抽成数字500也可能把“这个链接”抽出来当参数名。你本地测试时就应该模拟这种情况把所有乱七八糟的说法全当成输入看你的脚本会不会崩。另一个实用技巧是“空参数测试”把必填参数之外的字段全部留空看脚本能不能用默认值跑通。往往你写完主逻辑后第一次空参数测试就崩——因为你没想到max_length可能压根不存在或者None值会被你的代码直接拿去处理。提前做一轮防御性编码让参数清洗函数去统一处理None、空字符串、异常类型保证任何状态下脚本都不会因参数异常而崩溃。如果说还有一条调试心得那就是“日志打全”的偏执。本地调试时我会在每个关键节点print一行日志记录收到的原始参数、清洗后的参数、调用的第三方接口、返回的状态码。这些日志在云端排查问题时就是救命稻草。很多平台只给你看标准输出看不到系统级日志如果你自己不多打印出错时就等于在黑暗里摸象。3. 实操过程一个完整Skill从零到一3.1 选型与场景定义我这次复盘时选的实践对象是一个“网页正文提取与内容摘要”Skill。为什么选它因为这个场景非常典型用户给一个链接要你总结或者提炼重点本身逻辑不算复杂但依赖外部网络、需要解析HTML、还要控制返回长度——水平和垂直两个维度都有代表性。开发这个Skill时我的功能边界定义为输入一个URL抓取页面内容剔除导航、广告、页脚等噪音模块提取核心正文按字数要求输出摘要并以结构化JSON返回。边界之外明确不做的事情包括登录墙内容抓取、动态渲染页面的抓取、视频内容解析。这些边界写清楚一方面是为了防止模型把不合适的任务交给Skill另一方面也能避开一堆法律和网络策略的坑。3.2 本地开发与逐级调试这个过程我分了三步走。第一步先写一个最朴素的抓取函数直接用requests请求目标页面拿到HTML再用正则或者解析库提取正文。import requests from bs4 import BeautifulSoup def fetch_article(url: str) - str: headers { User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 } resp requests.get(url, headersheaders, timeout10) resp.raise_for_status() resp.encoding resp.apparent_encoding soup BeautifulSoup(resp.text, html.parser) for tag in soup([script, style, nav, header, footer, aside]): tag.decompose() article soup.find(article) or soup.find(main) or soup.body lines [line.strip() for line in article.get_text().splitlines() if line.strip()] return \n.join(lines)这里有个实操细节requests拿到响应后一定要用resp.apparent_encoding去修正编码。很多中文网页的headers里不写charset或者写错了直接使用resp.text会乱码。如果你在本地跑得好好的一到云端输出一堆乱码90%都是编码问题。另外User-Agent一定要伪装成一个浏览器否则不少网站直接给你403这个我是在第一次调试抓取资讯站点时踩到的一开始以为是代码问题排查半天才发现是请求头被拒了。第二步写摘要生成逻辑。我想避免依赖大型模型做二次生成所以在Skill内部实现了一个朴素的“按段落权重抽取”的摘要器def summarize(text: str, max_length: int 500) - str: paragraphs [p.strip() for p in text.split(\n) if len(p.strip()) 20] if not paragraphs: return text[:max_length] score_by_index {} for idx, para in enumerate(paragraphs): score len(para) if idx 0: score * 1.2 score_by_index[idx] score result for idx in sorted(score_by_index, keyscore_by_index.get, reverseTrue): if len(result) len(paragraphs[idx]) max_length: continue result paragraphs[idx] \n if len(result) max_length: break return result.strip() or text[:max_length]这套逻辑很粗糙但足够在本地跑通主链路。你要做自己的Skill时不需要追求一步到位的效果先把链路跑起来更重要后续可以再换更好的抽取算法。开发这类能力时比较稳妥的思路是第一版就看能不能抓到内容、能不能返回结构化结果只要主流程通了再回头优化摘要算法千万不要一开始就陷入算法调优的泥潭。第三步用一个带main入口的封装让Skill无论被本地脚本调用还是被平台调用都走同一套参数解析逻辑def main(): import sys import json raw_input sys.stdin.read() try: params json.loads(raw_input) except json.JSONDecodeError: params {} url params.get(url, ) max_length int(params.get(max_length, 500)) try: content fetch_article(url) summary summarize(content, max_length) output { success: True, summary: summary, source_url: url, content_length: len(content) } except Exception as e: output { success: False, error: str(e) } print(json.dumps(output, ensure_asciiFalse)) if __name__ __main__: main()这里有一个重要设计Skill的入口约定为从标准输入读取JSON参数向标准输出打印JSON结果。不管云端平台用哪种方式调用这个约定都是最通用的。我在本地调试时就直接用管道方式模拟平台调用把JSON参数echo进Python脚本看输出的结构对不对这个过程非常贴近真实场景。顺带说一个细节json.dumps时一定要加ensure_asciiFalse否则中文全部变成\uXXXX转义序列模型拿到之后很难直接理解。这个选项本地测试时几乎感觉不到差异但到了云端模型手里可读性上的差距会被明显放大。3.3 云端落地的配置与发布本地链路跑通以后就到了最关键的云端部署环节。不同平台的部署流程大同小异核心步骤有三个上传代码、配置依赖、声明参数映射。上传代码这块如果平台支持直接输入代码照抄即可如果支持上传ZIP包打包时务必注意不要包含本地的虚拟环境目录、缓存文件和多余的样本数据。尤其是依赖管理我强烈建议你手写一份requirements.txt而不要靠平台自动检测。自动检测经常会有误判或者在构建阶段发生版本冲突到时候日志里只给一句“build failed”你根本无从下手。requests2.31.0 beautifulsoup44.12.3版本号尽量锁死不要写requests2.31.0这种宽松版本。理由很简单今天写宽松约束明天云端构建时可能面对一个全新的环境把最新版依赖拉进来如果你的代码用了旧版API就会莫名挂掉。锁版本是减少不确定性成本最低的手段。配置参数映射这是最容易出错的地方。云端平台往往要求你在控制台上配置参数名与本地代码里的字段一一对应但平台生成的参数名可能自带前缀或者格式上有区别。如果你在skill.json里写了url在代码里也是url但平台的某个设置非要自动加一层路径那实际传进来的字段就变成了params.url这种嵌套结构你自己不亲眼验证的话根本不会发现。我的建议是在代码入口处加一层“参数解包”也就是不管传进来是嵌套还是平铺统一捞一层之后再做字段映射。多写这五六行能替你挡掉一大半云端调试的坑。部署完成后先不要急着发布。在平台控制台里发起一次测试调用但不要用“默认生成的测试参数”要自己写一个模拟用户请求的JSON例如{ url: https://example.com/article, max_length: 300 }跑通之后再看平台返回的JSON结构是否完整、摘要是否合理。这一步通过之后才建议真正发布给外部使用。3.4 上线后的验证与迭代发布上线不等于工作结束。我一般会在上线后的头几天保持高频观察重点看三件事调用成功率、平均响应耗时、返回内容被采纳的比率。调用成功率比较好理解只要日志里有报错就会暴露。响应耗时则要警惕一种情况你的Skill本身跑得很快但模型拿到你的JSON结果后还要做二次加工那段耗时用户也会感知到所以日志只能辅助判断不能只看Skill本身的耗时。返回内容被采纳的比率这个指标容易被忽略但很有价值。你可以通过对话记录观察用户是否多次追问、是否表示不满意间接判断Skill返回的内容质量。比如摘要过于抽象、抓取的正文时间地带了网站版权声明、返回的内容跟链接完全无关这些现象都会让用户不满意。发现问题后不要急着改算法先回到“参数描述”和“输出描述”上检查大概率是模型调用时给的原始输入不对或者对你的输出结构理解不到位。关于迭代我有一条实践心得改动描述文件SKILL.md或skill.json描述后一定要重新走一遍完整的调用链路不要只重新上传代码。因为描述文件的变更影响的是模型的调用判断这个影响只能用真实请求去验证本地怎么测试都测不准。4. 常见问题与排查技巧实录4.1 本地跑通云端就挂的经典三连几乎每个Skill开发者都会经历一次“本地明明没问题云端一调用就报错”的循环。这类问题我来回跑过无数遍归纳下来主要是三个原因。第一是依赖缺失。本地有Anaconda或者全局环境兜底你import的任何库都在云端沙箱很干净你没声明依赖就是没有。解决办法是老老实实把requirements.txt补齐然后重新构建一遍。第二是相对路径问题。本地脚本可能依赖某个同目录的配置文件你在本地写的路径是./config.json但云端的工作目录不一定就是脚本所在目录。这个坑我在一个需要加载静态词表的Skill上遇到过改成使用Path(__file__).parent来定位文件就彻底解决了。第三是网络被限制。云端沙箱可能不允许访问某些内网地址或者特殊端口也可能默认禁掉了非HTTPS请求。针对这种情况做一个检测在返回结果里附带一个http_status字段便于收到输出后快速定位是网络策略还是目标站点本身的问题。4.2 模型传参不听话怎么办你会在日志里看到一些匪夷所思的传参枚举值拼写错误、数字传成字符串、必填字段遗漏、甚至参数名都对不上。最初我以为是平台的问题后来发现这是LLM抽取自然语言参数的固有误差完全消除是不现实的你要做的是让系统“扛得住”。我的方案是在代码入口处加一个“参数归一化”函数把所有可能的别名、类型、格式统一处理def normalize_params(raw, aliases): params {} for key, value in raw.items(): clean_key key.strip().lower().replace(-, _) params[clean_key] value for canonical, candidates in aliases.items(): for c in candidates: if c in params and canonical not in params: params[canonical] params[c] break return params比如模型可能传URL、url_link、page_url你把这些别名全部映射到url。平时不觉得这有什么一旦你在线上看到模型传了个Url而不是url你就会感谢这个函数了。除了参数名在类型处理上也做同样的容错把数字字符串转成int把首尾空格trim掉把None值替换为默认值——发挥你的编程经验把能想到的脏数据形态都提前接住。4.3 依赖装不上的治理方案云端构建依赖失败也是一个高频问题。我见过最多的情况是某个库在本地有预编译的wheel但云端用的Python版本和系统架构不匹配会现场尝试编译源码紧接着报错。这时候我的排查顺序是锁定依赖版本把requests这种底层的库尽量固定到有预编译的稳定版本查看平台是否支持手动指定Python版本如果支持先与本地版本对齐如果某一个库始终装不上考虑替换实现——比如不用lxml改用html.parser不用pandas改用纯Python处理。很多Skill根本不需要一堆重型库。能用标准库解决的就不要引第三方依赖。依赖越少云端构建越稳定这句话我在踩过无数依赖坑之后已经把它当成选择库的第一原则。4.4 排查速查表习惯把常见问题整理成一张表遇到问题先查表定位效率提升明显。现象大概率原因排查顺序收到请求但无任何输出入口脚本未捕获异常或stdout未刷新在入口处包一层全量try/exceptself-test打印返回乱码响应编码未设置或JSON未用ensure_asciiFalse检查apparent_encoding与json.dumps参数模型从不调用SkillSKILL.md描述不明确或skill.json的description与场景不匹配检查描述语句是否包含明确触发条件参数缺少默认值required字段过多或模型抽参失败后直接用空值调用精简必填字段代码增加None兜底调用超时目标网站响应慢脚本串行处理导致总耗时过高设置timeout缩短单次任务链路Skill上传后构建失败依赖缺失或版本冲突查看构建日志锁定requirements版本这张表在每次复盘时我都会更新发现问题就补一行。积累一段时间后你会发现自己排查线上问题的时间越来越短很多情况扫一眼报错就能猜到根因。5. 复盘之后我对Skill开发的几点认知深化5.1 从“写功能”到“定义接口”的思维转变以前写代码我关心的是“功能正确”给一个输入得到预期输出任务就完成了。但Skill开发让我不得不切换到一个更上层的视角我关心的是“接口清晰”模型能不能准确理解这个接口能不能正确调用它调用之后的结果能不能被模型再次加工。这个转变最直观的体现是我现在开发一个Skill花在设计描述上的时间比写代码的时间还要多。每次我都会反复修改skill.json里的description和SKILL.md的表述经常改一版就要去实测一次。我意识到代码只是接口背面的实现细节面向模型的那一面才是真正需要精心雕琢的。一位做智能体开发的前辈跟我说过一个比喻我记到现在写Skill很像教一个聪明但死板的实习生做事。你不能只给他讲一遍做法就指望他举一反三你要把什么场景做、什么场景不做、输入怎么填、输出怎么返回全都交代清楚他才不会给你捅娄子。这个比喻对我影响很大。5.2 边界设计比功能设计更重要以前开发模块时我习惯把功能铺开得越全越好。做Skill之后我发现边界感必须放在第一位。一个Skill的边界不清晰模型就不知道该不该调用它调用之后也不知道它能不能处理最后的结果就是模型要么乱调用、要么不敢调用。比如我最初给“网页摘要”Skill加了很多扩展功能支持自定义提取规则、支持深度爬取、支持多页面对比。听起来很强大但模型在实际对话里根本不会触发这些扩展参数反而因为Schema里可选字段变多抽取参数的准确率明显下降。后来我砍掉了所有非核心功能只保留URL和长度两个参数调用率和成功率反而双双提升。所以现在的开发原则很明确一个Skill就做好一件事边界用自然语言写得清清楚楚能力范围宁窄勿宽。多出来的需求可以拆成新的Skill而不是硬塞进一个技能里。5.3 自动化落地的核心是“信任边界”复盘整个开发过程我觉得最值得沉淀的一点是所谓“自动化”并不是让系统完全替人做决定而是要找到人、模型和执行器之间的信任边界。Skill的落地方式本质上也是这个逻辑人类用自然语言表达意图模型负责把意图翻译成精确的执行指令代码负责可靠地执行。三者各管一段每一段都有清晰边界。信任边界清晰了系统才真正稳定可靠边界一旦模糊系统就会陷入各种无法预期的混乱。我现在评估一个Skill做得好不好标准很简单把一段真实的用户对话丢给它看模型是否在正确的时候调用它参数是否正确返回结果是否被合理利用。如果这三个环节都顺畅这个Skill就真正“落地”了。5.4 给后来者的一点实操建议如果你正准备开始自己的第一个Skill我的建议是不要贪多从一个非常小、非常具体、几乎只做一件事的功能开始。先跑通“定义接口、编写脚本、本地调试、云端部署、模型调用”的完整闭环再慢慢扩展。闭环建立的体验比写十个半成品Skill的收获都要大。其次强烈建议你保存每一次调试的记录包括参数schema的版本变化、踩过的坑、最终的描述文案。这些东西在你后续开发其他Skill时都是宝贵的对照样本。我自己就是靠这些记录逐步归纳出了一套稳定的开发模板。最后把测试当成开发的一部分而不是事后动作。每次修改描述文件后都做一次完整调用验证每次发布前都用拟真用户请求跑一遍全链路这些小习惯会让你的Skill从一开始就保持在一个相对健康的状态后续维护成本也会低很多。