Agent Skills 多平台实战：安装、迁移、排障与自定义技能包全指南

这阵子 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 仓库里的技能包装到本地。但拆开看每一段都有讲究npxNode.js 自带的包执行工具它的好处是不用先把skills这个 CLI 装成全局工具直接拉起 npm 包执行装完即走不留垃圾。skills目前社区里比较通用的 Agent Skills 管理 CLI由 skills.sh 维护。它负责解析远程仓库、复制文件、生成索引。add子命令表示要添加一个新技能包。sandai-org/vidmuse-skillsGitHub 仓库地址格式是组织名/仓库名。这里是三呆工作室开源的 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 火起来之后很多人把它和 MCPModel Context Protocol、Tools 混为一谈。我一开始也糊里糊涂后来做了个表格才彻底理清。概念作用对象核心思路典型例子ToolsAI 运行时给 Agent 一个可调用的函数/接口搜索工具、读网页工具、执行代码工具MCP工具与应用的通信协议用标准化协议让 AI 接入外部服务通过 MCP 连接数据库、连接浏览器SkillsAgent 的能力封装给 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但需要手动配置 rulesOpenAI 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 --since24 hours ago --oneline 获取最近提交 2. 运行 git diff --stat HEAD~1 获取变更统计 3. 将结果整理成以下结构 - 今日完成事项 - 变更文件统计 - 遇到的问题 - 明日计划 ## 注意事项 - 如果 git 仓库为空或没有提交记录直接说明“无新改动” - 日报保持简洁不超过 200 字第三步写辅助脚本可选技能包可以附带脚本AI 在某些平台上能直接执行。比如写一个scripts/get_changes.sh#!/bin/bash echo 最近提交 git log --since24 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 提前度确实比亲手写提示词高一个量级。