这阵子 AI 圈子里最火的话题，除了各家大模型轮番上新，就是 Agent Skills 了。吴恩达亲自出教程，GitHub 上一堆 skills 仓库，装个技能跟 npm 装包一样，一条npx命令就完事。我前两天刚把一套 vidmuse-skills 装上，在 Claude Code、Codex、Cursor、OpenCode 几个平台来回切换着用，顺手把踩过的坑都记了下来。这篇就把 Agent Skills 在多平台下的安装、配置、迁移和排障一次性讲透，全程无密，照着抄就行。
1. Agent Skills 到底是什么：从一条安装命令说起
先说结论：Agent Skills 就是给 AI Agent 塞一本“操作手册”。它把某个特定领域的工作流、判断标准、工具调用方式打包成一个标准目录结构，AI 在对话时读取这个包，就等于临时学会了这门手艺。它不是新模型，也不是新框架，而是一层轻量级的“能力封装”。
很多人第一次接触 Agent Skills，就是从这条命令开始的：
npx skills add sandai-org/vidmuse-skills --agent claude-code -g -y接下来我把这条命令拆开讲，顺便把背后的机制说清楚。
1.1 一条命令拆开看：npx skills add背后发生了什么
这条命令表面上做了一件事：把某个 GitHub 仓库里的技能包装到本地。但拆开看，每一段都有讲究：
npx：Node.js 自带的包执行工具，它的好处是不用先把skills这个 CLI 装成全局工具，直接拉起 npm 包执行，装完即走，不留垃圾。skills：目前社区里比较通用的 Agent Skills 管理 CLI，由 skills.sh 维护。它负责解析远程仓库、复制文件、生成索引。add：子命令，表示要添加一个新技能包。sandai-org/vidmuse-skills：GitHub 仓库地址，格式是组织名/仓库名。这里是三呆工作室开源的 vidmuse 技能包，内容跟视频创意与视觉生成相关。--agent claude-code：指定这个技能包主要服务的 Agent 平台。Claude Code 是 Anthropic 官方的命令行 AI 编程工具，也是目前对 Agent Skills 支持最积极的一个。-g：全局安装。技能包默认只装进当前项目的.claude/skills目录，加上-g会装到用户级目录（通常是~/.claude/skills），这样你在任何目录下打开 Claude Code 都能识别到。-y：跳过交互式确认。安装过程本来会问你“确认要下载这个仓库吗？”，-y就是替你回答了“是”。
装完之后，skillsCLI 会把仓库拉取到本地，解析里面的SKILL.md文件，并在对应的平台目录里生成索引。整个过程看起来像“装软件”，本质上是把一套提示词工作流和辅助脚本拷贝到了 AI 能读取的位置。
1.2 Skills、Tools、MCP，别再傻傻分不清
Agent Skills 火起来之后，很多人把它和 MCP（Model Context Protocol）、Tools 混为一谈。我一开始也糊里糊涂，后来做了个表格才彻底理清。
| 概念 | 作用对象 | 核心思路 | 典型例子 |
|---|---|---|---|
| Tools | AI 运行时 | 给 Agent 一个可调用的函数/接口 | 搜索工具、读网页工具、执行代码工具 |
| MCP | 工具与应用的通信协议 | 用标准化协议让 AI 接入外部服务 | 通过 MCP 连接数据库、连接浏览器 |
| Skills | Agent 的能力封装 | 给 Agent 注入流程化、场景化的知识 | 视频分镜技能包、日报生成技能包、代码审查技能包 |
打个比方：Tools 是工具包里的扳手和螺丝刀，MCP 是工具箱的统一接口规格，而 Skills 是老师傅的脑子。扳手再好用，不会用也是废铁；接口再标准，不知道什么时候该调用也没用。Skills 解决的就是“什么场景下用什么工具、按照什么顺序做”的问题。
从实现上看，一个技能包可以引用已有的 Tools 和 MCP 服务，把它们按特定流程组织起来。所以 Skills 不是替代 MCP，而是站在 MCP 和 Tools 之上的“调度手册”。
1.3 为什么“Skill”突然成了高频词：从吴恩达教程聊起
Agent Skills 这波热度，吴恩达功不可没。他在 DeepLearning.AI 上推出的 Agent Skills 教程，核心观点是：大模型的能力边界已经够宽了，缺的不是更强的推理，而是更专的“工作方法”。他提出把专家经验沉淀成技能包，让 Agent 直接加载，这比在系统提示词里写一堆约束要可靠得多。
为什么这个观点能火？原因很实际：
- 门槛足够低：写技能包不需要训练模型，只需要把你擅长的事情写成清晰的步骤文档，挂到一个目录里，AI 就能照着执行。
- 复用性极强：同一个技能包，Claude Code 能用，Codex 能用，Cursor 只要稍微适配也能用，边际成本趋近于零。
- 效果立竿见影：装完技能包之后，AI 输出质量确实会有肉眼可见的提升，因为它不再“临场发挥”，而是按流程办事。
我自己体验下来，装技能包前后，Claude Code 生成视频脚本的质量差距非常明显。没装之前是“写得对”，装了之后是“写得对且专业”。这一点在后面实操部分会详细讲。
2. 多平台适配：一套技能如何在 Claude Code、Codex、Cursor、OpenCode 之间流转
Agent Skills 多平台应用，最关键的问题就是：同一套技能包，怎么在多个 AI 平台上跑起来？这涉及到平台对技能包格式的支持程度、目录结构的差异、以及触发机制的细微差别。
先说结论：一套基于SKILL.md的技能包，至少能在 Claude Code、Codex CLI、Cursor、OpenCode 四个平台上流转。但“能流转”不等于“无脑兼容”，里面有不少细节。
2.1 主流平台对 Agent Skills 的支持现状
我用四个主流平台做了实测，结论如下：
| 平台 | 技能包支持方式 | 读取目录 | 原生程度 | 备注 |
|---|---|---|---|---|
| Claude Code | 原生支持 | .claude/skills | 最高 | Anthropic 自家标准，SKILL.md 直接加载 |
| Cursor | 部分原生 | .cursor/skills | 较高 | 支持 SKILL.md，但需要手动配置 rules |
| OpenAI Codex CLI | 通过 skills CLI 适配 | ~/.codex/skills | 中等 | 需要skillsCLI 转换格式 |
| OpenCode | 开源支持 | .opencode/skill | 中等 | 社区实现，兼容性要看版本 |
实测下来，Claude Code 对SKILL.md的加载最积极，只要技能描述里写清楚适用场景，它会在合适的时机自动调用。Cursor 的兼容性也不错，但它的技能机制原来叫 “Rules”，现在虽然支持SKILL.md，触发逻辑还是跟 Claude Code 有差异。
要让一个技能包同时跑在多个平台，路径就是：把技能包的核心写成标准的SKILL.md，再针对不同平台的读取目录做一份拷贝或软链接。
2.2 SKILL.md 格式：技能包的核心契约
SKILL.md是技能包的灵魂文件，它本质上是一份给模型读的 Markdown 文档，但结构上有约定。一个标准的SKILL.md长这样：
--- name: vidmuse-skill description: 视频创意与视觉生成工作流。用于生成视频脚本、镜头拆解、提示词优化等任务。 metadata: version: 1.0.0 author: sandai-org tags: [video, creative, prompt] --- # VIDMUSE 技能包 你是一名资深视频创意导演，擅长把一段描述拆成可执行的镜头语言。 ## 触发场景 - 用户要求生成视频脚本 - 用户要求优化文生视频提示词 - 用户要求拆分镜头脚本 ## 执行流程 1. 确认视频主题和目标受众 2. 生成整体叙事结构 3. 拆解镜头：场景、画面、运镜、时长 4. 生成对应的提示词 5. 输出可直接用于视频生成工具的参数 ## 注意事项 - 镜头拆解时遵循 3-5 秒一个镜头的原则 - 提示词遵循“主体+动作+环境+镜头+风格”的结构为什么格式统一这么重要？因为模型读 Markdown 文档的方式和人类不一样。它不是“理解大意”，而是把整个文件塞进上下文窗口，当成指令来解析。标题层级越清晰、指令表达越明确，技能生效的质量就越高。如果你的SKILL.md写成了流水账，模型可能只提取到一半信息，技能包就会变成摆设。
另外要注意，SKILL.md里的description字段极其关键。Agent 会根据这个描述来决定“这个技能在什么场景下该被激活”。描述写得太窄，模型永远不会触发；写得太宽，又会在不该用的时候乱用。我见过不少人装完技能不生效，九成是 description 写得有问题。
2.3 跨平台迁移的三种路径对比
要在多平台实现同样的技能效果，我总结出三种迁移路径，各有优劣：
路径一：用 skills CLI 统一安装
npx skills add sandai-org/vidmuse-skills --agent claude-code -g -y npx skills add sandai-org/vidmuse-skills --agent cursor -g -y npx skills add sandai-org/vidmuse-skills --agent codex -g -y不同平台执行不同的安装命令，CLI 会自动把技能文件放到对应目录。优点是最省心，缺点是每个平台要单独跑一次命令。
路径二：手动拷贝目录
直接把.claude/skills里的技能目录复制到.cursor/skills，或者在~/.codex/skills下建软链接。优点是快，缺点是你得知道每个平台的目录约定，而且跨平台时SKILL.md里的 frontmatter 可能要微调（比如某些平台不识别metadata字段）。
路径三：项目级共享技能目录
在项目根目录建一个共享的/skills目录，然后让每个平台的配置都指向这个目录。这个方式适合团队协作，因为你只需要维护一份技能包，所有成员用各自的平台读取。缺点是配置复杂度高，需要你熟悉每个平台的路径映射规则。
我个人建议：小范围试用走路径一，固定工作流复用走路径三。路径二适合临时测试，不建议生产环境用。
3. 实操篇：从零安装 vidmuse-skills 并跑通第一个任务
前面理论讲得再多，不如亲手跑一遍。这一节我把安装 vidmuse-skills 的完整过程写出来，从环境检查到最终跑通一个视频脚本生成任务，每一步都附上实测记录和参数说明。
3.1 安装前的环境准备与检查
安装技能包不需要编译，但对运行环境有基础要求，先把这四件事检查一遍：
检查 Node.js 版本
node -v npm -vskillsCLI 是基于 Node.js 的，实测 Node 16 以下会报错，建议安装 Node 18 以上。如果你用的是 nvm 管理版本，可以随时切换：
nvm install 20 nvm use 20检查平台 CLI 是否就绪
如果要在 Claude Code 里用技能，得确保 Claude Code 已经能用。执行一下：
claude --version如果提示找不到命令，就先去安装对应的平台 CLI。这些细节不展开，但必须确认。
检查目录是否存在
ls -la ~/.claude/skills这个目录是技能包的默认归宿。第一次运行可能不存在，别慌，skills add会自动创建。
检查网络与源
skills CLI默认从 GitHub 拉取仓库，国内网络有时候会超时。如果遇到下载失败，可以配置代理或者改用镜像仓库。这一步不展开，但你需要知道skills支持从本地目录安装。
npx skills add ~/my-skills/vidmuse-skills --agent claude-code -g如果你已经把仓库 clone 到本地，直接指定本地路径，可以避开网络问题。
3.2 完整安装步骤与参数详解
环境准备好之后，开始正式安装。我在 macOS 和 Ubuntu 上都验证过，流程一致。
第一步：执行安装命令
npx skills add sandai-org/vidmuse-skills --agent claude-code -g -y执行过程中，skillsCLI 会输出以下信息：
▶ Fetching repository: sandai-org/vidmuse-skills ▶ Resolving skill manifest... ✔ Found skill: vidmuse-skill ▶ Installing to global skills directory... ✔ Installed to ~/.claude/skills/vidmuse-skill看到Installed就表示成功了。
这里插一句，-g参数的行为值得注意。不加-g时，技能包会装到当前项目的.claude/skills目录，只对这个项目生效。加了-g，技能会在你所有项目里都能被识别。但-g也有副作用：团队协作时，你全局装了新版本，项目里可能还是旧版本，容易产生“本机能跑、别人跑不了”的问题。后面会有专门一节讲这块。
第二步：验证安装结果
npx skills list输出结果应该包含vidmuse-skill。同时可以看看实际目录：
ls -la ~/.claude/skills/vidmuse-skill正常情况下会看到：
SKILL.md scripts/ examples/ reference/第三步：在 Claude Code 里触发技能
打开 Claude Code，输入：
请帮我生成一段 15 秒的产品宣传视频脚本Claude Code 会根据SKILL.md里的description判断是否触发这个技能。如果触发了，你会在输出里看到它遵循了技能包里的执行流程，比如先确认主题、再拆镜头、最后生成提示词。
第四步：检查技能激活日志
Claude Code 支持查看详细的 debug 日志，如果在对话里没明显感觉技能生效，可以打开日志确认它是否加载了SKILL.md。
claude --debug在日志里搜skill关键字，能看到类似这样的记录：
[skill] Loaded skill "vidmuse-skill" from ~/.claude/skills/vidmuse-skill/SKILL.md到这里，安装链路就是通的。
3.3 自定义一个技能包的完整流程
很多人在跑通别人的技能之后都会想：我能不能自己做一个技能包？当然可以。我给你演示一个“日报生成技能”的最小实现，走完整个流程你就彻底明白技能包是怎么回事了。
第一步：创建目录结构
mkdir -p my-skills/daily-report/scripts cd my-skills/daily-report第二步：编写 SKILL.md
--- name: daily-report description: 生成项目日报。用于从 git 提交记录中提取变更内容，并输出结构化日报。 metadata: version: 1.0.0 author: your-name --- # 日报生成技能 ## 执行流程 1. 运行 `git log --since="24 hours ago" --oneline` 获取最近提交 2. 运行 `git diff --stat HEAD~1` 获取变更统计 3. 将结果整理成以下结构： - 今日完成事项 - 变更文件统计 - 遇到的问题 - 明日计划 ## 注意事项 - 如果 git 仓库为空或没有提交记录，直接说明“无新改动” - 日报保持简洁，不超过 200 字第三步：写辅助脚本（可选）
技能包可以附带脚本，AI 在某些平台上能直接执行。比如写一个scripts/get_changes.sh：
#!/bin/bash echo "== 最近提交 ==" git log --since="24 hours ago" --oneline echo "== 变更统计 ==" git diff --stat HEAD~1第四步：本地安装并测试
npx skills add /path/to/my-skills/daily-report --agent claude-code -g -y然后在 Claude Code 里说“生成日报”，看看它是否按流程执行。
第五步：发布到 GitHub
把my-skills/daily-report推到 GitHub 仓库，别人就能通过npx skills add 你的用户名/daily-report安装了。
到这里，你已经能独立制作技能包了。核心逻辑就一句话：把你要 AI 执行的流程写清楚，让它按照这个流程输出。
3.4 从安装到调用：实际跑通一个多平台任务
我装完 vidmuse-skills 之后，实际跑了一个“把一段文案变成视频分镜脚本”的任务。过程记录下来供参考：
第一步，在 Claude Code 里输入：
把这段文案改成视频脚本：我们的新咖啡豆采用日晒处理， 带有明显的柑橘和巧克力风味，适合喜欢果酸和醇厚口感的人。第二步，Claude Code 加载了 vidmuse-skill，先确认了主题是“咖啡豆推广视频”，然后输出了结构化的镜头列表：
镜头1：近景，日晒处理的咖啡豆在桌上翻滚，暖色调，3秒 镜头2：特写，手冲壶向下注水，水花飞溅，浅景深，3秒 镜头3：中景，咖啡杯被端起，杯口冒着热气，4秒 镜头4：远景，咖啡馆吧台全景，顾客在交谈，5秒每段都配了对应的文生视频提示词，比如：
raw coffee beans tumbling on table, warm sunlight, close-up, 3 seconds这段输出质量，明显比我直接在 Claude Code 里“硬写”要高——因为技能包把镜头语言的经验预设进去了。
第三步，我在 Cursor 里打开同一个项目，切到 Agent 模式，同样输入这句话。Cursor 也正确加载了技能包，生成结果几乎一致。这就是多平台复用的效果，一套技能，处处可用。
4. 常见问题与避坑实录
技能包这东西，装起来很爽，用起来小问题不少。我整理了几个高频问题，每个都是我实际踩过的坑。
4.1 装完技能不生效：八成是这几个原因
如果装完技能后，平台完全没反应，优先从下面这几个地方排查：
| 问题现象 | 可能原因 | 排查步骤 | 解决办法 |
|---|---|---|---|
| 技能完全没被触发 | SKILL.md 的 description 写得太窄或太宽 | 查看 description 字段实际内容 | 重新描述触发场景，写清楚“当用户要做什么时使用” |
| 只有部分平台生效 | 平台目录不兼容 | 确认安装到了哪个目录 | 针对目标平台单独执行skills add |
明明加了-g却不生效 | 平台缓存没刷新 | 重启 CLI 或 IDE | 关闭终端/编辑器重新打开 |
| 技能加载了但输出不对 | 模型版本或上下文长度限制 | 查看 debug 日志中 skill 加载记录 | 缩短 SKILL.md 正文，精简指令 |
其中最常见的是第一个——description 写得太笼统。比如你写成“视频技能”，模型不知道什么时候该用；写成“生成视频脚本、镜头拆分、文生视频提示词优化”，模型就清楚多了。
4.2 -g -y 别乱用：作用域、权限与安全
-g和-y这两个参数虽然方便，但都有副作用。
-g的问题在于作用域。全局安装的技能包会出现在你所有项目里，如果你同时在多个项目里做不同类型的任务，全局技能可能会在不该出现的地方被触发。比如日报生成技能是全局的，你在写代码的项目里说“帮我总结一下今天做了什么”，它可能就会往日报方向跑。
-y的问题在于安全。这个参数会跳过一切确认，如果你从不可信的仓库安装技能包，等于把未知代码直接拉进你的用户目录。技能包本质上是代码，安装前至少扫一眼仓库内容，看看它的SKILL.md里有没有可疑指令，有没有附带执行脚本。
我给一个建议：用-g之前看清楚技能包适用的 agent，用-y之前确认是可信仓库。
4.3 多平台“假兼容”陷阱
这一节是我比较想强调的。很多技能包宣称支持多平台，实际上只是“能装进去”，离“正常运转”还有一段距离。我在实际操作中就遇到了三个坑：
坑一：frontmatter 字段解析差异
Claude Code 能识别SKILL.md里的metadata字段，但 Cursor 和 Codex 不一定。如果SKILL.md里写了类型不匹配的 metadata（比如数组里用了[]），某些平台会直接跳过整个文件。
坑二：环境变量和路径假设
技能包里的脚本如果引用了$HOME或写死了路径，换平台可能失效。比如在 macOS 上是/Users/xxx，在 Linux 上是/home/xxx，脚本里写死了就完蛋。
坑三：模型能力差异
技能包只是指令，最终执行靠模型。Claude 3.5 Sonnet 和 GPT-4o 对同一份SKILL.md的理解有差异，同一个技能在两个平台上的输出质量可能一个天一个地。这不是技能包的问题，是模型差异，你得接受。
想要减少假兼容问题，我建议你在技能包的 README 里写清楚“在哪个平台、哪个模型版本上验证过”，这样其他人用的时候有个参考基线。
4.4 团队协作时如何共享技能包
最后聊聊团队场景。如果你的团队有七八个人，大家都在用 Agent Skills，怎么维护一套统一的技能包？
我的做法是：
- 把技能包仓库作为唯一可信源。所有人从同一个 Git 仓库安装，而不是各自维护版本。
- 在项目根目录锁定技能版本。使用
skills.json或直接记录安装命令，确保团队成员安装同一个版本。 - 写清兼容矩阵。在 README 里说明这个技能包在哪个平台、哪个版本上测试通过，避免伙伴装完发现不兼容互相扯皮。
{ "skills": { "vidmuse-skills": { "source": "sandai-org/vidmuse-skills", "version": "1.2.0", "agents": ["claude-code", "cursor"] } } }这样团队里的新人来了，看一遍文档就能搭好环境。
我这段时间把 Agent Skills 从安装到自定义再到多平台适配完整走了一遍，最大的感受是：技能包的价值不取决于你装了多少，而取决于你把流程写得清不清楚。你给 AI 一份好手册，它就能像老员工一样干活；你给它一本流水账，它也只能满嘴冒烟地瞎猜。
所以，如果你也想搭自己的技能包，我建议从写好第一份SKILL.md开始——先想清楚“我希望 AI 在什么场景下做什么事”，然后把这个过程拆成步骤写下来。写完先给 Claude Code 试，跑通了再往其他平台搬。技能包这个东西，做一次就能上手，做完你就会发现，Cont 提前度确实比亲手写提示词高一个量级。
