1. Agent Skills 到底是什么最近为什么到处都在聊先说结论Agent Skills 是 2025 年以来 AI Agent 方向里回报率最高的一个玩法。吴恩达专门写了一篇教程核心观点非常简单——与其反复调 prompt 让大模型“猜着干活”不如直接给它一套带说明文档的“技能包”让它看到任务就自动调用对应的那套流程。这个思路很快被 Claude Code、Cursor、OpenAI、国内各家大模型平台跟进现在基本上成了智能体落地的默认姿势。很多人第一次接触这个概念是在某个视频教程里看到一条命令npx skills add sandai-org/vidmuse-skills --agent claude-code -g -y。看起来就是在终端里“装了一个包”但背后其实完成了一次完整的技能分发从 GitHub 拉取技能包、识别当前使用的 Agent 平台、把技能文件放到全局目录、然后让 Claude Code 在运行时自动加载。这条命令跑完你的 AI 就不再是“有问必答”而是变成了“带工具箱干活”。那 Agent Skills 和普通的系统提示词、或者 MCP 有什么区别我个人的理解是它更像是“给 AI 的一本岗位手册 对应工具集合”。普通 prompt 是口头交代MCP 是外接的双手而 Skills 是两者之间的桥梁——它告诉模型在什么场景下、按什么步骤、调用什么函数、输出什么格式。这套机制最大的好处是模型不需要“想”怎么干活它只需要“照着做”。这个方向适合谁如果你是做 AI 应用开发的或者日常重度使用 Claude Code、Cursor 这类工具的非常值得把技能包的机制吃透。哪怕你不写代码只希望 AI 帮你画图、做视频、整理 Excel一套好的技能包就能让结果从“能看”变成“能用”。我下面写的内容都是我在多平台实际跑过之后总结下来的不绕弯子直接讲怎么用、怎么改、怎么排坑。2. 技能包机制的核心逻辑为什么“教它干活”比“让它猜”更靠谱2.1 一套 Skill 包的标准组成我拆过不少开源技能包也自己封装过好几个发现不管哪个平台技能包的内部结构基本都长一个样。一个合格的 Agent Skill 目录通常包含三块东西SKILL.md这是整个技能包的中枢用 Markdown 写的说明文档描述了该技能“什么时候用、怎么用、注意什么”。scripts/或src/放实际的执行脚本模型决定调用后就去执行这里面的程序。YAML frontmatter位于SKILL.md头部用---包裹声明技能的name、description等元信息。举一个具体的例子。比如你手头有一个vidmuse-skills包从名字看就知道是一个和视频创作/视频理解相关的技能集合。它的SKILL.md里大概率会写清楚当用户提出“帮我把这段文案转成短视频脚本”时你应该先加载哪段“镜头拆分模板”再调用哪个脚本去生成时间轴最后按照什么格式输出分镜表。这一整套“流程说明 可执行文件”的组合就是技能包的本质。YAML 部分非常关键我见过不少技能包不被加载就是 frontmatter 写错了字段模型根本不知道这个技能是干嘛的。以 Claude 系为例一个规范的 frontmatter 长这样--- name: vidmuse-create description: 当用户需要将文案、图片素材或灵感转换为短视频分镜脚本时使用。支持时长设置、镜头拆分、旁白生成。 ---description字段不能写得太含糊。模型在对话中判断“该不该调用技能”主要就是靠这个字段与用户请求做语义匹配。你写“视频脚本工具”模型匹配率就很低你写“当用户需要将文案转换为短视频分镜脚本时使用”匹配率立刻就上来了。2.2 它是怎么被模型发现并调用的理解了这个再看调用链路就很清晰了。模型每收到一轮对话都会在思考过程中“扫一遍”所有可用的技能描述找到匹配度最高的那个技能包读取对应的SKILL.md然后按照文档里的步骤执行。这个过程和人类新入职看 SOP 干活几乎一模一样。值得注意的是Agent Skills 的“技能”不一定每次都必须被调用。它更像是一个路由器模型判断命中才使用判断不命中就当普通对话处理。这个设计非常重要否则每个技能包都会抢着响应对话体验会变得异常混乱。那和 MCP 有什么区别呢我打个比方MCP 相当于给 AI 装了“手”——可以读取数据库、操作浏览器、调用 API而 Skills 相当于给它装了一本“作业指导书 配套习题答案”——不只告诉它能干什么还告诉它解决问题的标准路径。所以实际使用中往往两者搭配MCP 负责抓数据Skills 负责把数据加工成成品。2.3 为什么吴恩达一出来讲整个行业都跟着做吴恩达的 Agent Skills 教程 PDF 在社区传得很广我读完的最大感受是他其实没有发明什么新东西而是把大家一直在零散使用的方法规范化了。在他之前大家是各写各的提示词各种“专家提示词模板”满天飞他的贡献是把“给模型写技能说明”这件事做成了标准结构有元信息、有说明文件、有配套脚本、有分发机制随便换一个平台都能用。这一点非常戳行业痛点。以前大家做 Agent 应用最怕的就是换平台重写逻辑同一个任务在 Claude 上能用到了别的平台又得重新调一遍 prompt。如今技能包做成纯 Markdown 脚本的组合跨平台迁移成本大大降低。这也就是为什么“多平台应用”能成为一个独立的话题——因为 Skills 机制天生就是为了多平台复用而设计的。3. 从一行命令开始把技能包装进你的智能体3.1 拆解npx skills add这条核心命令视频标题里的命令我拆开讲一下很多新手直接复制粘贴跑通了也不知道每个参数在干什么。npx skills add sandai-org/vidmuse-skills --agent claude-code -g -ynpx skills这是社区里常用的skillsCLI 工具通过 npm 分发不需要提前下载安装。add sandai-org/vidmuse-skills指定要从哪个 GitHub 仓库拉取技能包。格式是组织名/仓库名跟npm install的写法很像。--agent claude-code告诉 CLI 你要把技能装到哪个 Agent 平台它会按平台的约定规则写入对应目录。-gglobal的缩写表示全局安装让当前机器的所有项目都能用而不仅限于当前目录。-y自动确认后续的提示跳过交互式提问方便脚本化执行。从实际经验看-g这个参数建议一直带着。如果不加技能只装到当前项目的.agents/skills目录换个项目就没了加了之后技能会被放到系统级的全局目录比如 macOS 上常见的位置是~/.claude/skills或~/.config/skills所有项目都能共享。3.2 安装完成后必须做的三件事命令跑完只是第一步很多人在这一步就以为“装好了”实际还差三步。第一验证技能是否被正确识别。如果你用的是 Claude Code在对话里直接输入/skills或者/agents就能看到当前可用的技能列表。如果列表里出现了你刚才安装的vidmuse-skills说明加载成功。第二确认技能目录结构。进入对应目录看一眼确认SKILL.md和脚本文件都完整存在。有时候网络拉取不完整会导致目录在但文件缺失模型调用时直接报错。第三找一个最小用例测试。比如问你的 Agent“帮我用 vidmuse 生成一个 15 秒的猫猫日常短视频脚本。”如果模型开始按照技能包的分镜格式输出就说明整个链路通了如果它答非所问多半是技能没被加载或者 description 匹配失效。3.3 全局技能目录与项目级技能目录怎么选这里我多说一点很多老手也会在这上面犹豫。技能目录有两种全局和项目级两者并不是二选一的关系而是按场景选择。全局技能目录适合装通用型技能比如“PPT 大纲生成”“Excel 数据清洗”“短视频脚本”因为这类任务不管你开哪个项目都用得上。项目级技能目录适合装和项目强绑定的专属流程。比如你手头在做一个电商数据分析项目就可以把“店铺周报生成”这套技能装到该项目目录下别人 checkout 代码后不需要额外安装技能自动生效。我个人习惯是通用技能走全局专属技能走项目。安装命令上全局就加-g项目级就不加很简单。3.4 一条命令装多个技能包skillsCLI 还支持一次加多个包用空格隔开就行npx skills add sandai-org/vidmuse-skills someuser/slide-skills another/report-skills --agent claude-code -g -y这个功能适合新环境初始化比如换了台新电脑一条命令把常用的技能全都装回来。不过要注意技能包之间可能会存在指令冲突比如两个包都响应“生成报告”模型就不知道该听谁的。所以一次装太多之前最好先逐个验证过再组合使用。4. 多平台应用实战Claude Code、Cursor、ChatGPT 与本地开源方案4.1 Claude CodeAgent Skills 的“原生主场”目前对 Agent Skills 支持最自然的就是 Claude Code。原因很简单这套技能的规范本身就是 Anthropic 在推的官方文档、社区工具链都对齐这个标准。在 Claude Code 里用技能体验是最顺滑的——你安装技能后不只是“能用”而是模型会在对话过程中主动检索技能描述并告诉你“我准备使用 vidmuse-skills 来完成这个任务”。Claude Code 中技能目录的加载优先级需要特别注意。它的查找顺序是项目目录.claude/skills 用户全局目录~/.claude/skills。如果同名的技能在两个目录都存在项目级优先。这个顺序决定了你调试时容易踩坑——改了全局技能包却发现不生效一看项目目录里还有个同名旧版。还有一个很实用的细节Claude Code 会在会话启动时自动索引所有可用技能但如果你在会话中途手动加了新技能并不会立即生效需要重启会话或者运行/agents刷新。我一开始不知道装完技能一整个下午都在问“为什么模型不调用”最后发现只是没有刷新索引。4.2 Cursor把技能包从命令行接到图形界面Cursor 作为 AI 编辑器对 Agent Skills 的支持方式是“对话时自动读取技能说明配合代码生成”。在 Cursor 里配置技能核心操作就是将技能包放到项目根目录的.cursor/skills下。和 Claude Code 不同Cursor 的技能目录更偏项目级全局配置目前还需要通过 Cursor 的settings里的自定义规则来实现。我的做法是在 Cursor 里写代码时调用 Claude Code 中已经验证过的技能包。比如让 AI 帮我生成 Django 视图的增删改查我就会用一个django-crud技能包它会告诉 Cursor 项目的模型命名规范、视图写法、URL 注册规则。实测下来生成的代码风格统一不需要像以前那样反复纠正。有一点提醒Cursor 对技能的自动“调用”不像 Claude Code 那么主动它更倾向于把技能内容当背景知识。所以你在写SKILL.md时最好把适用范围和触发条件写得非常明确不要用模糊词不然模型容易忽略。4.3 ChatGPT 与 OpenAI 系平台另一套标准别照抄如果是 ChatGPT 或者 OpenAI API 系目前的主流路径有两个一是将技能机制放到自定义 GPT 的 instructions 里二是通过file_search或知识检索让它读取技能文档。OpenAI 也在推进自己的 Skills 协议但从我测试的版本看它和 Anthropic 的实现并不完全互通字段名比鲁、加载方式都有差异。如果你是团队协作想统一维护一套技能包我强烈建议按 Claude Code 的标准来编写因为社区生态和 CLI 工具目前最成熟然后在发布到其他平台时写一个“转换器”把 YAML frontmatter 转成 OpenAI 平台要求的 schema。我封装过一次转换脚本大概两百来行 Python就能把 Markdown 技能包自动转换成可导入 OpenAI 的 JSON 配置。这个思路对“多平台”这一步非常关键——没有自动化转换维护两套标准会苦不堪言。# skills_converter.py # 将 Claude 风格的 SKILL.md/YAML 转成 OpenAI 自定义指令格式 import yaml, json, sys def convert(skill_path: str) - str: with open(skill_path, r, encodingutf-8) as f: content f.read() parts content.split(---) if len(parts) 3: raise ValueError(SKILL.md 缺少 YAML frontmatter) meta yaml.safe_load(parts[1]) body ---.join(parts[2:]).strip() instruction fSkill Name: {meta.get(name)}\n instruction fWhen to use: {meta.get(description)}\n instruction fSteps:\n{body}\n return instruction这段小工具的逻辑很简单但足够实用把 frontmatter 里的description转成“When to use”再把正文直接拼接成指令。这样你在团队里只需维护一套 Markdown剩下的转换工作交给脚本。4.4 本地开源方案OpenHands 与 Continue 的接入思路如果你介意云端平台想在本地部署 Agent那么 OpenHands 这类开源项目也支持自定义技能。OpenHands 的技能目录通常放在~/.openhands/skills或项目目录下的openhands/skills机制上和 Claude Code 类似都有一个SKILL.md文件描述触发条件。Continue 则是以 IDE 插件形式存在它的 “Rules” 机制可以直接把技能说明文件路径写进配置效果相当于是“全局背景知识”。在这种架构下技能包更像是“提示词模板库”模型的调用机制并不存在——它只是在生成代码时参考了你提供的规则。所以如果你要在非 Anthropic 系平台上用 Agent Skills核心要调整的不是技能包本身而是“调用方式”。在 Claude Code 里模型会自动判断何时该读取技能包在本地开源方案里很多情况下技能是全量加载的需要考虑上下文开销。一个几万字的SKILL.md全塞进去会影响对话质量需要精简说明。4.5 多平台复用的完整流程参考聊了这么多我把一次完整的跨平台使用流程整理成一张“行动路线图”照着走基本不会出错。在 GitHub 上找到一个满意的技能包仓库。先用 Claude Code 安装、测试确认这个技能包逻辑符合预期。将技能包从全局目录复制到你常驻的项目目录提交到 Git。这样团队其他人拉代码后自带技能。如果需要在 Cursor 里用在项目根目录建.cursor/skills把技能包复制过去同时把SKILL.md里的触发条件写得比 Claude Code 版本更显式。如果需要给 ChatGPT 用用我上面的转换脚本将 Markdown 转成指令文本粘贴到 Custom Instructions 或知识文件里。每次修改主技能包务必同步更新各平台下的副本或者在文档开头标注“本版本最后修改时间”。说实话这个流程第一次走会有点繁琐但一旦跑通后面再添加新技能就非常省事。而且我强烈建议团队内部把技能包当作代码一样管理用 GitHub 仓库来维护不要只躺在某一个人的笔记本里。5. 自己动手封装一个 Skills 包从零到可用的完整过程5.1 设计思路先想清楚“要教会 AI 干一件什么完整的事”自己封装技能包最重要的不是写代码而是想清楚“完整的事”是哪件事。什么叫完整比如“生成短视频脚本”就不够完整“根据用户输入的主题和时长生成包含镜头序号、景别、画面描述、旁白文案、字幕文案的表格并输出为 CSV”才是完整。技能包的价值在于把模糊目标转成明确流程。我一般建议从一个你“已经手工重复做了三遍以上”的事情开始比如你每月都要整理一份数据周报这个流程极其适合固化成一个技能包。因为有真实的工作流可以参照写出来的步骤是验证过的而不是拍脑袋编的。还需要考虑“输入是什么、输出是什么”。一个技能的输入通常是用户对话中的自然语言描述输出则最好是结构化文本或文件。我在设计时会先定义输出格式再倒推操作步骤。比如输出是 CSV 表格那我就倒推先读取数据源→清洗字段→计算指标→拼接模板→输出文件整个链条非常清晰。5.2 编写SKILL.md的规范与技巧SKILL.md是技能包的灵魂我写了几十个之后总结出几个对效果影响巨大的技巧。第一正文开头必须先写“触发场景”而且要用枚举列表列出来不要写成一大段话。例如## 使用场景 - 用户说“帮我做一个短视频脚本” - 用户提供文案并要求生成分镜 - 用户希望批量生成多个视频脚本模型扫描技能时枚举列表比散文更容易命中。你写一百个字描述场景不如直接列出五条典型请求。第二操作步骤中要明确角色分工。有些步骤是模型直接推理完成有些步骤需要调用脚本有些步骤需要生成中间文件应当区分开来。我常用的标记方式[推理]模型根据已有信息分析并输出结果。[工具]调用scripts/下的脚本。[确认]需要用户确认后才能继续。这套标注非常笨但实测下来能让模型的行为稳定很多不然它经常越权执行不该执行的步骤。第三针对容易出错的环节写“易错点”区块。比如视频脚本技能里十个人有九个人分不清“分镜脚本”和“拍摄脚本”的区别那你的SKILL.md就明确写一句“本技能输出的是分镜脚本不包含场地安排和演员调度内容。”这句话能给模型套上缰绳避免生成不相关的信息。5.3 一个真实的技能包封装示例我拿“周报生成器”做一个例子完整展示结构。技能包目录如下weekly-report-skill/ ├── SKILL.md ├── scripts/ │ ├── generate_report.py │ └── templates/ │ └── weekly_report_template.md └── assets/ └── sample_data.csvSKILL.md的内容写清楚当用户说“生成周报”时先用sample_data.csv作为演示数据说明字段含义然后调用generate_report.py对输入数据进行清洗和统计最后把统计结果填入 Markdown 模板生成一份格式统一的周报。generate_report.py的核心逻辑不需要多复杂比如用 pandas 读取 CSV计算本周/上周环比生成图表最后替换模板字符串。关键在于模型只知道“有脚本可以调用”具体脚本内部实现并不关心。这就是 Agent Skills 的理念人类负责写工具模型负责调工具。写完之后记得在 scripts 目录下加一个requirements.txt让模型在缺依赖时知道该装什么。实测下来这一步经常被忽略结果技能包在别人机器上直接用不了非常尴尬。5.4 导入测试与迭代技能包写完第一时间导入 Claude Code 测一轮。测的时候不要直接问“你会用周报技能吗”这种开放式问题没有意义。最好模拟真实任务说“这是一份本周订单数据请帮我生成周报重点对比华东和华南区域的环比变化”。这里有个非常重要的检查点看模型是否主动提到它调用了技能包。如果它只是即兴发挥说明你的技能描述触发不够如果它表示这是“基于内置知识”生成的说明技能包完全没被加载。每次测试后回到description字段微调措辞通常两三轮迭代后效果就会明显改善。另外技能包的迭代也应该版本化。我在SKILL.md里放了一个version字段每次改动递增一位方便回退也方便团队里多人协作时对齐状态。6. 实战中的常见问题与排查技巧实录6.1 技能包“装上了但模型就是不调用”优先级最高这个现象占了日常问题的一大半。表现是你明明装好了技能包目录也在但问任何问题模型都像个没事人一样。排查路径我基本固定排查点操作判断标准技能列表是否可见在 Claude Code 输入/skills列表中没有该技能则加载失败description 是否具体阅读 SKILL.md 头部 YAML是否包含“当用户…时使用”这类触发措辞测试问题是否命中换一个和技能描述强相关的说法如果改问法后能命中说明描述措辞太窄是否在会话前安装重启会话或运行 /agents 刷新索引刷新后技能列表出现说明之前是索引问题全局目录位置是否正确查看skills list的输出确认安装路径对应的是当前 Agent这条路径我从不跳过几乎能定位 90% 的问题。6.2 技能包被加载了但生成结果完全不按说明来这种情况和“完全不调用”正好相反模型确实在用技能包但输出结果看起来像在自由发挥。一般原因有三类。一类是SKILL.md里步骤写得有歧义模型不知道先执行哪一步。解决办法是把步骤改成“必须按顺序执行”的强措辞并把每步的输入输出标注清楚。另一类是脚本本身报错但是模型错误地继续推理了。比如generate_report.py因为缺少 pandas 抛了异常模型不告诉我而是自己“猜”了一个报告出来。这个非常坑。我的解决办法是在脚本里加异常兜底任何异常都输出ERROR: {错误信息}同时让SKILL.md告诉模型“看到 ERROR 必须停止并向用户说明”。第三类是最难查的模型被第二个技能包“带偏”了。如果机器上同时装了“通用写作助手”和“周报生成器”两个包都抢着响应写周报请求输出就很可能夹杂着两种风格。解决办法就是精简技能包数量或在技能包的说明里加上“本技能优先于通用写作类技能处理结构化周报任务”。6.3 跨平台移植后结果大相径庭同一个技能包在 Claude Code 里效果好换到 Cursor 里就变味。这本质上是因为不同平台对技能包的“调用策略”不一样。Claude Code 至少还有一个显式的技能列表入口而 Cursor 完全靠模型自己判断是否读取.cursor/skills下的内容触发概率就低了不少。我的经验是在 Cursor 里使用的技能包需要把description字段写得更偏向“显式指令”比如改成“每次用户要求生成周报时必须读取本文件并按步骤执行”。听起来像在“命令”模型但效果确实比“提示”式描述有效得多。另外在 Cursor 的 Rules 里加一行“项目使用 .cursor/skills 目录下的技能包生成结果前必须参考”也能显著提升调用率。6.4 必加的“安全措施”与通用避坑清单最后分享几个踩过坑后养成的习惯这些不属于官方文档但你可以直接抄。不要直接修改全局技能包的原文件。我先复制到项目目录再改这样即使改坏了也不影响其他项目。另外技能包仓库往往会更新直接改源文件会被 Git 覆盖你的改动全部白费。不要在SKILL.md里贴超长代码。模型读取大段代码会占用大量上下文还容易产生幻觉。正确做法是把代码放到scripts目录SKILL.md里只写调用命令和参数说明。版本号务必写在文件名或 frontmatter 里。我用weekly-report-skill-v2这种命名方式好几个技能包同时存在也不怕模型能根据描述选择最新版。技能包里的提示语一定要是“指令式”不要用“请”字。模型不会因为有礼貌就做得更好清晰、直接、分步骤的指令才是它最需要的。7. 一些值得长期跟踪的方向关于 Agent Skills还有一个很值得玩味的点它把“知识”和“执行”拆开了。以前你给模型一个 prompt它记住了“知识”但不会执行现在你用技能包把“知识”固定下来把“执行”交给脚本模型只负责判断和调度。这个变化看似简单实际上是整个 Agent 从“花瓶”走向“生产力工具”的关键一步。我个人的习惯是每次从一个新技能包里学到了好思路就顺手把它拆开看一遍看作者是怎么写description的是怎么划分脚本职责的又是怎么处理异常情况的。拆了十几个包之后你自己写包的水平也会明显上一个大台阶。如果你刚接触这个概念今天就做一件事找一个和手头工作相关的技能包装上跑通一次然后试着改一版适合自己习惯的说明。这个流程走完你就算真正入门了。剩下的事情就是在多平台之间反复折腾、踩坑、优化慢慢形成一套自己的“技能资产管理体系”。 Agent Skills实战：从安装到多平台复用，打造高效AI智能体
1. Agent Skills 到底是什么最近为什么到处都在聊先说结论Agent Skills 是 2025 年以来 AI Agent 方向里回报率最高的一个玩法。吴恩达专门写了一篇教程核心观点非常简单——与其反复调 prompt 让大模型“猜着干活”不如直接给它一套带说明文档的“技能包”让它看到任务就自动调用对应的那套流程。这个思路很快被 Claude Code、Cursor、OpenAI、国内各家大模型平台跟进现在基本上成了智能体落地的默认姿势。很多人第一次接触这个概念是在某个视频教程里看到一条命令npx skills add sandai-org/vidmuse-skills --agent claude-code -g -y。看起来就是在终端里“装了一个包”但背后其实完成了一次完整的技能分发从 GitHub 拉取技能包、识别当前使用的 Agent 平台、把技能文件放到全局目录、然后让 Claude Code 在运行时自动加载。这条命令跑完你的 AI 就不再是“有问必答”而是变成了“带工具箱干活”。那 Agent Skills 和普通的系统提示词、或者 MCP 有什么区别我个人的理解是它更像是“给 AI 的一本岗位手册 对应工具集合”。普通 prompt 是口头交代MCP 是外接的双手而 Skills 是两者之间的桥梁——它告诉模型在什么场景下、按什么步骤、调用什么函数、输出什么格式。这套机制最大的好处是模型不需要“想”怎么干活它只需要“照着做”。这个方向适合谁如果你是做 AI 应用开发的或者日常重度使用 Claude Code、Cursor 这类工具的非常值得把技能包的机制吃透。哪怕你不写代码只希望 AI 帮你画图、做视频、整理 Excel一套好的技能包就能让结果从“能看”变成“能用”。我下面写的内容都是我在多平台实际跑过之后总结下来的不绕弯子直接讲怎么用、怎么改、怎么排坑。2. 技能包机制的核心逻辑为什么“教它干活”比“让它猜”更靠谱2.1 一套 Skill 包的标准组成我拆过不少开源技能包也自己封装过好几个发现不管哪个平台技能包的内部结构基本都长一个样。一个合格的 Agent Skill 目录通常包含三块东西SKILL.md这是整个技能包的中枢用 Markdown 写的说明文档描述了该技能“什么时候用、怎么用、注意什么”。scripts/或src/放实际的执行脚本模型决定调用后就去执行这里面的程序。YAML frontmatter位于SKILL.md头部用---包裹声明技能的name、description等元信息。举一个具体的例子。比如你手头有一个vidmuse-skills包从名字看就知道是一个和视频创作/视频理解相关的技能集合。它的SKILL.md里大概率会写清楚当用户提出“帮我把这段文案转成短视频脚本”时你应该先加载哪段“镜头拆分模板”再调用哪个脚本去生成时间轴最后按照什么格式输出分镜表。这一整套“流程说明 可执行文件”的组合就是技能包的本质。YAML 部分非常关键我见过不少技能包不被加载就是 frontmatter 写错了字段模型根本不知道这个技能是干嘛的。以 Claude 系为例一个规范的 frontmatter 长这样--- name: vidmuse-create description: 当用户需要将文案、图片素材或灵感转换为短视频分镜脚本时使用。支持时长设置、镜头拆分、旁白生成。 ---description字段不能写得太含糊。模型在对话中判断“该不该调用技能”主要就是靠这个字段与用户请求做语义匹配。你写“视频脚本工具”模型匹配率就很低你写“当用户需要将文案转换为短视频分镜脚本时使用”匹配率立刻就上来了。2.2 它是怎么被模型发现并调用的理解了这个再看调用链路就很清晰了。模型每收到一轮对话都会在思考过程中“扫一遍”所有可用的技能描述找到匹配度最高的那个技能包读取对应的SKILL.md然后按照文档里的步骤执行。这个过程和人类新入职看 SOP 干活几乎一模一样。值得注意的是Agent Skills 的“技能”不一定每次都必须被调用。它更像是一个路由器模型判断命中才使用判断不命中就当普通对话处理。这个设计非常重要否则每个技能包都会抢着响应对话体验会变得异常混乱。那和 MCP 有什么区别呢我打个比方MCP 相当于给 AI 装了“手”——可以读取数据库、操作浏览器、调用 API而 Skills 相当于给它装了一本“作业指导书 配套习题答案”——不只告诉它能干什么还告诉它解决问题的标准路径。所以实际使用中往往两者搭配MCP 负责抓数据Skills 负责把数据加工成成品。2.3 为什么吴恩达一出来讲整个行业都跟着做吴恩达的 Agent Skills 教程 PDF 在社区传得很广我读完的最大感受是他其实没有发明什么新东西而是把大家一直在零散使用的方法规范化了。在他之前大家是各写各的提示词各种“专家提示词模板”满天飞他的贡献是把“给模型写技能说明”这件事做成了标准结构有元信息、有说明文件、有配套脚本、有分发机制随便换一个平台都能用。这一点非常戳行业痛点。以前大家做 Agent 应用最怕的就是换平台重写逻辑同一个任务在 Claude 上能用到了别的平台又得重新调一遍 prompt。如今技能包做成纯 Markdown 脚本的组合跨平台迁移成本大大降低。这也就是为什么“多平台应用”能成为一个独立的话题——因为 Skills 机制天生就是为了多平台复用而设计的。3. 从一行命令开始把技能包装进你的智能体3.1 拆解npx skills add这条核心命令视频标题里的命令我拆开讲一下很多新手直接复制粘贴跑通了也不知道每个参数在干什么。npx skills add sandai-org/vidmuse-skills --agent claude-code -g -ynpx skills这是社区里常用的skillsCLI 工具通过 npm 分发不需要提前下载安装。add sandai-org/vidmuse-skills指定要从哪个 GitHub 仓库拉取技能包。格式是组织名/仓库名跟npm install的写法很像。--agent claude-code告诉 CLI 你要把技能装到哪个 Agent 平台它会按平台的约定规则写入对应目录。-gglobal的缩写表示全局安装让当前机器的所有项目都能用而不仅限于当前目录。-y自动确认后续的提示跳过交互式提问方便脚本化执行。从实际经验看-g这个参数建议一直带着。如果不加技能只装到当前项目的.agents/skills目录换个项目就没了加了之后技能会被放到系统级的全局目录比如 macOS 上常见的位置是~/.claude/skills或~/.config/skills所有项目都能共享。3.2 安装完成后必须做的三件事命令跑完只是第一步很多人在这一步就以为“装好了”实际还差三步。第一验证技能是否被正确识别。如果你用的是 Claude Code在对话里直接输入/skills或者/agents就能看到当前可用的技能列表。如果列表里出现了你刚才安装的vidmuse-skills说明加载成功。第二确认技能目录结构。进入对应目录看一眼确认SKILL.md和脚本文件都完整存在。有时候网络拉取不完整会导致目录在但文件缺失模型调用时直接报错。第三找一个最小用例测试。比如问你的 Agent“帮我用 vidmuse 生成一个 15 秒的猫猫日常短视频脚本。”如果模型开始按照技能包的分镜格式输出就说明整个链路通了如果它答非所问多半是技能没被加载或者 description 匹配失效。3.3 全局技能目录与项目级技能目录怎么选这里我多说一点很多老手也会在这上面犹豫。技能目录有两种全局和项目级两者并不是二选一的关系而是按场景选择。全局技能目录适合装通用型技能比如“PPT 大纲生成”“Excel 数据清洗”“短视频脚本”因为这类任务不管你开哪个项目都用得上。项目级技能目录适合装和项目强绑定的专属流程。比如你手头在做一个电商数据分析项目就可以把“店铺周报生成”这套技能装到该项目目录下别人 checkout 代码后不需要额外安装技能自动生效。我个人习惯是通用技能走全局专属技能走项目。安装命令上全局就加-g项目级就不加很简单。3.4 一条命令装多个技能包skillsCLI 还支持一次加多个包用空格隔开就行npx skills add sandai-org/vidmuse-skills someuser/slide-skills another/report-skills --agent claude-code -g -y这个功能适合新环境初始化比如换了台新电脑一条命令把常用的技能全都装回来。不过要注意技能包之间可能会存在指令冲突比如两个包都响应“生成报告”模型就不知道该听谁的。所以一次装太多之前最好先逐个验证过再组合使用。4. 多平台应用实战Claude Code、Cursor、ChatGPT 与本地开源方案4.1 Claude CodeAgent Skills 的“原生主场”目前对 Agent Skills 支持最自然的就是 Claude Code。原因很简单这套技能的规范本身就是 Anthropic 在推的官方文档、社区工具链都对齐这个标准。在 Claude Code 里用技能体验是最顺滑的——你安装技能后不只是“能用”而是模型会在对话过程中主动检索技能描述并告诉你“我准备使用 vidmuse-skills 来完成这个任务”。Claude Code 中技能目录的加载优先级需要特别注意。它的查找顺序是项目目录.claude/skills 用户全局目录~/.claude/skills。如果同名的技能在两个目录都存在项目级优先。这个顺序决定了你调试时容易踩坑——改了全局技能包却发现不生效一看项目目录里还有个同名旧版。还有一个很实用的细节Claude Code 会在会话启动时自动索引所有可用技能但如果你在会话中途手动加了新技能并不会立即生效需要重启会话或者运行/agents刷新。我一开始不知道装完技能一整个下午都在问“为什么模型不调用”最后发现只是没有刷新索引。4.2 Cursor把技能包从命令行接到图形界面Cursor 作为 AI 编辑器对 Agent Skills 的支持方式是“对话时自动读取技能说明配合代码生成”。在 Cursor 里配置技能核心操作就是将技能包放到项目根目录的.cursor/skills下。和 Claude Code 不同Cursor 的技能目录更偏项目级全局配置目前还需要通过 Cursor 的settings里的自定义规则来实现。我的做法是在 Cursor 里写代码时调用 Claude Code 中已经验证过的技能包。比如让 AI 帮我生成 Django 视图的增删改查我就会用一个django-crud技能包它会告诉 Cursor 项目的模型命名规范、视图写法、URL 注册规则。实测下来生成的代码风格统一不需要像以前那样反复纠正。有一点提醒Cursor 对技能的自动“调用”不像 Claude Code 那么主动它更倾向于把技能内容当背景知识。所以你在写SKILL.md时最好把适用范围和触发条件写得非常明确不要用模糊词不然模型容易忽略。4.3 ChatGPT 与 OpenAI 系平台另一套标准别照抄如果是 ChatGPT 或者 OpenAI API 系目前的主流路径有两个一是将技能机制放到自定义 GPT 的 instructions 里二是通过file_search或知识检索让它读取技能文档。OpenAI 也在推进自己的 Skills 协议但从我测试的版本看它和 Anthropic 的实现并不完全互通字段名比鲁、加载方式都有差异。如果你是团队协作想统一维护一套技能包我强烈建议按 Claude Code 的标准来编写因为社区生态和 CLI 工具目前最成熟然后在发布到其他平台时写一个“转换器”把 YAML frontmatter 转成 OpenAI 平台要求的 schema。我封装过一次转换脚本大概两百来行 Python就能把 Markdown 技能包自动转换成可导入 OpenAI 的 JSON 配置。这个思路对“多平台”这一步非常关键——没有自动化转换维护两套标准会苦不堪言。# skills_converter.py # 将 Claude 风格的 SKILL.md/YAML 转成 OpenAI 自定义指令格式 import yaml, json, sys def convert(skill_path: str) - str: with open(skill_path, r, encodingutf-8) as f: content f.read() parts content.split(---) if len(parts) 3: raise ValueError(SKILL.md 缺少 YAML frontmatter) meta yaml.safe_load(parts[1]) body ---.join(parts[2:]).strip() instruction fSkill Name: {meta.get(name)}\n instruction fWhen to use: {meta.get(description)}\n instruction fSteps:\n{body}\n return instruction这段小工具的逻辑很简单但足够实用把 frontmatter 里的description转成“When to use”再把正文直接拼接成指令。这样你在团队里只需维护一套 Markdown剩下的转换工作交给脚本。4.4 本地开源方案OpenHands 与 Continue 的接入思路如果你介意云端平台想在本地部署 Agent那么 OpenHands 这类开源项目也支持自定义技能。OpenHands 的技能目录通常放在~/.openhands/skills或项目目录下的openhands/skills机制上和 Claude Code 类似都有一个SKILL.md文件描述触发条件。Continue 则是以 IDE 插件形式存在它的 “Rules” 机制可以直接把技能说明文件路径写进配置效果相当于是“全局背景知识”。在这种架构下技能包更像是“提示词模板库”模型的调用机制并不存在——它只是在生成代码时参考了你提供的规则。所以如果你要在非 Anthropic 系平台上用 Agent Skills核心要调整的不是技能包本身而是“调用方式”。在 Claude Code 里模型会自动判断何时该读取技能包在本地开源方案里很多情况下技能是全量加载的需要考虑上下文开销。一个几万字的SKILL.md全塞进去会影响对话质量需要精简说明。4.5 多平台复用的完整流程参考聊了这么多我把一次完整的跨平台使用流程整理成一张“行动路线图”照着走基本不会出错。在 GitHub 上找到一个满意的技能包仓库。先用 Claude Code 安装、测试确认这个技能包逻辑符合预期。将技能包从全局目录复制到你常驻的项目目录提交到 Git。这样团队其他人拉代码后自带技能。如果需要在 Cursor 里用在项目根目录建.cursor/skills把技能包复制过去同时把SKILL.md里的触发条件写得比 Claude Code 版本更显式。如果需要给 ChatGPT 用用我上面的转换脚本将 Markdown 转成指令文本粘贴到 Custom Instructions 或知识文件里。每次修改主技能包务必同步更新各平台下的副本或者在文档开头标注“本版本最后修改时间”。说实话这个流程第一次走会有点繁琐但一旦跑通后面再添加新技能就非常省事。而且我强烈建议团队内部把技能包当作代码一样管理用 GitHub 仓库来维护不要只躺在某一个人的笔记本里。5. 自己动手封装一个 Skills 包从零到可用的完整过程5.1 设计思路先想清楚“要教会 AI 干一件什么完整的事”自己封装技能包最重要的不是写代码而是想清楚“完整的事”是哪件事。什么叫完整比如“生成短视频脚本”就不够完整“根据用户输入的主题和时长生成包含镜头序号、景别、画面描述、旁白文案、字幕文案的表格并输出为 CSV”才是完整。技能包的价值在于把模糊目标转成明确流程。我一般建议从一个你“已经手工重复做了三遍以上”的事情开始比如你每月都要整理一份数据周报这个流程极其适合固化成一个技能包。因为有真实的工作流可以参照写出来的步骤是验证过的而不是拍脑袋编的。还需要考虑“输入是什么、输出是什么”。一个技能的输入通常是用户对话中的自然语言描述输出则最好是结构化文本或文件。我在设计时会先定义输出格式再倒推操作步骤。比如输出是 CSV 表格那我就倒推先读取数据源→清洗字段→计算指标→拼接模板→输出文件整个链条非常清晰。5.2 编写SKILL.md的规范与技巧SKILL.md是技能包的灵魂我写了几十个之后总结出几个对效果影响巨大的技巧。第一正文开头必须先写“触发场景”而且要用枚举列表列出来不要写成一大段话。例如## 使用场景 - 用户说“帮我做一个短视频脚本” - 用户提供文案并要求生成分镜 - 用户希望批量生成多个视频脚本模型扫描技能时枚举列表比散文更容易命中。你写一百个字描述场景不如直接列出五条典型请求。第二操作步骤中要明确角色分工。有些步骤是模型直接推理完成有些步骤需要调用脚本有些步骤需要生成中间文件应当区分开来。我常用的标记方式[推理]模型根据已有信息分析并输出结果。[工具]调用scripts/下的脚本。[确认]需要用户确认后才能继续。这套标注非常笨但实测下来能让模型的行为稳定很多不然它经常越权执行不该执行的步骤。第三针对容易出错的环节写“易错点”区块。比如视频脚本技能里十个人有九个人分不清“分镜脚本”和“拍摄脚本”的区别那你的SKILL.md就明确写一句“本技能输出的是分镜脚本不包含场地安排和演员调度内容。”这句话能给模型套上缰绳避免生成不相关的信息。5.3 一个真实的技能包封装示例我拿“周报生成器”做一个例子完整展示结构。技能包目录如下weekly-report-skill/ ├── SKILL.md ├── scripts/ │ ├── generate_report.py │ └── templates/ │ └── weekly_report_template.md └── assets/ └── sample_data.csvSKILL.md的内容写清楚当用户说“生成周报”时先用sample_data.csv作为演示数据说明字段含义然后调用generate_report.py对输入数据进行清洗和统计最后把统计结果填入 Markdown 模板生成一份格式统一的周报。generate_report.py的核心逻辑不需要多复杂比如用 pandas 读取 CSV计算本周/上周环比生成图表最后替换模板字符串。关键在于模型只知道“有脚本可以调用”具体脚本内部实现并不关心。这就是 Agent Skills 的理念人类负责写工具模型负责调工具。写完之后记得在 scripts 目录下加一个requirements.txt让模型在缺依赖时知道该装什么。实测下来这一步经常被忽略结果技能包在别人机器上直接用不了非常尴尬。5.4 导入测试与迭代技能包写完第一时间导入 Claude Code 测一轮。测的时候不要直接问“你会用周报技能吗”这种开放式问题没有意义。最好模拟真实任务说“这是一份本周订单数据请帮我生成周报重点对比华东和华南区域的环比变化”。这里有个非常重要的检查点看模型是否主动提到它调用了技能包。如果它只是即兴发挥说明你的技能描述触发不够如果它表示这是“基于内置知识”生成的说明技能包完全没被加载。每次测试后回到description字段微调措辞通常两三轮迭代后效果就会明显改善。另外技能包的迭代也应该版本化。我在SKILL.md里放了一个version字段每次改动递增一位方便回退也方便团队里多人协作时对齐状态。6. 实战中的常见问题与排查技巧实录6.1 技能包“装上了但模型就是不调用”优先级最高这个现象占了日常问题的一大半。表现是你明明装好了技能包目录也在但问任何问题模型都像个没事人一样。排查路径我基本固定排查点操作判断标准技能列表是否可见在 Claude Code 输入/skills列表中没有该技能则加载失败description 是否具体阅读 SKILL.md 头部 YAML是否包含“当用户…时使用”这类触发措辞测试问题是否命中换一个和技能描述强相关的说法如果改问法后能命中说明描述措辞太窄是否在会话前安装重启会话或运行 /agents 刷新索引刷新后技能列表出现说明之前是索引问题全局目录位置是否正确查看skills list的输出确认安装路径对应的是当前 Agent这条路径我从不跳过几乎能定位 90% 的问题。6.2 技能包被加载了但生成结果完全不按说明来这种情况和“完全不调用”正好相反模型确实在用技能包但输出结果看起来像在自由发挥。一般原因有三类。一类是SKILL.md里步骤写得有歧义模型不知道先执行哪一步。解决办法是把步骤改成“必须按顺序执行”的强措辞并把每步的输入输出标注清楚。另一类是脚本本身报错但是模型错误地继续推理了。比如generate_report.py因为缺少 pandas 抛了异常模型不告诉我而是自己“猜”了一个报告出来。这个非常坑。我的解决办法是在脚本里加异常兜底任何异常都输出ERROR: {错误信息}同时让SKILL.md告诉模型“看到 ERROR 必须停止并向用户说明”。第三类是最难查的模型被第二个技能包“带偏”了。如果机器上同时装了“通用写作助手”和“周报生成器”两个包都抢着响应写周报请求输出就很可能夹杂着两种风格。解决办法就是精简技能包数量或在技能包的说明里加上“本技能优先于通用写作类技能处理结构化周报任务”。6.3 跨平台移植后结果大相径庭同一个技能包在 Claude Code 里效果好换到 Cursor 里就变味。这本质上是因为不同平台对技能包的“调用策略”不一样。Claude Code 至少还有一个显式的技能列表入口而 Cursor 完全靠模型自己判断是否读取.cursor/skills下的内容触发概率就低了不少。我的经验是在 Cursor 里使用的技能包需要把description字段写得更偏向“显式指令”比如改成“每次用户要求生成周报时必须读取本文件并按步骤执行”。听起来像在“命令”模型但效果确实比“提示”式描述有效得多。另外在 Cursor 的 Rules 里加一行“项目使用 .cursor/skills 目录下的技能包生成结果前必须参考”也能显著提升调用率。6.4 必加的“安全措施”与通用避坑清单最后分享几个踩过坑后养成的习惯这些不属于官方文档但你可以直接抄。不要直接修改全局技能包的原文件。我先复制到项目目录再改这样即使改坏了也不影响其他项目。另外技能包仓库往往会更新直接改源文件会被 Git 覆盖你的改动全部白费。不要在SKILL.md里贴超长代码。模型读取大段代码会占用大量上下文还容易产生幻觉。正确做法是把代码放到scripts目录SKILL.md里只写调用命令和参数说明。版本号务必写在文件名或 frontmatter 里。我用weekly-report-skill-v2这种命名方式好几个技能包同时存在也不怕模型能根据描述选择最新版。技能包里的提示语一定要是“指令式”不要用“请”字。模型不会因为有礼貌就做得更好清晰、直接、分步骤的指令才是它最需要的。7. 一些值得长期跟踪的方向关于 Agent Skills还有一个很值得玩味的点它把“知识”和“执行”拆开了。以前你给模型一个 prompt它记住了“知识”但不会执行现在你用技能包把“知识”固定下来把“执行”交给脚本模型只负责判断和调度。这个变化看似简单实际上是整个 Agent 从“花瓶”走向“生产力工具”的关键一步。我个人的习惯是每次从一个新技能包里学到了好思路就顺手把它拆开看一遍看作者是怎么写description的是怎么划分脚本职责的又是怎么处理异常情况的。拆了十几个包之后你自己写包的水平也会明显上一个大台阶。如果你刚接触这个概念今天就做一件事找一个和手头工作相关的技能包装上跑通一次然后试着改一版适合自己习惯的说明。这个流程走完你就算真正入门了。剩下的事情就是在多平台之间反复折腾、踩坑、优化慢慢形成一套自己的“技能资产管理体系”。