AI Skill技能包实战：从SKILL.md编写到发布安装全流程

先说个现象2025年AI圈子里最热的词之一就是skillGitHub上的skill技能库、codex skill、opencode skill、spring ai skill铺天盖地大家突然发现光会写prompt已经不够看真正能让大模型稳定干活的是给它配一套定义好的“技能包”。我花了几个周末从零开始研究skill怎么写踩了一堆坑之后终于把整个流程跑通这篇文章就把我的完整思路和实操过程整理出来希望能帮到正在折腾的你。文章不会讲太多虚的直接从“skill到底是什么”说清楚然后带你手把手创建一个能真实运行的skill项目包括目录结构、SKILL.md怎么写、脚本怎么配套、参数怎么设计、怎么发布和安装最后附上我在调试过程中遇到的各种坑。无论你是想给Codex、opencode这类CLI工具配技能还是想研究Agent的技能编排这篇文章都应该能给你一个完整的参考框架。1. Skill到底是什么把“经验”打包给AI1.1 从Agent说起为什么大模型需要“外挂技能”聊skill之前得先回到一个基础问题为什么现在大家不满足于直接对话非要搞出一个叫skill的东西。原因其实很简单大模型本身是个“纸上谈兵”的天才。你跟它说“帮我分析这组数据的分布特征”它能给你写出一篇漂亮的统计学分析报告但它自己不会去读文件、不会去执行Python脚本、不会去查数据库更不会根据实际报错反复调整参数。这就是纯Prompt的极限——它只能输出文字不能真正操作工具、操作系统、操作代码。Agent作为一层“大脑手脚”的组合让模型能调用工具、执行命令、观察结果、再决策下一步。但Agent只是给出了一个行动框架具体到“每一步该怎么走”如果完全靠模型临场发挥结果往往不稳定同样一句指令它今天按这个流程走明天就换了一套流程输出质量完全看运气。Skill就是来解决这个稳定性的问题。它的本质是把一套完成特定任务的标准流程、提示词约束、代码工具、领域知识打包成一个可以被Agent按需加载的独立模块。你可以把它理解成给AI“外挂”了一份岗位SOP它接到相关任务后不再自由发挥而是按SOP执行甚至在关键环节调用你写好的脚本把结果精确计算出来。我自己的体会是从“写prompt”到“写skill”思路转变非常大。以前我写prompt是在“教模型说话”现在写skill是在“给模型设计一套完整的工作制度”包括它什么时候该说什么、什么时候该动手、什么时候该调用工具、输出格式必须是什么。这个转变一旦打通AI才真正从“聊天对象”变成“干活的人”。1.2 Skill的身体结构一个完整的技能包长什么样动手写skill之前先搞清楚它的物理结构否则后面全是懵的。一个典型的skill项目目录通常长这样my-skill/ ├── SKILL.md # 技能的核心描述文件相当于“大脑说明书” ├── scripts/ # 可执行脚本辅助模型完成具体计算/操作 │ ├── analyze.py │ └── format.py ├── reference/ # 参考文档、领域知识、示例模板 │ └── report_template.md └── requirements.txt # 依赖声明可选其中最重要的就是SKILL.md它是Agent加载技能时第一个读取的文件。这个文件里通常包含两部分一部分是YAML格式的元信息比如技能的name和descriptionAgent就是靠description来判断“什么时候该调用这个技能”另一部分是Markdown格式的技能正文用来告诉模型“这个技能具体怎么执行”包括任务拆解、执行步骤、输出格式、注意事项、工具使用方式等等。scripts目录则用来放真实可执行的代码。为什么要放脚本因为模型擅长“生成文字”但不擅长“精确计算”比如让它算个统计量、批量改文件名、解析JSON虽然它也能写代码但让它直接执行不如让它调用你写好的脚本稳妥。你提供脚本模型只负责编排和解释准确率会高很多。reference目录是可选但很实用的部分放一些领域背景知识、专业术语表、范例输出等相当于给模型一份“考前参考书”在复杂任务中能显著提升输出质量。1.3 Skill与Agent、Prompt、Plugin的区别很多初学者会把Agent、Skill、Prompt、Plugin混在一起我刚开始也绕晕了这里用最直白的话说清楚Prompt是一段话告诉模型“这次任务怎么做”是一次性的、静态的Plugin是一组程序接口给模型提供某种能力比如联网搜索、读写文件、执行代码它是“工具层”Agent是编排层它负责理解用户意图、拆解任务、决定调哪个工具、循环推进直到完成Skill介于Prompt和Plugin之间它把“某一类任务的完整解决方案”固化下来既是提示词又包含工具调用说明还可能附带脚本。Agent在运行中可以动态加载skill再配合plugin去执行具体操作。所以简单理解Agent是项目经理Plugin是工具箱Skill是项目经理手里的“标准作业流程卡”。项目经理接到任务后先翻作业流程卡找到对应的流程再拿起工具去干活。这就是为什么skill非常适合沉淀那些“流程明确、重复性高、标准严格”的任务比如写周报、做数据分析、跑测试用例、生成特定格式的文档等。2. 动手前准备环境、工具和第一个实验2.1 准备哪些工具创建skill本身不需要太复杂的环境本质上你只需要一个文本编辑器和一个能跑脚本的运行时。但既然要测试skill在真实Agent里的表现我建议你至少准备以下环境一个支持skill加载的Agent客户端目前主流的有Codex CLI、opencode以及一些基于Spring AI自建的多智能体框架它们的skill目录约定大同小异Python 3.10因为很多示例脚本都是Python写的而且Python做文本处理、数据分析最方便Git用于本地版本管理以及后续发布到GitHub一个终端模拟器Windows推荐Windows TerminalmacOS直接Terminal或iTerm2都行。如果你是零基础别慌skill的开发门槛其实不高。你不需要先学会训练模型也不需要懂复杂算法只要会写基本的Markdown和Python脚本就能做出一个有用的skill。2.2 设计一个最小可用Skill从需求拆解开始为了让流程足够具体我带大家做一个实际能用的skill名字就叫markdown-report-skill。这个技能解决一个非常典型的场景给Agent一段原始素材比如会议记录、实验数据、调研要点它能自动生成一篇结构化Markdown报告并且严格遵循预设的报告格式。这个需求定得很用心原因有三点第一报告生成是高频场景几乎所有人都能用上第二它的输出格式有明确约束非常适合体现skill“固化流程”的价值第三它既要写文本又可以搭配脚本做辅助处理能完整展示skill开发的各个环节。拆解一下需求这个skill需要做到以下几点接收用户提供的原始素材不分格式纯文本、Markdown、JSON都行自动识别素材内容类型会议纪要、实验数据、调研摘要等按预设模板生成报告模板包含背景、核心内容、结论建议三大部分如果素材中包含数据列表自动转换成Markdown表格输出一份排版干净、可直接发布的Markdown文件。2.3 建立项目目录与骨架需求拆解完之后先建目录骨架再一步步填充内容。我在本地建了一个新文件夹名字就叫markdown-report-skillmkdir markdown-report-skill cd markdown-report-skill mkdir scripts mkdir reference touch SKILL.md touch scripts/build_report.py touch reference/report_template.md这时候目录结构是空的接下来我会按“先写模板再写SKILL.md最后写辅助脚本”的顺序来填充。我的经验是先确定模板相当于先定标准后面写提示词和脚本都围绕标准来就不会跑偏。3. 核心编写实操从SKILL.md到可运行的技能3.1 SKILL.md的编写规范SKILL.md是整个skill的灵魂它的内容质量直接决定Agent的执行效果。我第一次写的时候基本就是把prompt改个文件名放了进去结果运行效果跟直接对话没什么区别后来研究了很多开源skill项目才发现SKILL.md有自己的写法套路。一个高质量的SKILL.md通常分两个block先看YAML元信息部分--- name: markdown-report-skill description: 根据用户提供的原始素材会议记录、实验数据、调研要点自动生成结构化的Markdown报告包含背景、核心内容、结论建议并自动将数据转化为表格。 ---name要简短明确description尤其关键因为Agent就是靠读取description来决定“当前任务是否匹配这个技能”。description写得越具体技能被正确触发的概率越高。比如我这版description就明确了适用场景和输出特征如果写成“生成报告”这种泛泛的描述Agent可能在很多不相关的场景下也尝试加载反而影响效果。再看技能正文部分这部分才是核心。我整理出自己在实操中验证有效的结构供你参考# Markdown报告生成技能 ## 目标 根据用户提供的原始素材生成结构化、排版规范的Markdown报告。 ## 背景 用户通常没有时间手动整理会议记录或实验数据需要快速转化为可汇报、可存档的文档格式。 ## 执行步骤 1. 阅读用户提供的素材判断素材类型属于会议纪要、实验数据、调研摘要中的哪一种 2. 提取素材中的关键信息背景、核心结论、数据指标、待办事项等 3. 按照参考模板(reference/report_template.md)组织报告结构 4. 如素材中包含连续数据如销售数据、测试指标使用scripts/build_report.py生成表格片段 5. 输出完整Markdown报告。 ## 工具使用说明 - 当素材中包含结构化数据时调用scripts/build_report.py传入原始数据文件路径 - 脚本会输出Markdown格式的表格代码直接拼接到报告中对应位置。 ## 输出格式 - 一级标题报告题目 - 二级标题背景、核心内容、结论与建议 - 数据一律使用Markdown表格展示 - 报告末尾必须附上“数据来源说明” ## 注意事项 - 如果原始素材信息不足不要强行编造在报告中标注“信息缺失” - 素材中的数字必须原样保留不得四舍五入或修改 - 严格使用简洁、客观的书面语。看到区别了吗它不是一段笼统的“你要好好写报告”而是一套详细的作业指令规定了模型读什么、怎么判断、按什么顺序做、调用什么工具、输出什么格式、遇到特殊情况如何处理。这就是把“人的经验”变成“AI的流程”的过程也是skill和prompt最大的分水岭。3.2 写辅助脚本让AI真正“动手”而不是“耍嘴皮”SKILL.md负责“思想”scripts里的脚本负责“动手”。我设计的build_report.py功能就是接收一个包含原始数据的文件自动识别其中的数字指标将它们转换成格式优美的Markdown表格。这个脚本本身功能不复杂但很能代表skill里脚本的设计哲学小而专、输入输出明确、由模型来调用。看一下我写的核心代码import sys import json import re from pathlib import Path def extract_table_data(text): 从文本中提取表格数据支持JSON数组和类CSV格式 text text.strip() try: data json.loads(text) if isinstance(data, list) and len(data) 0: return data except json.JSONDecodeError: pass lines [line.strip() for line in text.splitlines() if line.strip()] if len(lines) 2 and any(, in line or \t in line for line in lines[:2]): delimiter , if , in lines[0] else \t return [line.split(delimiter) for line in lines] return None def to_markdown_table(data): 将二维数组或对象列表转换为Markdown表格 if not data: return _无有效数据_ if all(isinstance(row, dict) for row in data): headers list(data[0].keys()) rows [[str(row.get(h, )) for h in headers] for row in data] else: headers data[0] rows [row for row in data[1:]] header_line | | .join(headers) | sep_line | | .join([---] * len(headers)) | body_lines [| | .join(row) | for row in rows] return \n.join([header_line, sep_line] body_lines) if __name__ __main__: if len(sys.argv) 2: print(使用方式: python build_report.py 数据文件路径, filesys.stderr) sys.exit(1) input_file Path(sys.argv[1]) if not input_file.exists(): print(f错误: 文件 {input_file} 不存在, filesys.stderr) sys.exit(1) content input_file.read_text(encodingutf-8) table_data extract_table_data(content) table to_markdown_table(table_data) print(table)这个脚本虽然简单但有两个设计点非常重要。第一它支持两种输入格式JSON数组和逗号/制表符分隔的文本这样模型从各种途径拿到的数据都能处理不需要严格指定格式第二脚本只做“数据转表格”这一件事不做语义理解语义理解交给大模型这样职责划分清晰脚本出错的可能性也大幅下降。3.3 命令行接口与参数设计细节在skill的脚本设计里命令行接口和参数怎么定直接关系到Agent能不能正确调用。我在调试时发现很多刚写skill的人容易忽视一个问题模型并不知道你的脚本内部是怎么实现的它只能靠你写在SKILL.md里的“工具使用说明”来判断怎么调。所以你在SKILL.md里写工具说明时要把以下信息写清楚脚本的调用方式比如python scripts/build_report.py data_file每个参数的含义data_file到底传什么是路径还是内容脚本可能出现的典型错误以及模型应该怎么应对脚本输出是什么样的模型应该怎么处理输出。我建议把工具说明写成“如果……那么……”的句式可以极大降低模型的误用概率。比如## 工具使用说明 - 如果用户提供的素材中包含数据列表、表格、统计数字将数据内容保存为temp.json然后运行 python scripts/build_report.py temp.json - 脚本会打印一段Markdown表格代码直接粘贴到报告中 - 如果脚本报错“文件不存在”检查用户原素材中是否有附件路径必要时将附件内容手动保存后再调用这种if-then式的描述对模型的指令遵循度提升非常明显。早期我用的工具说明写得太随意模型经常忘掉传参数或者把整个文件内容都塞进命令行后来改成这种结构化描述误用率就大幅下降了。3.4 我的第一版SKILL.md踩坑记录写完第一版SKILL.md我直接在终端里跑了一次测试结果不太理想但也非常有收获。我把当时的失败案例原样复盘一下。第一次测试我输入了一段模拟的会议记录项目进展会 - 2025.06.05 参会人张三、李四、王五 讨论内容 - 新版App开发进度落后两周原因是后端接口延迟 - 用户反馈首页加载速度慢平均加载时长从1.2秒恶化到2.8秒 - 市场部提出需要在下月初前上线新版 - 结论后端加班赶工前端预留缓存优化时间。我以为模型会直接输出一份完整报告结果它确实按模板写了但出现了两个问题一是把“1.2秒”和“2.8秒”这两个关键数字直接写在了正文段落里而不是像我要求的那样转成表格二是它擅自加了一句“这是一个高效务实的会议体现了团队协作精神”这种话放进正式报告里完全就是废话。这两个问题暴露了同一个根源我在SKILL.md里写了“如果素材中包含连续数据使用脚本生成表格”但模型对“连续数据”的理解和我不一样。它认为两个时间点不算连续数据不值得表格化。后来我把这句话改成了“如果素材中出现2组以上同类指标对比如性能数据、销售数字、时间节点必须使用脚本生成表格”同时加了一条“严禁在报告中添加任何评价性、情绪化表述只保留事实信息”第二版测试效果就好多了。这个坑让我深刻理解了一件事skill的本质是“有限状态下的标准化执行”所以描述越精确、边界越清楚、例外情况越明确输出质量就越稳定。不要指望模型“理解你的言外之意”它是很笨的执行者你要把规则写到白纸黑字上。4. 调试、发布与安装从本地到GitHub4.1 本地调试与验证创建skill之后必须做本地调试再发布否则漏洞会被成倍放大到使用者的环境中。我的调试策略分三步走第一步单测脚本。先把build_report.py单独测一遍用几种不同格式的数据跑确保转表格功能没问题。这个阶段不涉及模型只要输出正确就算过。第二步模拟Agent调用。在终端里手动模拟Agent可能会执行的命令复制到真实的终端里去跑。这一步能验证你的“工具使用说明”是不是准确如果自己照着说明都跑不通模型更不可能跑通。第三步端到端测试。把skill装进Agent客户端输入真实的用户请求观察整个执行链路。这一步最容易发现“模型不按套路调用脚本”“模型输出格式偏移”等问题。我在端到端测试阶段发现了一个很有意思的问题Agent有时候会“自作聪明”地跳过脚本直接把原始数字写进表格。原因在于很多模型本身就具备生成Markdown表格的能力它觉得自己能做就不需要调用脚本。解决方法是把SKILL.md里的表述改得更强制、更“行政化”比如“必须运行脚本生成表格不允许手写表格代码”并且单独设置一条规则“如果你的输出表格不是由脚本生成的这次任务判为失败”。这种强约束在多数模型上都能生效。4.2 发布到GitHub与README规范本地测试通过后就可以考虑把skill项目发布到GitHub上了。目前社区里主流的skill分发渠道就是GitHub仓库你的项目结构会直接影响别人是否方便安装和使用。一个规范的skill仓库除了SKILL.md和scripts目录还应该包含一个README.md用来帮助其他使用者快速了解项目。我建议README里写清楚这几块内容技能名称和一句话简介安装方法如何把skill安装到Codex、opencode或其他Agent中使用示例输入和输出的示例让用户一目了然依赖要求需要哪些运行环境License开源协议建议直接MIT。在命名上仓库名建议直接使用skill名格式通常是小写字母加连字符比如markdown-report-skill。这样社区用户在GitHub上搜索时能直接找到。4.3 跨工具安装从Codex到opencode再到自建Agent不同的Agent客户端skill的安装位置和加载方式略有差别但总体思路是一致的把技能仓库克隆到客户端的skills目录下然后重启或刷新即可。我自己测试过Codex CLI和opencode也研究过Spring AI的skill加载机制大同小异。以Codex CLI为例典型的安装方式是把技能仓库放到~/.codex/skills/目录下git clone https://github.com/yourname/markdown-report-skill.git mkdir -p ~/.codex/skills cp -r markdown-report-skill ~/.codex/skills/opencode类似只是目录换成了~/.opencode/skills/。如果你用的是Spring AI做自建Agent就稍微复杂一点一般需要把skill作为资源文件放到classpath下或者实现一个加载器从指定路径读取skills目录。Spring AI的skill机制更偏编写技能描述注册工具的方式核心是一样的但接入成本更高适合有Java开发能力的团队。5. 常见问题与排查技巧实录5.1 我的高频问题速查表现象可能原因解决方案Agent从未触发skilldescription写得太模糊模型判断不出适用场景重写description加入触发关键词和使用场景触发skill但输出格式混乱SKILL.md的“输出格式”段落描述不够具体给出一份完整的输出样例让模型模仿而不是自行理解模型不调用辅助脚本工具使用说明写得太弱模型觉得可以直接生成在SKILL.md中加“必须调用脚本否则任务失败”的强约束脚本执行报错路径、依赖或Python版本问题先在终端手动运行脚本排除环境问题skill在别人的机器上无法使用依赖项未声明或硬编码了本地路径使用相对路径写requirements.txt声明依赖技能在复杂任务上输出平庸SKILL.md缺少参考文档模型缺少领域背景增加reference目录写入模板、术语表、案例5.2 排查思路与心得分享这些坑我基本都踩过一遍。最想多说一句的是第一个问题Agent不触发skill。这个问题非常隐蔽因为从用户视角看你告诉AI去做某件事它“正常”地回答了你虽然它没有用上你的技能。新手会以为AI没明白实际上问题的根源往往在description写得不够具体。我做一个统计报告skill时最初description写的是“帮助用户模拟统计分析输出结果”这个描述很泛模型可能用它来做所有统计分析任务但它又不像一个“专属技能”导致系统觉得直接回答就够了。后来我改成了“当用户需要快速生成统计结果图表或回归分析报告时使用本技能输入原始数据输出分析结果”加上了明确的条件和动作触发率就高多了。关于引用文件路径还有一句额外提醒在skill里尽量用相对路径。比如reference目录里的模板引用时写reference/report_template.md不要写/Users/你的名字/skills/markdown-report-skill/reference/report_template.md。因为一旦你发布到GitHub别人下载后的绝对路径完全不同硬编码路径会让整个技能变成废代码。5.3 关于“skill生态”的一点观察最后聊一下skill生态的现状。GitHub上现在已经有很多现成的skill技能库从写论文、做数学建模到软件测试、硬件设计比如Allegro、嘉立创相关的skill覆盖领域很广。有一些skill库已经做得很规范很值得参考学习我自己的几个技能就是在研究了这些开源项目之后才逐渐打磨出来的。观察这些优秀的开源skill项目我发现它们有几个共同特征SKILL.md结构清晰、步骤拆解细致、工具说明明确、常常带reference提供领域知识并且都提供了真实可运行的示例。反过来那些只是把一段长prompt改名为SKILL.md的项目基本都没什么人用。这个对比恰好印证了skill的本质——它是工程化的AI任务解决方案而不是一段华丽但空泛的提示词。在我自己这几个月的实践中最大的感受是skill开发的真正难点不在技术而在“把任务流程想清楚”。一旦你能把一件事拆成明确的步骤、边界、异常处理和输出标准写SKILL.md的时候自然文思泉涌。我觉得这也是skill最有魅力的地方——它逼着你去结构化思考你以为自己懂的事真正拆解之后才发现有很多模糊地带没想明白而把模糊变成清晰正是从0到1开发一个skill的最大价值所在。