Agent Skills 这个事儿从吴恩达的教程上线到现在几乎是我见过热度来得最猛的一波 AI 工程化概念之一。同行群里天天有人问你的 agent 写 skill 了没GitHub 上各种 skills 仓库也跟雨后春笋似的往外冒。我前前后后把主流的几个 agent 平台都折腾了一遍也顺着npx skills add这条命令把一个视频创作类的 skill 跑了完整流程。这篇东西就把这段时间的实操记录整理出来从概念拆解到多平台实战再到踩坑记录希望能帮你少走几步弯路。1. 先把概念掰开揉碎Agent Skills 到底是什么1.1 从一次翻书说起Skill 为什么不是 Prompt 也不是 MCP很多人第一次听到 Agent Skills 时脑子里蹦出来的问题是这不就是 prompt 吗或者这不就是 MCP 吗我一开始也这么想但真把它们放到同一个工作流里对比过之后才发现三者完全是不同维度的东西。你可以这样理解Prompt 是口头叮嘱你告诉 agent 一句帮我写个视频脚本要口语化一点剩下的全靠模型自由发挥效果不稳定。MCP 是递给 agent 一把扳手它给的是实时工具调用能力比如查数据库、发请求、操作外部系统解决的是手脚的问题。而 Agent Skills 是塞给 agent 一本书这本书会告诉它在面对某类任务时应该遵循什么样的步骤、使用什么样的模板、参考什么样的范例。换句话说Skill 封装的是做一件事的完整方法论。以视频创作领域的 vidmuse 这类 skill 为例它不只是告诉模型你要写脚本而是把脚本结构、分镜规则、运镜描述的写法、镜头语言注意事项、常见风格参数这些经验都打包进去。agent 拿到这个 skill 之后不管接到什么视频创作需求都知道该按什么顺序拆解、每个环节输出什么格式、哪些坑要避开。从底层机制上看Agent Skills 这个概念真正火起来和 Anthropic 在 Claude 生态里提出并推广的标准格式有很大关系。它的核心是一个SKILL.md文件这个文件里面有结构化的 frontmatter 描述区包含技能名称、功能说明、适用场景下面接着正文用自然语言描述执行步骤、决策规则和注意事项。模型在运行时会根据用户请求的语义去匹配技能描述如果觉得某个 skill 与任务高度相关就把SKILL.md当作上下文加载进来。这个按需加载的机制特别关键。它既不像把所有指令都塞进 system prompt 那样浪费 token又能在执行任务时给模型提供足够精细的指导。吴恩达在新教程里花了不少篇幅强调这一点给 agent 提供像人一样可查阅的操作手册比把注意事项全部记住然后再执行要可靠得多。1.2 你已经在用的 Agent 其实早就有 Skills 的影子如果你之前一直用 Claude Code、Codex CLI 或者 OpenAI 的各类 Agent 工具其实早就接触过和 Agent Skills 类似的机制只是它们没有统一叫这个名。比如 Claude 的 Projects 功能可以在每个项目里放一份自定义指令集和参考资料让 Claude 在处理该项目任务时优先遵循。Codex CLI 里的AGENTS.md文件本质上也承担了类似角色——它会告诉 codex agent 当前代码库的约定、代码风格、常见任务的执行方式。OpenAI 的 Custom Instructions 则是用户级的长期偏好设置和技能还不太一样但思路上有共通之处。Agent Skills 厉害的地方在于它把这些散落在各平台的实践给标准化了。以前你给 Claude 写一套行为规范到了 Codex 那边基本要推倒重来。现在只要把技能写成标准结构通过统一的命令就能在不同 agent 平台之间复用。这也正是我把标题定为多平台应用实战的原因——同一份技能资产能不能在不同 agent 上跑通直接决定了这套方案值不值得投入。2. 多平台生态哪些 Agent 支持 Skills怎么选2.1 主流 Agent 对 Skills 的支持现状先看一张我整理的支持情况表这是我在自己的机器上逐个验证过的结论Agent 平台Skills 支持形式体验成熟度适合场景Claude Code原生支持通过skills指令管理标准SKILL.md格式最高编码、写作、视频脚本创作、数据分析Codex CLI通过AGENTS.md 自定义指令近似实现中等GitHub 生态、代码库维护、自动化脚本Gemini CLI支持自定义指令与工具技能格式尚未完全统一中等多模态任务、Google 生态集成OpenAI Agents SDK支持通过 instructions 注入和 tools 扩展偏高开发者定制、服务端 Agent 部署Cursor通过.cursorrules等规则文件提供类似体验中等编辑器内辅助开发这里要特别说明一下我为啥把 Claude Code 放在体验最高这一档。因为 Anthropic 是SKILL.md标准格式的主要推动者Claude Code 对 skill 的发现、加载和切换都做了比较顺畅的原生支持。你在终端里可以直接安装一个 skill也可以把本地写好的技能目录挂载到配置里agent 在处理任务时会自动识别并加载相关技能。整个链路从创建、安装到使用都能在几分钟内跑通。Codex CLI 更多是用规则文件模拟技能。它的AGENTS.md是一个 Markdown 文件可以放在项目根目录或者用户目录下codex 在启动时会读取这些文件来理解项目约定。如果你把某个技能的完整操作手册写进AGENTS.md确实能达到类似效果但缺点是没有标准化的技能注册机制一个项目同时挂多个技能时管理和匹配都会变得笨重。OpenAI 这边如果你只是用 ChatGPT那确实没什么好折腾的。但如果你在用 OpenAI Agents SDK 开发自己的 agent 应用那其实可以通过instructions参数和自定义工具把技能手册注入到 agent 的指令上下文里。这种方式灵活但需要开发者自己实现技能的加载逻辑和匹配规则相当于白手起家。相比之下Claude Code 那种把技能文件往目录里一扔、命令一敲就能用的体验还是省心不少。2.2 多平台场景下的选型建议既然不同平台的 Skills 支持水平参差不齐那在实际项目中该怎么选我个人建议按任务类型来分。如果是写代码、搞数据清洗、做文本处理这类偏工程的任务Claude Code 配合正式 Skill 格式是首选因为它对技能的组织和使用都在同一个工作流里。如果是长时间在 GitHub 上折腾仓库、写 issue、跑 CI 脚本那 Codex CLI 本来就长在这里你需要做的就是把技能内容写成AGENTS.md的约定不用强迫自己套SKILL.md的格式。如果你是做视频、做内容创作这一类创意型任务状况又有不同。视频创作技能的输入输出比较多样有时候要生成脚本、有时候要出分镜表、有时候要写镜头描述有时候还要配合工具生成素材。这种场景下我建议用支持标准 skill 格式的平台因为技能文件里的分支判断和模板输出效果最好。用 vidmuse 这类视频创作技能的时候我在 Claude Code 里体验最顺。还要考虑一个重要因素如果你需要把技能共享给团队使用或者从一个平台迁移到另一个平台那么优先选择标准格式 可复用文件的方案。SKILL.md本身就是普通文本文件天然适合放进 Git 仓库做版本管理团队协作时可以像管理代码一样管理技能。而像.cursorrules这种和特定编辑器绑定的方案迁移成本就高了。3. 一条命令打通npx skills add 实战全记录3.1 命令逐段拆解别直接复制粘贴就跑现在很多人在分享 Agent Skills 的时候都会贴出这么一条命令npx skills add sandai-org/vidmuse-skills --agent claude-code -g -y第一次看到这条命令的人很容易不明所以就直接复制执行。事实上这条命令是把一个 GitHub 仓库里的技能集合安装到你本地的 agent 配置中让 agent 在后续对话里能自动识别并调用这套技能。它没做任何出格的事儿就是把远程仓库拉到本地、解析技能目录结构、然后注册到指定平台。为了不让你对着黑屏终端发懵我把每个关键部分拆开讲一遍。npx skills add调用的核心命令来自一个名为skills的 npm CLI 工具。它会去指定的 GitHub 仓库里找技能文件然后下载到本地并完成向目标 agent 的注册。这和我之前手动把技能目录复制到配置目录里的做法相比省去了大量手工操作。sandai-org/vidmuse-skillsGitHub 仓库定位符格式是拥有者/仓库名。这个仓库属于sandai-org组织仓库名含vidmuse从名字不难看出这是一套面向视频创作场景的技能集合video muse视频灵感。仓库里通常按目录组织多个技能比如视频脚本撰写、分镜拆解、运镜描述、剪辑节奏建议等等。你如果用的是别的技能仓库把这段替换成对应仓库地址就行。--agent claude-code指定目标 agent 平台表示把技能安装到 Claude Code 环境下。如果平时用 Codex可以改成--agent codex如果是在 OpenAI 生态里就改用对应平台名。这个参数决定了技能文件的存放路径和适配格式。-g以全局模式安装让所有项目都能使用这些技能而不只是当前目录生效。我平时在多个项目间切换全局安装更方便。-y跳过安装过程中的确认提示。执行时终端会逐条列出即将安装的技能、保存位置、目标平台等信息正常情况下确实需要回车确认-y就是帮你一路绿灯。注意不要把-y当成无脑选项。第一次安装时建议去掉它认真看一眼安装清单确认技能来源和保存路径确认无误后再决定是否全局安装。3.2 实操流程从零到能用的完整记录我在自己电脑上完整走了一遍安装流程环境是 macOSNode.js 和 npm 都已经装好Claude Code 也已经登录。整个过程大概三分钟。第一步我先在本地建了个测试目录然后执行了去掉-y的安装命令npx skills add sandai-org/vidmuse-skills --agent claude-code -g终端很快输出了技能清单显示该仓库包含若干个视频创作技能每个技能都有独立的名称、描述和版本号。确认之后安装程序开始拉取仓库内容然后逐个写入 Claude Code 的全局技能配置目录。在我这台机器上最终落到了~/.claude/skills/目录下。这个目录就是 Claude Code 运行时查找技能的地方里面每个子目录对应一个技能命名规则是技能名全小写加连字符。第二步验证安装结果。我直接输入claude进入 Claude Code 交互界面然后发了一个视频创作请求比如帮我写一个 30 秒的产品宣传短片脚本主角是一款咖啡机。Claude Code 在思考过程里明确提到了加载 vidmuse 技能说明技能识别已经生效。然后它按照技能里定义的脚本结构输出了包括开场画面、分镜、旁白、字幕建议在内的完整脚本方案效果比没有装技能时明显更专业。第三步单独把技能的目录结构看了一遍确认里面除了SKILL.md之外还有示例文档和参考素材。技能不是只靠一个描述文件硬撑的它会把常用的模板、案例、方法论都封装在仓库里agent 使用时按需读取这让生成内容的专业化程度提升了一个量级。有一点要提醒npx skills add这个工具本身还在快速迭代不同版本的命令参数可能会调整。我建议在正式使用时先执行npx skills add --help看看当前版本支持的参数再决定怎么传入。4. 从会用到会写制作一个自己的 Agent Skill4.1 Skill 的标准结构与格式解析装别人的技能只是第一步真正让你在这套玩法里拥有自主权的是能写出自己的 skill。一个标准的 skill 文件夹结构大概长这样my-skills/ ├── SKILL.md ├── reference/ │ ├── template-script.md │ └── examples/ │ ├── example-30s-video.md │ └── example-product-intro.md └── scripts/ └── generate-storyboard.py最关键的文件是SKILL.md所有技能元信息和核心指令都写在这里。它有严格的前言frontmatter格式用 YAML 写至少包含name和description两个字段。description尤其重要因为这是 agent 判断当前任务是否需要加载这个技能的核心依据。description 写得越精确、越包含关键词技能被正确触发的概率就越高。举个例子如果是一个口播脚本生成技能description 可以写成--- name: tiktok-script-writer description: Generate engaging short-form video scripts for TikTok, YouTube Shorts, and Reels. Includes hook creation, pacing advice, call-to-action suggestions. Use this skill when the user asks for a social video script, viral video outline, or short-form content planning. ---我把短句、视频脚本、社交媒体、爆款这类关键词都放进了 description这样 agent 在处理相关请求时就能通过语义匹配快速定位这个技能。如果 description 只写写作助手那基本等于没写——agent 很可能在真正需要它的时候忽略它。SKILL.md正文部分我一般按三个板块组织执行步骤、输出模板、注意事项。执行步骤要像菜谱一样明确比如第一步收集产品信息第二步确定目标平台第三步套用脚本结构第四步生成分镜表。输出模板直接给 Markdown 结构agent 会照着这个格式输出结果。注意事项则写一些容易出错的经验比如脚本前 3 秒必须有强 hook旁白不要超过 180 字/30 秒。参考文件目录reference/放的是更详细的背景资料和示例。技能加载到上下文时SKILL.md是必读项但参考目录是按需读取的模型感觉到需要看示例的时候才会去翻。这种设计能在保证技能指导质量的同时控制 token 消耗。4.2 分步制作一个视频创作类 Skill我以一个口播视频脚本生成器为例说说我的实际操作。这个技能的目标是当用户给出产品描述和目标平台时自动生成一条结构完整、可直接拍摄的口播视频脚本。第一步建目录和文件。mkdir -p voice-script-writer/reference cd voice-script-writer touch SKILL.md第二步写SKILL.md。description 部分我写得很具体把常见的使用场景都列进去了。正文部分我给出了一个标准的视频脚本生成流程明确要求 agent 依次完成以下步骤收集产品核心卖点、确定目标受众、选择平台适配的脚本风格、撰写 hook、展开正文、设计结尾引导。然后我在输出格式中定义了脚本的标题区、参数区、逐段内容区和拍摄提示区agent 会严格按照这个模板来。第三步在reference/里放一个优秀脚本示例。我挑选了一个之前表现较好的 30 秒带货脚本加了注释标明每一段对应什么功能。这个示例文件的存在让 agent 在不确定好脚本应该长什么样时有一个参考锚点生成的脚本质量明显更稳定。第四步测试。我在 Claude Code 里把技能目录挂上然后输入帮我写一条 30 秒的挂耳咖啡口播脚本目标平台是抖音希望突出便携和香气两个卖点。Claude Code 自动加载了技能按模板产出了完整脚本。和没装技能相比输出内容的结构清晰度、文案节奏感、镜头提示完整性都有显著提升。实操心得写完技能之后一定要在至少两个平台上测试一遍。同一个SKILL.md在 Claude Code 里表现好不代表在别的平台也能被正确解析。有些 agent 对 Markdown 的处理方式有细微差异比如对 H2 结构的层级识别、对代码块的引用方式这些都可能导致最终的输出格式变形。4.3 多平台兼容的发布与分发当你的技能在本地跑通之后下一步就是把它发布出去让团队甚至开源社区都能使用。技能的发布形式非常简单把整个技能目录推到一个 Git 仓库然后在仓库根目录的README.md里写清楚每个技能的用途、安装命令和使用示例。仓库结构建议按多技能集合来组织my-skills-collection/ ├── README.md ├── 01-video-script/ │ ├── SKILL.md │ └── reference/ ├── 02-social-copy/ │ ├── SKILL.md │ └── reference/ └── 03-data-analysis/ ├── SKILL.md └── scripts/发布之后别人就可以通过npx skills add命令来安装你的技能了。整个过程和我前面安装 vidmuse-skills 的流程完全一致。这里有一个非常容易被忽略的关键点仓库里技能的目录命名不要太随意。因为很多 agent 在解析技能名时会直接使用目录名所以尽量用全小写加连字符的格式比如video-script-writer不要用中文、空格或下划线。技能名是全局标识符一旦用了奇怪的字符安装时很容易出现解析错误。5. 实战踩坑我在多平台安装与使用 Skills 时遇到的问题5.1 最常见的五个坑及排查这一路下来我在多平台安装、使用技能时踩了不少坑。我整理成了一张速查表这些基本覆盖了新手最常遇到的五类问题问题现象可能原因解决办法npx skills add执行后长时间卡住网络问题导致 GitHub 仓库拉取超时检查网络连接确认能正常访问 GitHub重试命令必要时配置国内镜像安装时报command not found: skillsNode.js/npm 未安装或版本过低升级 Node.js 到 18 以上重新安装 npm 包agent 不识别已安装的技能技能 description 写得太模糊模型没判断出需要加载重写 description加入更多任务相关关键词和触发场景技能输出格式和预期不符目标的 platform 参数传错了安装时确认--agent参数不同平台技能目录与解析规则不同技能安装成功但对输出没影响技能文件权限不对agent 读取不了检查技能目录和文件的读取权限用ls -la查看第一个坑最让人头疼。npm 工具在拉取远程仓库时如果所在网络环境对 GitHub 的访问不稳定就可能长时间没有任何反馈。我当时第一次执行时等了快两分钟都没动静一度以为命令卡死了。后来把终端切到详细日志模式才发现它一直在重试网络请求。解决方式很简单因为skills这个工具本身支持通过环境变量配置代理但我个人更建议直接找一个网络稳定的时候安装。第四个坑需要重点说说。我在测试 Codex CLI 的时候特意把--agent参数传成了claude-code结果技能虽然装上了但 Codex 根本没有任何反应。后来发现 Codex 有自己的配置读取机制它不会主动去~/.claude/skills/目录找技能。要让 Codex 使用技能得把技能的核心指令提炼成AGENTS.md放在项目根目录下。这说明同一份技能、不同平台不同适配方式不是一句空话。5.2 让 Skill 稳定多平台复用的小技巧针对多平台复用这件事儿我总结出几条真正管用的经验。第一个技巧是给同一个 skill 提供多份平台适配文件。如果你希望一个技能同时在 Claude Code 和 Codex 上使用可以在仓库里同时维护SKILL.md和AGENTS.md版本的说明文档。虽然核心方法论一样但每个平台对指令格式的偏好不同稍微做一下适配效果会好很多。第二个技巧是严格控制SKILL.md的篇幅。很多人在写技能时会把能想到的所有细节都塞进去结果一个文件好几千字。但 agent 加载技能时会读取全部内容文件太大会挤占上下文窗口反而影响生成质量。我一般把核心执行步骤控制在 500 行以内更详细的背景材料和示例放进reference/让 agent 按需读取。这样既保证了核心逻辑完整又不会无谓地消耗 token。第三个技巧是写技能时尽量用行为指令而不是风格描述。与其写生成的内容要有创意不如写脚本开头 3 秒内必须包含一个反常规问题或视觉冲击画面。agent 对具体可执行的指令理解得更好对抽象形容词的理解则容易走偏。语言上多使用动词开头的短句少用修饰性的长句套话。6. 跟着吴恩达学 Agent Skills课程里的干货与我的学习路线6.1 课程核心要点提炼吴恩达的 Agent Skills 教程一上线就刷屏火的原因很简单他把 Agent Skills 从概念炒作落到了可操作的方法论上。我花了一个周末把主要内容过了一遍感觉核心要点可以提炼成三块给技能写精准描述、用动态指令让技能可迁移、用多技能协同构建复杂工作流。第一块给技能写精准描述很多人觉得不就是在文档开头写一段话嘛但吴恩达强调的是描述就是技能的触发开关。模型在接收到任务时会先判断当前任务与已有技能的匹配度而判断依据主要是description。如果你把描述写得太宽泛比如帮助用户写作那模型在做任何写作任务时都可能试着加载这个技能造成大量无效调用如果你写得太狭窄又会错过真正该触发的时机。课程里给了一个练习方法把同一段技能描述分别喂给多个 agent看它们在什么场景下会触发这个技能然后根据结果不断调整措辞。第二块动态指令指的是在技能文档里使用变量和条件判断。比如你可以定义当目标平台为抖音时采用以下节奏模板当目标平台为 YouTube 时采用另一种模板。模型在执行时会根据实际输入选择对应的指令分支这样一份技能就能覆盖多个场景。这个概念和我做多平台适配的思路非常契合只不过吴恩达是在技能内部做分支而我们是在平台外部做适配。第三块多技能协同让我比较有启发。单个技能解决单个问题但真实任务往往是复合的比如做一条视频既需要脚本写作技能又需要分镜技能还可能需要数据分析技能。吴恩达建议把技能设计成可以互相调用的模块比如脚本技能生成的输出结构直接作为分镜技能的输入格式。这其实就是一种面向 agent 的函数组合思维。6.2 结合课程内容完善自己的 Skill 工作流学完课程之后我马上调整了自己的技能工作流。之前写技能的时候能用就行是我的标准但课程里提到的技能质量评估让我开始给每个技能加上了测试步骤用一个标准输入去测试技能记录输出结果然后判断是否达到预期。我会把测试样例和输出样例都放进技能仓库的tests/目录这样每次修改技能后都能快速回归。另外我开始把多个技能按任务链路组织。比如我之前单独写了脚本生成分镜拆解镜头描述三个技能现在我会在脚本生成技能的结尾处自动输出一个高度结构化的脚本 JSON这个 JSON 可以直接作为分镜技能的输入。这种输出即输入的衔接方式让多个技能真正协同起来而不是各干各的。课程里还有一个观点对我触动很大技能不是写一次就完事的静态文档它应该像代码一样持续迭代。每次使用技能时如果发现输出质量不达标我都会回头检查是 description 写得不够精准还是执行步骤描述得不够清晰或者是参考示例不太匹配当前场景。找到问题改完就重新测试。这种使用—反馈—迭代的循环才是技能效果持续提升的关键。7. 最后再分享一点个人的实操体会折腾 Agent Skills 这几个月我最深的感受是这套玩法真正的价值不在多了一个新工具而在它把 AI 应用开发的重心从调模型拉回到了沉淀方法上。以前要让 agent 稳定输出高质量的行业内容要么堆 prompt 技巧要么反复微调现在只需要把行业经验整理成结构化的技能文档让 agent 在需要时查阅执行。这种经验即代码的思路对整个内容创作和软件工程领域来说都是效率上的一次明显升级。如果你现在刚开始接触我的建议是别急着写自己的技能先把视频创作类的成熟技能装上让 agent 在日常工作里跑一段时间感受一下有技能和没技能的差别。等到你对技能的结构、触发方式、输出模式都有了直观理解之后再动手写自己的第一个SKILL.md。从克隆、修改到发布整个过程其实比想象中简单只要你愿意多试几遍、多调整几次 description就能体会到这套体系的真正威力。