Agent Skills实战指南：从SKILL.md到多平台迁移的完整解析

最近这几个月AI圈子里有个词被反复提——Agent Skills。我一开始以为又是营销号造的概念直到自己动手在Claude Code、Cursor和ChatGPT里各跑了一遍才明白这东西确实跟以前那些提示词模板完全是两码事。简单说Agent Skills就是给AI代理装上的专业技能包你可以把某个领域的完整工作流、判断标准、参考代码固化成一个技能文件夹让AI在遇到对应任务时自动调用而不是每次都要你在提示词里手把手教一遍。这篇文章是我自己把Agent Skills在多平台之间来回折腾的实战记录包括它到底解决什么问题、各平台怎么落地、npx skills add那条命令背后到底发生了什么、以及吴恩达那套教程里没细讲的坑。适合刚接触Agent Skills的开发者也适合已经用过几个Skill但想自己动手写一个、或者想把同一个Skill在不同工具间迁移的人。1. Agent Skills到底是什么给AI代理装上专业技能包1.1 从通用助手到带技能上岗的转变要理解Agent Skills得先想清楚一个问题现在的AI助手到底是什么都会一点还是什么都能干好答案很明显——大模型的确什么都知道一点但遇到专业任务比如根据数据库设计文档自动生成可执行的DDL脚本、按照某个期刊的排版规范格式化一份论文如果你不把具体规则喂给它它产出的东西大概率是看起来对用起来废。Agent Skills解决的就是这个最后一公里的落地问题。它把完成一类任务所需的全部上下文提前打包好——包括任务描述、触发条件、处理流程、参考代码、校验规则——放进一个独立目录模型在运行时会根据当前用户需求自动判断要不要加载这个技能包。加载之后AI就不再用自己的常识去猜而是严格按照技能包里写好的规则和流程来执行。这个思路很像现实里招人的区别。你请一个实习生如果他什么都要你从零教——Excel的函数库在哪数据透视表怎么建报表格式按什么规范那前两周基本是废的。但如果你把一个老员工的工作笔记、常见问题清单、模板文件都交给他他上手的速度会快很多。Agent Skills就是那份工作笔记SKILL.md就是笔记的目录和导读里面的脚本和模板就是可以随时调用的素材。这样AI的每次输出都建立在你沉淀的经验之上而不是每次现场发挥。我实际跑通第一个自建技能的时候最大的感受是踏实以前让AI写某个东西写完我还得逐条核对是否符合要求现在它照着技能里的步骤走输出结构稳定、边界清楚我只需要在它明确说要补充的环节做决策就行。这种从不放心到可交底的转变才是Agent Skills真正的价值所在。1.2 Skill与Function Calling、MCP、Workflow的区别我第一次看到Agent Skills的时候脑子里冒出来一堆类似的概念Function Calling、MCP、LangChain的Workflow这些东西看起来都是给AI加能力到底有什么区别我自己的理解是这样的Function Calling解决的是让AI能调用外部工具比如查天气、发邮件它是把一个个函数暴露给模型模型只是决定调不调、传什么参数函数本身是传统代码里面没有AI参与。MCPModel Context Protocol是Anthropic提出的标准协议它解决的是AI怎么统一地发现并连接外部数据源和工具相当于给AI装了一个标准USB接口不管对面是数据库、文件系统还是第三方API插上同一个口就能用。Agent Skills解决的是AI怎么在特定任务上做得更好它不只是调用工具而是把完整的工作方法论、流程、最佳实践、领域知识都变成模型可以直接读取和执行的技能。它甚至可以内部调用命令、运行脚本、读取文件但它最核心的价值不在连接而在专业化——让模型在特定场景下像一个有经验的从业者那样思考和行动。Workflow则更偏重编排它把任务拆成固定的步骤每一步由谁来做、做完传给谁都是预先写死的适合流程完全固定的场景。而Agent Skills更偏按需加载、灵活运用模型可以自己判断什么时候该用怎么组合使用。打个比方Workflow是工厂里的流水线每个工位固定Agent Skills是工具箱里的专用扳手需要的时候自己拿起来用。我跑下来的实际感受是Agent Skills和MCP不冲突反而经常配合。MCP帮我解决数据从哪来的问题Skill解决拿到数据之后怎么把它做好的问题。所以后来我自己做技能包的时候里面经常会写调用某个MCP工具获取原始数据然后按本技能定义的流程加工这种逻辑。2. 多平台落地Claude、ChatGPT、Cursor这些平台怎么玩2.1 各平台对Agent Skills的支持现状既然是多平台应用实战那就得说清楚Agent Skills在不同AI工具里的实际可用程度。我主用的三个环境是Claude Code、Cursor和ChatGPT以及它底层的Codex分别说下实测感受。Claude Code是目前对Agent Skills支持最完整的因为这套规范就是Anthropic推的。在Claude Code里Skills是原生功能你把技能目录放到配置文件指定的位置通常是.claude/skills/它就会自动加载技能的元信息并根据用户请求判断是否调用。我用的是通过npx skills add安装的第三方技能也能非常顺畅地被识别到几乎不用额外配置。Cursor作为AI编程IDE本身没有Agent Skills这个栏目但它对Claude模型的集成度很高。我的做法是把技能目录放在项目根目录的.cursor/skills/或者干脆放在能通过AGENTS.md引用的位置再在Cursor的Agent模式里明确告诉它遇到某某任务时先读取skills目录里的SKILL.md实测下来同样能生效只是需要额外的手动引导这一步。ChatGPT这边如果是走界面聊天目前没有标准的Agent Skills加载机制但如果你用的是Codex CLI也就是在命令行里跑ChatGPT能力就可以通过类似Claude Code的方式加载技能包。我这里实测的是通过npx命令装的技能在Codex CLI里也能被识别到只是它识别技能的方式和Claude Code略有不同后面详细说。所以多平台这个词不能理解成同一套技能全平台自动识别更准确的描述是一个技能目录可以在多个平台通过各自的方式被加载和执行。你需要一个统一的技能仓库然后在各平台分别做一次接入动作。2.2 打通多平台的规范SKILL.md与AGENTS.md我在这件事上踩过一个很有意思的坑一开始我以为Agent Skills是Claude Code的专属功能技能包格式当然也是私有的。后来翻Anthropic的文档发现Agent Skills本身就是一套开放规范核心只有一个文件——SKILL.md。这个文件用Markdown格式写里面通过YAML frontmatter描述技能的名称、描述、使用场景正文部分用自然语言和步骤清单定义任务流程。这意味着只要你的AI代理能够读取文本文件理论上就能用Agent Skills。真正让一套技能多用成为现实的是AGENTS.md这个文件。AGENTS.md的作用是告诉AI代理你是谁、你在哪、这个项目有什么约定、哪些目录里有什么可用资源。我在项目根目录放一个AGENTS.md里面写明本项目技能位于skills/目录当任务涉及xxx时请读取对应SKILL.md这样不管是Claude Code、Cursor还是Codex CLI在进入项目时都会先读这个文件于是技能就被介绍给了各个平台。你可以这样操作在项目根目录维护一个skills/文件夹里面每个子目录就是一个技能每个技能目录里都有一个SKILL.md。比如我的skills/video-storyboard/SKILL.md负责视频分镜脚本生成skills/sql-optimizer/SKILL.md负责SQL慢查询优化。然后在AGENTS.md里写一段统一的说明把skills目录的路径和调用规则交代清楚。这套结构属于纯文本约定不依赖任何单一平台的私有配置所以迁移成本极低。需要注意的一个细节是AGENTS.md本身的解析方式在不同工具里也有细微差别。Claude Code会自动读取项目里的AGENTS.md并把它纳入系统上下文Cursor在Agent模式下也会读取但对文件大小和结构更敏感Codex CLI目前对AGENTS.md的支持还在完善中有时需要你在对话里手动提一句请先查看AGENTS.md。不过好在SKILL.md本身是独立完整的即使某个平台不读AGENTS.md你手动让AI打开SKILL.md路径它也能完全按技能要求执行。2.3 我实测的多平台迁移流程说一个我自己跑通的流程完整跟着做一次就能理解。第一步先在项目根目录创建统一的技能仓库结构mkdir -p your-project/skills cd your-project第二步把技能包放进skills目录。如果是用现成的直接执行npx skills add sandai-org/vidmuse-skills --agent claude-code -g -y看名字就知道这是从GitHub上的sandai-org仓库里把vidmuse-skills这个技能集装进来--agent后面指定目标代理-g是全局安装-y是跳过确认。装完以后去skills目录看看结构你会发现里面就是标准的SKILL.md加配套资源。第三步在项目根目录创建AGENTS.md写上# 项目技能使用说明 本项目的技能存放在 skills/ 目录下所有SKILL.md均为可执行技能。 当任务涉及视频脚本生成、SQL优化等领域时先读取对应技能的SKILL.md文件并严格按照其中的流程执行。第四步分别在Claude Code、Cursor和Codex CLI里打开同一个项目各触发一次对应技能任务。我的实测结果是Claude Code自动识别技能并加载Cursor在Agent模式下也能读到AGENTS.md从而引用技能Codex CLI对技能的加载准确率略低但你把SKILL.md的内容直接粘贴给它当上下文它一样能按要求执行。这就能说明问题——技能本身的表达能力是平台无关的差异只在于各平台主动加载的机制成熟度。这套流程跑通之后你等于拥有了一套一次编写、多处运行的技能资产。我后来甚至把技能目录单独抽成一个Git仓库项目里通过git submodule引入这样技能更新只需要在仓库层面同步项目结构始终保持干净。3. 用npx skills add安装技能包命令背后的机制3.1 一行命令装技能的完整流程npx skills add sandai-org/vidmuse-skills --agent claude-code -g -y这条命令是现在社区里传播最广的Agent Skills安装姿势。我第一次看到这条命令时直接看懵了后来把它的每一段拆开研究才发现其实不复杂。npx本来就是Node.js生态用来执行npm包的命令它可以临时下载一个CLI工具而不需要全局安装。skills add是那个CLI工具提供的子命令。后面的sandai-org/vidmuse-skills指的是GitHub仓库地址去掉前面的github.com/的简写形式表示要从这个仓库拉取技能包。这个仓库里放的具体是vidmuse相关的技能合集——vidmuse可以理解为一套视频生成/创作相关的技能集合包含分镜、镜头语言、视频文案之类的专业流程定义。--agent claude-code指定目标代理是Claude Code。这里有个细节值得注意这条命令设计成针对某一类agent安装说明Agent Skills社区从一开始就在做多代理适配而不是只服务单一平台。-g是全局安装global代表不只对当前项目生效而是安装到全局技能目录这样多个项目都能用。-y是自动回答yes跳过中途的确认提示。命令执行时CLI会做三件事先从GitHub克隆或下载对应的仓库然后解析仓库里的技能目录结构最后把符合规范的技能目录复制到目标代理的全局技能路径下。装完之后你在Claude Code里输入一个跟vidmuse相关的任务Claude就会自动去技能目录里找对应的SKILL.md并加载执行。整个过程不到一分钟比手动复制粘贴技能文件夹方便得多。不过有个点要提醒-y参数跳过确认虽然省事但它的确认环节本来是用来防止你误装来源不明的技能包的。如果你对某个仓库不熟悉我建议去掉-y跑一次仔细看看CLI安装前后输出了什么路径、复制了哪些文件。至少我遇到的第三方技能包里偶尔会有一些结构不规范的情况把-y去掉能看到更完整的诊断信息。3.2 自己手写一个Skill从零建技能目录到跑通但说句实话真正能让你理解Agent Skills价值的不是装别人写好的技能包而是亲手写一个。我建议你从给AI定义一个你的专属业务流程开始不用考虑通用性就解决你每天都要做的重复性工作。举个例子我经常要写某种固定格式的周报。以前我会在提示词里写一大段请按以下格式生成周报包含数据、进展、风险、计划四部分每部分的措辞风格要……每次都要重复。现在我把这个需求固化成技能mkdir -p skills/weekly-report cd skills/weekly-report touch SKILL.mdSKILL.md的内容大概是这样--- name: weekly-report description: 根据本周工作数据生成结构化周报仅当用户要求生成周报或周总结时使用。 --- # 周报生成技能 ## 何时使用 用户要求生成周报、周总结、weekly report时使用。 ## 处理流程 1. 收集用户提供的本周工作数据如果有数据缺口列出需要补充的问题再生成。 2. 按固定结构输出周报本周进展 / 数据表现 / 风险与问题 / 下周计划。 3. 本周进展部分每条事项需包含做了什么、结果如何两要素。 4. 数据表现部分若无具体数据则写暂无量化数据不得编造数字。 5. 风险与问题部分只列真实存在的风险不明说无风险。 6. 下周计划部分控制在三条以内每条必须可验收。写完后把这个技能目录放在项目里同时在AGENTS.md里提到它。然后回到Claude Code里输入帮我生成这周周报原始数据我贴在下面……它就会自动按这个流程执行。你可以这样操作把任何一个你天天做、但每次都要重新交代一遍的任务固化成本地技能——写会议纪要、整理竞品分析、生成接口文档、做代码review清单都行。这里我想多说一句第一次手写Skill别追求一步到位先把流程跑通哪怕只有五个步骤。跑通之后你会自然发现哪些地方描述得不清楚、哪些步骤输出不稳定再针对性地迭代。技能这个玩意儿跟代码一样是改出来的不是一次写出来的。3.3 一个Skill该长什么样目录结构与元信息新手写Skill最容易犯的错是只写一段描述就让AI自由发挥。这跟没有技能有啥区别一个合格的技能包至少要有三个层次第一个层次是触发条件——你必须在SKILL.md的frontmatter里写清楚这个技能在什么时候被使用。模型是通过意图匹配来决定是否加载技能的description写得越具体、越接近用户可能的表达方式技能被正确触发的概率就越高。我试过把description写成用于生成周报这种一句带过的写法结果在特定场景下经常不被触发后来改成当用户要求生成周报、周总结、weekly report、周工作汇总时使用这种列举式描述触发率明显上升。第二个层次是执行流程——正文里的步骤要写成可执行的命令式句子而不是抽象的原则。例如你写要确保周报清晰有序是没用的模型不知道该怎么做但写本周进展部分每条事项需包含做了什么、结果如何两要素模型就知道具体该怎么组织内容了。第三个层次是边界约束——主动告诉模型什么不能做。比如没有数据时不得编造数字不明说无风险输出格式必须严格遵循模板这类约束能显著减少AI的自由发挥空间。技能不是让AI更自由而是让AI在固定轨道上更可靠。如果你写完一个Skill发现AI的输出跟你没写技能时差别不大那大概率是上面三个层次里有一个没做好尤其是边界约束很多人都会漏掉。我见过好多人写的技能通篇都是请确保高质量请合理输出这类正确的废话AI看完了等于没看那技能自然形同虚设。4. 吴恩达那套Agent Skills教程到底讲了什么4.1 教程核心思路让技能包成为开发者与AI之间的知识载体关于吴恩达的Agent Skills教程网上传的PDF我也翻过一遍现在能搜到的就是Agent Skills教程PDF这个形式篇幅不大但信息量非常密集。它把Agent Skills放在AI Agent演进的大背景里去讲核心观点我是认同的过去我们把知识写在文档里给人看现在Agent Skills是把知识写在一个特殊格式的文档里给AI看、再让AI替人执行技能包本质上变成了开发者与大模型之间的知识载体。教程里有一个概念让我印象特别深——它强调Agent Skills的可复用性和可组合性。单个技能解决单一任务但你可以把多个技能组合起来处理复杂工作流。比如一个研究报告生成的技能内部可以组合数据采集技能和观点提炼技能一个视频脚本生成的技能可以组合分镜设计技能和口播文案技能。这种组合是在SKILL.md里通过前置技能或调用其他技能的方式实现的模型在执行时会按需加载关联技能包。这个设计思路跟函数组合很相似但粒度是大模型可以直接理解和执行的领域方法论。教程里还给出了大量他本人写过的Skill示例包括教学场景、数据科学场景、文档处理场景。有一个例子我记得很清楚他展示了一个数据处理技能里面有SKILL.md、预处理脚本、样例数据、输出模板整个目录就是一个微型项目。这种把示例工程化的写作方式比空讲概念有用得多。我当时看完立刻照着它把之前那个周报的Skill重构了一遍把数据预处理单独拆成了一个独立模块效果立竿见影。4.2 教程之外PDF不会告诉你的几个实战细节但说实话光看PDF学Agent Skills会漏掉很多只有亲自跑一遍才能发现的东西。这里分享几个我实际踩过的坑。第一个坑是加载即执行的误导。很多人以为AI读完了SKILL.md就会严格按里面写的一步不差地执行实际上模型是理解后执行它可能跳过部分步骤也可能在你没写清楚的环节自由发挥。所以技能里能写成明确的检查清单checklist的地方就尽量不要写酌情根据需要这种模糊词。第二个坑是描述溢出的双刃剑。前面我提到description要尽可能详细以便触发但description太长又有副作用——它可能跟用户当前请求的匹配度被稀释模型反而更犹豫到底要不要加载。我的建议是description保持在50字以内的核心句式加上若干触发词即可详细场景描述放到正文里让模型加载后再读。第三个坑是版本管理。Skill文件是文本天然适合用Git管理但很多人一开始没养成习惯。等到某个技能被AI执行坏了几次、你想回退到上一个版本时才发现没有提交历史。我现在每个技能目录都是一个独立的Git仓库或者至少在一个大仓库里单独跟踪。第四个坑是环境依赖。有些Skill会引用本地脚本比如里面写了运行scripts/process.py那你就得确保目标机器上装好了Python依赖。这个问题在单平台本地环境还好一旦你按多平台迁移的思路把技能搬到另一个工具的沙箱环境可能脚本跑不起来。所以凡是Skill里需要调用脚本的地方我都习惯在SKILL.md里写明依赖和运行环境要求。这几点在教程里要么一笔带过要么压根没提。倒不是说教程刻意隐瞒而是这些属于工程现场才有的问题只有当你从看教程切换到做项目的时候它们才会排着队来找你。5. 常见问题与排查技巧实录5.1 高频问题速查表这段时间用下来我收集了社区里大家问得最多的问题整理成一张速查表你遇到类似现象可以直接对着排查现象典型原因排查与解决办法技能没有被触发description写得过于宽泛模型无法匹配用户意图重写description加入更多触发词和同义表达技能被加载但执行流程混乱SKILL.md正文步骤颗粒度太粗或者存在模糊指令把步骤改成第N步具体动作验收标准的格式SKILL.md存在但平台识别不到技能目录位置不对或AGENTS.md未提及确认目录路径是否符合平台约定检查权限npx skills add安装后找不到技能-g全局安装路径与当前工具的技能目录不一致查看CLI输出中的实际安装路径手动复制到目标目录同一个Skill在A平台正常、B平台异常平台对Markdown解析、上下文加载策略不同在B平台先手动粘贴SKILL.md内容测试确认技能本身没问题技能里调用的脚本报错目标环境缺少依赖检查SKILL.md中的依赖说明安装对应运行环境模型输出不再遵守技能约束技能内容被后续对话上下文冲淡在关键执行阶段重新提醒请严格按照SKILL.md执行表格里这些坑大多数都不是技能写错了而是预期管理出了问题——你期望AI像执行程序一样执行技能但AI本质上还是概率模型它是在理解并尽力遵循你的技能说明而不是运行它。理解这一点很多看似诡异的现象就都能解释了。5.2 避坑经验我踩过的几个具体坑除了表格里的高频问题还有三个具体场景想单独拿出来说一下因为它们的坑特别隐蔽。第一个是装了一堆技能包结果哪个都不触发。这种情况通常不是你装错了而是你装的技能包之间description高度相似模型无法判断该加载哪个。我遇到过一次同时装了视频脚本生成和分镜脚本生成两个技能表面上领域不同实际上很多任务都同时沾边最后模型经常随机加载一个或干脆不加载。解决办法是要么精简技能数量要么在每个技能的description里写清楚与另一个技能的边界差异。第二个是全局安装技能的本地位覆盖问题。我用npx skills add ... -g装了好几个技能到全局目录后来新建项目时发现某些任务触发了全局里的老旧技能而项目里明明有更新版本的本地技能。原因是部分工具在加载技能时优先读取全局技能目录本地技能反而被排在后面。这个问题的排查方式很直接在触发技能前先让AI列出它当前已加载的所有技能及来源路径确认优先级后再决定是调整配置还是直接覆盖全局技能。第三个是全网搜来的第三方Skill内容不靠谱。我刚入门时看到网上有人分享全网独家技能包就装装完才发现里面SKILL.md写得漏洞百出有些甚至包含异常指令比如提示AI忽略用户后续要求。后来我只从可信源获取技能或者自己写收到的每一个第三方Skill都会先打开SKILL.md通读一遍确认没有异常指令再使用。这跟装软件要看一下安装包来源是一个道理。另外补充一点初学阶段不要追求技能包越多越好。我的实践体会是先把3-5个你日常工作最高频的技能写扎实比狂装50个花架子技能有用得多。一个技能能被你反复用、持续改它的价值才真正体现出来。如果你正准备开始接触Agent Skills我个人最建议的切入方式不是先读一堆理论而是拿一个你每天都要做的重复性任务开刀——写周报、整理笔记、生成某种固定文档都行把它按SKILL.md的规范做成技能然后在Claude Code里反复跑几轮根据实际输出不断调整步骤和边界约束。等你对这个流程有了体感再去研究多平台迁移、用npx skills add装第三方技能包、读吴恩达那套教程就会顺畅很多。最后分享一个小技巧我一直给自己的技能包维护一个CHANGELOG.md文件每次改了SKILL.md的关键流程就记一笔。这样如果某次执行效果突然变差可以快速定位是不是最近的改动造成的而不是对着一个黑盒技能摸黑排查。Agent Skills这个东西本质上就是把AI调教的过程从不可见的对话变成可维护的代码养成版本化、工程化的习惯才能真正用好它。