在 GitHub 上刷到一条安装命令被疯狂转发npx skills add sandai-org/vidmuse-skills --agent claude-code -g -y。正好吴恩达那边关于 agent skills 的教程资料也被翻出来传阅连 PDF 都被整理了好几版。很多人第一反应是这不就是给 AI 助手装个插件有必要搞这么大动静吗还真不是。Agent Skills 这套定义看着轻巧但它牵扯的是从 Claude Code 命令行、桌面应用到第三方编码助手、再到 API 自建工作流的多平台协同问题。这段时间我在不同端里反复折腾 skills 的安装、调用、迁移和自建踩了不少坑也总结出一套能直接复用的流程。这篇文章就把整个实战过程完整过一遍先把命令每个参数讲清楚再讲多平台怎么适配最后给出一套自写技能包的方法。适合手里有 Claude Code、或者正在用各类 AI 编码工具但总觉得“提示词塞不进去”的朋友。1. 先看懂 Agent Skills它不是插件也不是 MCP1.1 一次解决“提示词写不进去”的痛点先说一个经常遇到的场景。你用 Claude Code 做一个项目每次都要在对话里反复嘱咐它“输出格式按 XXX 来”“不要碰 YYY 目录”“代码里要带注释”……这些话重复一遍又一遍换个会话又得重来。更尴尬的是当任务稍微复杂一点比如“分析这段视频的分镜风格并生成新的分镜脚本”对话里的临时指令根本撑不住这种多步骤操作。Agent Skills 解决的就是这个问题。它把“某个场景下 AI 应该怎么干”这整套行为规范固化成一个体积很小的技能包。技能包本质上是标准化的 Markdown 文件里面写清楚了触发条件、执行步骤、输出格式、禁忌事项。AI 助手在运行时会主动读取这些文件在合适的时机按技能里的流程办事。你不用再手把手教它自己就知道该调用哪套“工作手册”。1.2 Skill、Prompt、MCP 三者到底差在哪刚开始我也把 Skill 和 MCP、普通 Prompt 混在一起后来把它们放在同一张表里对比一下就清楚了。扩展方式本质类比解决什么问题普通 Prompt对话里的临时指令口头交代一句一次性任务不可复用MCP让 AI 多出的外部工具接口给 AI 插个 U 盘、接个传感器让 AI 能操作外部系统、拉取数据Agent Skills给 AI 读的操作手册给实习生一份 SOP 文档让 AI 按特定方法论稳定执行MCP 和 Skills 经常被一起提但两者根本不是一回事。MCP 解决的是“AI 能碰什么”Skills 解决的是“AI 该怎么想”。一个技能包里面完全可以只写分析和输出规范不调用任何外部工具一个 MCP 服务也不等于任何技能它只是把数据或操作能力暴露给 AI。真正完整的工程里两者往往配合使用MCP 提供数据入口Skills 提供处理数据的流程。1.3 为什么吴恩达的教程突然这么火吴恩达那边把 Agent Skills 放进生成式 AI 课程里社区里很快就传开了。核心原因倒不是这东西多复杂而是它补上了一个一直被忽视的环节技巧沉淀和复用。过去我们调 AI靠的是个人经验、分散的提示词片段、朋友圈截图分享。Skill 给出了一套开放的文件规范让“调教 AI 的经验”变成了可安装、可分发、可版本管理的普通文件。官方课程资料是可以正常获取的网传的 PDF 大多是社区整理版入门建议还是以官方渠道内容为准配合实际命令跑一遍比囤十个 PDF 有用得多。2. 安装一条命令拆开细看npx skills add 背后做了什么2.1 命令每个参数的真实含义先把最常被引用的这条命令完整拆开npx skills add sandai-org/vidmuse-skills --agent claude-code -g -y从左到右逐个讲npx是 Node.js 自带的命令行工具专门用来临时执行 npm 包。用npx执行意味着你不必手动全局安装 skills 这个 CLI它会自动下载并运行。skills add是 skills 命令行工具的子命令表示“安装一个技能包”。sandai-org/vidmuse-skills是技能包的仓库地址标准格式是 GitHub 的owner/repo。这里对应的就是 sandai-org 组织下的 vidmuse-skills 仓库看目录名应该和视频生成、镜头语言这类创作任务有关。--agent claude-code指定技能装给谁。不同 AI 助手读取技能文件的目录规则可能不一样这个参数就是告诉 CLI“我要把技能装到 Claude Code 能认的那个目录里”。-g代表全局安装也就是装到当前用户的通用技能目录而不是只装到某一个项目目录下。-y是跳过确认。安装过程中 CLI 会提示你确认仓库地址、安装位置加了这个参数后一路自动执行适合脚本化批量操作。2.2 安装过程中 CLI 实际帮你做了四件事执行命令后表面上你只看到几行进度输出实际上 CLI 在后台做了四件事。第一解析并拉取仓库。它会把sandai-org/vidmuse-skills对应的 GitHub 仓库完整拉下来这一步走的是 Git 协议所以本机必须提前装好 Git。第二扫描技能描述文件。拉下来之后CLI 会在仓库里找SKILL.md文件。这是 Agent Skills 规范的核心一个技能包可以包含多个SKILL.md分布在不同的子目录里每个子目录就代表一个独立技能。第三按指定 agent 的规则写入对应目录。Claude Code 约定的技能目录一般是以.claude/skills结尾的文件夹--agent claude-code就是告诉 CLI 把复制目标锁定在这里。如果指定的是其他支持该规范的 agent写入位置会对应不同。第四输出结果并给出下一步提示。安装完 CLI 一般会打印“已安装 N 个技能”之类的信息有的版本还会提示你重启会话让配置生效。2.3 装完怎么验证真的装上了这是很多人忽略的一步。装完不验证等真正调用时才发现没生效排查成本反而更高。验证分三步走。# 1. 查看已安装技能列表 npx skills list # 2. 直接查看全局技能目录里有没有对应文件 ls ~/.claude/skills # 3. 进入项目目录查看项目级技能 ls .claude/skills第三步容易被忽略。如果安装时没加-g技能可能只装到当前项目的.claude/skills目录下。你换个项目打开 Claude Code技能就“消失”了。所以全局还是项目级安装在一开始就要想清楚如果这个技能是你整个工作流都通用的用-g如果只是某个仓库专用的就别加-g按项目隔离更干净。3. 多平台实战从 Claude Code 到 API 自建工作流3.1 平台一Claude Code 命令行模式Claude Code 是支持 Agent Skills 最直接的终端环境也是这套规范最先落地的场景。安装好技能包之后不需要在对话里提任何特殊口令经验是技能触发靠的是模型对技能的语义匹配。它会根据用户任务描述结合SKILL.md文件里的description字段判断是否要调用对应技能。实际操作时有个细节新装技能后最好重开一个会话窗口再测试。Claude Code 在启动时才加载技能列表和描述如果你是安装完直接在同一次会话里就开问它可能还没把新技能读进去导致你问半天也没触发。第一次触发成功之后你在对话里会看到模型开始频繁引用技能文件里的步骤类似“根据 XX 技能的流程我先需要你确认下面几个参数……”。看到这种对话模式就说明技能已经被正确加载了。3.2 平台二Claude 桌面应用桌面端和命令行的情况略有不同。桌面应用往往更讲究可视化技能的加载位置通常在全局用户目录下但不同版本的桌面端对技能的扫描时机不一样。我的实操经验是在桌面端使用技能前先确认应用已经升级到较新版本然后把技能文件放到对应目录完全退出应用重新启动再在新会话里测试。如果你发现桌面端始终不读取某个技能优先检查技能描述文件里有没有写错name字段。name只能包含小写字母、数字和连字符不能带中文、空格和下划线。这个字段一旦非法整个技能目录都可能被静默跳过日志里还不一定能看到警告。3.3 平台三第三方 AI 编码助手很多朋友问Cursor、Cline、Continue 这些工具能不能直接吃 Agent Skills答案比较微妙。现阶段不是所有第三方工具都原生完整支持 Anthropic 的 SKILL.md 规范。有些工具确实已经能读取SKILL.md文件并把它当成系统提示词的一部分加载有些工具则需要通过自定义指令、插件或 Agent 配置才能做到类似效果。判断一个工具是否支持不要光看宣传语直接做三个测试。第一查看它的工具调用接口里有没有“读取技能文件”之类的内部动作第二在项目根目录放一个最简SKILL.md看对话时它会不会主动引用第三检查它的配置目录里有没有skills目录约定。如果都没有别硬兼容最省事的方式是通过下一节的自建工作流把技能变成上下文内容直接注入。3.4 平台四自建 API 工作流如果你不想被某个特定工具绑定自建 API 工作流是终极方案。思路很简单Skill 文件本质是 Markdown你可以写一个脚本在每次调用模型 API 时把相关的SKILL.md读取出来拼接到系统提示词里。这样任何能调大模型 API 的平台都能复用同一套技能文件。import re def load_skill_text(skill_path: str) - str: raw open(skill_path, encodingutf-8).read() # 剥离 YAML frontmatter只保留正文指令部分 stripped re.sub(r^---\s*\n.*?\n---\s*\n, , raw, flagsre.S) return stripped.strip() system_prompt ( 你是一个工程助手请严格按以下操作规范执行。\n load_skill_text(./skills/video-style/skill.md) ) # 之后再把这个 system_prompt 传入任何兼容的大模型 API这种做法的好处是平台无关README、代码生成、视频脚本、文档处理都能用同一套技能文件。缺点是要自己处理上下文拼接和技能选择相当于把 CLI 工具替你做的那些事情手动实现了一遍。但反过来说这也意味着你真正常握了技能文件格式后面做任何平台的适配心里都有底。4. 一次完整调用演示让视频技能包真正干活4.1 准备一个具体任务理论讲再多不如真实跑一次。以sandai-org/vidmuse-skills为例装完技能包后进入 Claude Code 会话。这个仓库具体定义了哪些技能、技能名称叫什么以你实际安装后运行npx skills list看到的列表为准但用法是通用的。我们假设里面有一个面向短视频创作场景的技能比如“视频分镜生成”“镜头语言分析”之类。模拟一下用户输入我需要做一个 30 秒的产品宣传短片主角是一款便携咖啡机核心卖点是在办公室也能 30 秒做出意式浓缩。请帮我输出分镜脚本包含画面、景别、时长和旁白。4.2 技能被触发的完整对话链路如果技能加载成功模型不会直接抛一个普通回答而是会先从技能目录里找到匹配的技能文件然后按照里面的流程逐步展开。第一轮它会先承接任务并把它判断为“视频分镜生成”类任务然后开始执行技能里定义的步骤。技能里通常会要求先明确目标受众和视频时长所以它可能会反过来问你“这个短片主要投放在哪个平台抖音竖版还是 B 站横版”这是因为某些技能文件里写明了“先收集必要参数再开始创作”的规则。第二轮当你补充完平台信息后模型会按照技能里的分镜模板输出一张表格每一行包含镜号、画面内容、景别、时长、旁白文字。它不是随便写的而是严格贴合技能文件里的推荐格式。这个阶段最明显的标志就是输出结果比平时更稳定、更结构化。第三轮你提出“第三镜的旁白能不能更口语化”此时技能里的“迭代修改”规则继续生效模型会保留其他镜头不动只精修你指定的那一行最后还提示一句“如果需要我可以再生成一版不同风格的”。整个链路走下来模型的角色已经从“聊天助手”切换成了“按规范执行的创作执行者”。4.3 让技能效果更好的三个迭代技巧同一套技能包不同的人用出来效果差距很大。核心差在给模型的“上下文丰富度”上。分享我实测有效的三个迭代技巧。第一任务描述里尽量包含技能触发关键词。比如视频创作场景里直接点出“分镜”“镜头语言”“脚本”这类词模型匹配技能的准确率会明显提升因为description字段的匹配机制就是基于语义相似度的。第二给足约束条件。技能文件是通用流程你在对话里补充的时效、语气、平台、风格都会叠加到执行规则上。不要觉得技能存在就可以什么都不写技能保证下限你的补充决定上限。第三善用“重新描述需求”来修正。如果模型开始执行后发现方向不对不要只说“不对”直接把“技能第几步的输出格式不符合”点出来模型会重读技能文件并自我修正。实测下来这种方式比反复兜圈子高效得多。5. 自己动手写一个技能包并发布5.1 SKILL.md 最小可用结构看懂别人写的技能包之后自己写才是真正的掌握。一个最小可用技能包目录结构非常简单my-skill/ └── SKILL.mdSKILL.md的内容由两部分组成开头的 YAML frontmatter 和正文的 Markdown 指令。frontmatter 里必填两个字段name和description。name必须是合法的小写字母、数字、连字符组合description要写清楚这个技能会在什么场景下被触发描述写得越具体模型越不容易误判。正文部分写实际的执行流程、规则、输出格式。--- name: video-style-analyzer description: 分析视频作品的镜头语言和视觉风格输出结构化报告。适用于需要拆解短视频、广告片、宣传片的镜头、色彩、节奏等场景。 --- 当用户请求分析一段视频或脚本的风格特征时按以下步骤执行 1. 首先询问视频链接或脚本来源以及用户关注的分析维度。 2. 将分析拆分为四个维度镜头语言、色彩倾向、节奏感、声音设计。 3. 每个维度输出 3-5 条判断依据并附上具体时间码或脚本片段作为证据。 4. 最后给出 3 条针对该视频风格的模仿建议每条不超过 50 字。 注意只做客观分析不要评价内容本身的好坏。 输出格式使用 Markdown 表格展示四个维度的结论与证据。5.2 本地安装验证自己的技能写完之后先别急着发布在本地验证一遍。把SKILL.md放到一个目录里然后直接安装本地目录npx skills add ./my-skill --agent claude-code -g -y注意路径前的./不能省这是与安装 GitHub 仓库最大的区别。安装完成后按照前面 2.3 小节的方式验证文件已经出现在用户技能目录下再开一个全新会话测试技能是否能被正确触发。测试时要故意不直接提技能名而是用一句“帮我看看这个宣传片什么风格”的日常表述观察模型是否根据description自己找到了正确技能。如果没能触发第一个要改的就是description把它描述得更贴近用户的真实口吻。5.3 发布到 GitHub 让别人一条命令装走验证没问题后就可以把技能包推到 GitHub 仓库。推之前把目录整理干净建议在仓库根目录放一个README.md写清这个技能包包含哪些技能、使用场景、示例输入输出。然后把代码推到远程仓库后别人就能用开头那种命令安装你的技能包了npx skills add your-name/your-skill-repo --agent claude-code -g -y仓库命名尽量和技能内容相关方便别人通过npx skills add的功能联想。如果你需要维护多个技能不一定要每次建一个仓库可以在同一个仓库的不同目录下放多个技能文件CLI 会把它们全部识别出来。发布后记得自己在另一个目录里测试一遍“从 GitHub 安装”的完整流程防止推上去的仓库存在权限或路径问题。以 vidmuse-skills 这类技能包为参照组件化地维护一套自己的技能集合长期收益非常明显。6. 多平台实战常见问题与排查实录6.1 高频问题速查表实战中很多问题出现频率极高整理成一张速查表直接对着排查现象可能原因排查方向与解决安装提示成功但技能不生效没重启会话或-g参数缺失导致装到了项目目录重开会话用npx skills list和ls确认安装位置模型完全无视技能回答像普通聊天description写得泛泛模型无法匹配把触发场景、任务类型写得具体在提问时用技能关键词打开匹配线索技能目录存在但被静默跳过frontmatter 里name含有非法字符检查name是否只包含小写字母、数字、连字符桌面端看不到已装技能桌面端版本过旧或技能装到了项目级目录更新桌面端重新用-g安装并重启应用第三方工具提示技能不会被加载该工具未原生支持 SKILL.md 规范走 3.4 节 API 拼接方案把技能注入 system prompt同一技能在不同平台输出不一致各平台上下文窗口长度、模型版本不同技能正文控制精简关键输出格式写死在技能文件里6.2 我踩过的几个隐蔽的坑速查表之外的坑更隐蔽我挑三个最耽误时间的讲。第一个坑是“技能里的正文被截断”。技能文件写得越长越全面但不代表模型会一字不差读完。某次我写了一个特别详细的流程文档几万字塞进一个技能里结果模型执行到一半突然跳出技能逻辑开始自由发挥。后来我把技能拆成多个粒度更小的子技能每个只专注一件事执行稳定性立刻上来了。技能不是越长越好它更像是给模型看的“执行摘要”细节可以挂在附录但主流程必须短、清晰、可执行。第二个坑是“换行和编码问题”。在 Windows 上编辑SKILL.md时如果文件保存成了带 BOM 的 UTF-8frontmatter 解析偶尔会出问题虽然不一定会报错但技能就是加载不出来。我的做法是统一用 UTF-8 无 BOM 编码这是一个成本极低但能让你少折腾半小时的习惯。第三个坑是“技能名和技能内容对不上”。模型判定技能是否调用时主要依赖description而人类维护时常常只顾着改正文忘记同步描述。一旦描述过时模型就会在错误场景下调用或根本不调用技能。建议每次改完技能内容后都把description重新读一遍确认它仍然准确表达了这个技能的触发场景相当于给技能做了一个版本同步检查。写在最后的小建议Agent Skills 这套东西最有价值的点不是某一条安装命令而是让“调教 AI 的经验”第一次变成了可以分发、可以版本管理、可以跨平台复用的普通文件。我自己的使用习惯是先装几个现成的技能包跑通完整链路再拿自己最重复的那类需求开刀写成技能慢慢迭代。你要是实在不知道从哪里开始有个小技巧屡试不爽直接把“我希望你以后接到这类任务时这样处理……”这段需求丢给 Claude Code让它按 SKILL.md 的格式给你起草一版技能文件你再人工润色。这样生成的技能几乎不可能难用因为它本身就是从你真实需求反推出来的。等手上攒了三五个常用技能多平台切换又都验证通过你就会发现那些反复叮嘱 AI 的废话终于可以彻底删掉了。