1. Agent Skills 到底是什么为什么值得花时间学1.1 一颗技能子弹从“工具调用”到“随身技能”最早注意到 Agent Skills 这个概念是因为吴恩达的 AI Cursor 系列教程。他反复强调一个观点别再把所有东西都塞进 system prompt也别动不动就上 MCP 服务器很多重复性工作其实可以打包成一个“技能”让 Claude 按需调用。后来我试着把日常工作里的重复任务一个个封装成 skills从 Claude Code 到 Claude Desktop 再到 Cursor 全部接到一起才发现这条路是真的实用。如果用一句话说清楚 Agent Skills它是一组“自然语言说明书 可选代码脚本”的集合放在一个固定的文件夹里模型在需要的时候读到说明就知道自己能做什么、按什么步骤做、需要调用哪些脚本完成操作。你可以把它理解成发给 AI 的“岗位培训手册”——平时不占记忆拿到任务时翻开对应页码照着执行。这个设计和传统 prompt 工程最大的区别在于“按需加载”。之前我们习惯把所有指令、规则、示例都堆在 system prompt 里模型每次调用都要读一遍既浪费 token又容易互相干扰。Skills 是放到一边的模型先理解用户请求判断这件事是否匹配某个已安装技能的描述匹配到才会去读它的 SKILL.md并按里面的流程走。所以它能做到“技能再多也不拖慢主对话”这也是它在多平台场景下表现稳定的核心原因。1.2 吴恩达为什么反复推荐核心价值在哪吴恩达在多个公开课程和直播里专门拆解过 Agent Skills 的写法他的推荐理由很直接开发门槛低、复用性高、跨平台友好。相比微调模型或者搭一套完整的 Agent 框架写一个 skills 包的投入简直微不足道——一个文件夹、一个 Markdown 文件再加上几段脚本就能让 Claude 多一项可靠能力。我看完他那套教程后的复盘是Agent Skills 并不是什么高深理论它更像一套“实践公约”。Anthropic 定义了目录结构和 SKILL.md 的格式社区就按这个约定贡献了大量技能包你直接拉下来就能用不用自己从零造轮子。举个例子有人做视频内容直接安装vidmuse-skills里面通常已经包含了脚本生成、分镜拆解的说明有人做数据分析装一个数据分析技能的包Claude 就能按规范完成清洗、统计、图表输出。这里面有一个没被广泛提到的细节吴恩达推荐的顺序一般是“先做自己的技能再去社区的技能库找现成的”。因为自己封装技能的过程实际上是在把工作流里的隐性经验变成显性规则这比单纯安装别人技能包带来的帮助大得多。我后来也是这么做的先是装现成的跑通然后拆开看结构再模仿着写自己工作流的技能前后不到一周就顺手了。1.3 谁适合用什么时候该用它说实话不是所有人都需要立刻上 Agent Skills。如果你是偶尔让 AI 写个邮件、做张表那直接对话就够了。但如果你满足下面任何一条它就值得上手你在用 Claude Code、Cursor、Claude Desktop 做日常开发或内容生产且发现同样的要求反复解释你的工作流里有固定套路比如“每次写完代码都要检查一遍边界条件”“每篇文章都要按固定结构输出摘要”你希望团队里的 AI 行为一致而不是每个人手动写一段五花八门的系统提示词多平台应用是我体验最深的场景Claude Code 里它能作为原生技能直接触发Claude Desktop 里通过配置文件也能塞进去Cursor 则可以通过规则文件间接复用甚至连 OpenCode 这类开源工具也能接入同一套技能目录。也就是说一份技能包可以在多个平台之间反复横跳真正实现“写一次到处跑”。这篇文章接下来的所有内容都是围绕“一份技能包多端复用”这件事展开的。2. 拆开看核心机制SKILL.md 与技能包的文件结构2.1 SKILL.md 是灵魂自然语言说明书如果你打开任何一个 Agent Skills 技能包第一眼看到的肯定是SKILL.md。它不写代码而是用自然语言描述这个技能是干什么的、在什么场景下触发、有什么约束。对模型而言这份 Markdown 就相当于“工作手册”模型能不能正确判断“我该不该用这个技能”完全取决于这份手册写不写得好。我在反复尝试后总结出 SKILL.md 最理想的结构是四段式第一段一句话说明技能用途尽量包含关键词方便模型快速匹配第二段说明这个技能在什么情况下该用、什么情况下不该用避免误触发第三段给出具体的执行步骤最好按序号拆开复杂步骤要写判断条件第四段列出依赖工具、脚本用法、输入输出格式以及常见注意点这里给你一个示例开头是我做视频封面摘要时写的# VidMuse 封面摘要生成技能 在用户需要为一期视频生成封面方案或内容摘要时使用。 适合的场景视频发布前需要设计封面文案、提取视频主题要点。 不适合的场景用户只是简单询问视频内容不需要输出封面建议。这份文件不需要写得多华丽但一定要“机器友好”。模型不像人能领会潜台词它靠语义匹配决定是否触发所以你在描述使用场景时最好把“用户可能会怎么说”都列出来比如“帮我出个封面”“这期讲什么的”“做个视频摘要”这类句子写清楚命中率会高很多。这也是我对比过多个技能包之后发现的共同点那些装了不会触发的技能九成都是 SKILL.md 里场景描述写得模棱两可。2.2 辅助脚本把重复劳动交给代码SKILL.md 解决“模型知道该怎么做”的问题辅助脚本解决“事情能不能稳定做完”的问题。比如你要让 AI 总结一篇播客转录稿如果全靠模型自己读全文、归纳重点每次发挥可能都不一样但如果你在技能里放一个 Python 脚本规定它按固定逻辑切分文本、统计词频、提取关键句模型只需要调用脚本再基于脚本输出做润色结果就稳定得多。所以一个规范的技能包目录通常长这样my-skill/ ├── SKILL.md ├── scripts/ │ ├── summarize.py │ └── split_text.py └── reference/ └── template.mdscripts目录放可执行代码reference目录放参考材料比如输出模板、评分标准、案例样本。模型在按照 SKILL.md 执行时如果需要读参考材料它会自己去 reference 目录里翻如果要做计算或文本处理它会执行 scripts 里的脚本。有一点必须提醒脚本里的逻辑要尽量“原子化”。你宁可写三个小脚本每个只负责一件事也不要写一个 500 行的大脚本因为模型定位和调用大脚本时容易出错。我自己早期犯过的错误就是把“抓取链接、清洗内容、生成摘要”全写在一个文件里结果模型经常搞不清该传什么参数后来拆成三个脚本一次报错率立刻降下来了。2.3 Skills 和 MCP 的差别别再混为一谈很多人把 Agent Skills 和 MCPModel Context Protocol放在一起比较其实它们解决的完全不是一类问题。用生活化类比来说MCP 像是给电脑插上 U 盘它提供的是“连接能力”——连数据库、连浏览器、连内部系统重点在获取外部实时数据而 Skills 像是给员工发操作手册它提供的是“做事方法”——连不连外部系统无所谓重点是把一套流程稳定执行出来。MCP 的核心是服务器你需要配置 endpoint、定义工具、管理鉴权模型通过协议去动态发现和调用这些工具。Skills 的核心是文件和说明本地安装、按需读取、不依赖网络服务。所以如果你只是想让 AI 学会“按固定格式写周报”那完全没有必要上 MCP如果你想让它直接查公司数据库里的销售额那 Skills 做不了得用 MCP。这个区分在实际配置时至关重要。因为多平台场景下MCP 服务器每换一个客户端就要重新配置一遍甚至连鉴权方式都可能不一样而 Skills 只是一个文件夹你把它复制到对应平台的技能目录就能用分发成本低得多。这也是“多平台实战”里我最看重 Skills 的原因——它天生就是可移植的。3. 多平台应用实战从 Claude Code 到 Desktop 到 Cursor3.1 用一条命令装好首个技能包npx skills add 全参数解析最开始上手时我建议直接安装现成的技能包跑通流程。社区里最常见的安装命令长这样npx skills add sandai-org/vidmuse-skills --agent claude-code -g -y这条命令看着短但每个参数都有讲究我拆开讲。npx skills是 Anthropic 官方推出的 skills 命令行工具npx会自动下载并执行它不需要你先全局安装。add sandai-org/vidmuse-skills表示从sandai-org这个 GitHub 组织下把vidmuse-skills这个仓库当作技能包添加进来。这里要留意不是所有 GitHub 仓库都能直接作为技能源仓库根目录下必须有SKILL.md文件才行。--agent claude-code指定的是“这个技能要装给谁用”。不同平台对技能目录的要求不一样官方 CLI 目前支持claude-code、desktop、cursor、opencode等多个目标。-g是全局安装的意思如果不加技能默认只装到当前项目的.claude/skills目录。-y则是跳过交互确认适合脚本化批量安装。完整安装后Claude Code 会在启动时自动扫描技能目录不需要重启客户端也能识别到新技能这是我实测过很多次的结论。如果你只想装到当前项目里方便团队共享同一套技能配置把-g去掉就行。装完后在项目目录下会生成.claude/skills/vidmuse文件夹提交到 Git 仓库后团队成员 pull 下来就能直接用技能配置的版本管理也顺带解决了。3.2 Claude Desktop 的配置方法Claude Desktop 虽然叫“桌面版”但技能目录和 Claude Code 并不共享。很多人第一次接触时在这里卡住明明在 Claude Code 里装好的技能切到 Desktop 却找不到。原因是 Desktop 读取的是用户级配置目录下的skills文件夹而不是项目目录里的。按照官方规范Claude Desktop 的技能目录是~/Library/Application Support/Claude/skills/ # macOS %APPDATA%\Claude\skills\ # Windows你只需要把技能包整个文件夹复制到这个目录下重启 Claude Desktop 就能生效。这里有一个坑Desktop 的模型有时不会主动调用技能因为它没有一个明确的“用户让 AI 用技能”的上下文。我的经验是在对话里直接说“用 VidMuse 技能给这个视频出个封面方案”命中率会明显提高。原因是 Desktop 界面上没有像 Claude Code 那样暴露/skills命令入口只能靠语义触发所以你的指令里最好带上技能名或功能描述。如果你嫌手动复制麻烦可以写一个同步脚本用软链接把 Claude Code 的全局技能目录和 Desktop 的技能目录映射起来这样两边始终用同一套文件。我个人就是这么干的软链接建好后再也没有“装了两份、改了一处忘了另一处”的烦恼。3.3 Cursor 与 OpenCode 的接入思路Cursor 官方对 Agent Skills 的支持方式很轻量它通过.cursor/rules目录来加载规则文件而 Agent Skills 的 SKILL.md 本质上也是一种规则。所以要让 Cursor 用上同一个技能包最简单的方法是把技能包里的SKILL.md复制到.cursor/rules目录下或者写一个引用它的封装规则。但我实测发现直接复制有个问题SKILL.md 里如果写了要调用scripts/里的脚本Cursor 并不会像 Claude Code 那样自动找到相对路径。所以更好的做法是在.cursor/rules/vidmuse.mdc里写清楚技能文件夹的绝对路径并告诉 Cursor “遇到相关任务时阅读指定路径的 SKILL.md 并按其执行”。这样既保留了技能包的原始结构又能在 Cursor 里稳定触发。OpenCode 的接入稍微灵活一些它的插件体系支持加载本地目录。我参考社区方案在 OpenCode 的config里注册了一个功能模块启动时读取SKILL.md并注入上下文效果和 Cursor 类似。需要提醒的是OpenCode 的生态变化比较快如果你用的是较新版本建议优先看官方文档确认是否原生支持 Agent Skills避免花时间配了半天发现接口已经变了。3.4 多平台共用一套技能库的目录规划既然是讲多平台实战最理想的状态就是“一套技能文件三种平台共享”。我的做法是建立一个独立的技能仓库结构大致如下my-skills-repo/ ├── skills/ │ ├── vidmuse/ │ ├── weekly-report/ │ └── code-review/ ├── install-claude-code.sh ├── install-desktop.sh └── cursor-rules/ ├── vidmuse.mdc └── weekly-report.mdcClaude Code 直接用npx skills add安装或通过项目级路径引用Desktop 用软链接映射到全局技能目录Cursor 则通过cursor-rules里的引用文件桥接。配好之后你在任何一端更新技能内容其他平台下次触发时读到的都是同一份最新文件。关于目录规划我有一条重要心得技能包里不要写死任何绝对路径。因为 Claude Code、Desktop、Cursor 的技能目录路径完全不同一旦 SKILL.md 里写了C:\Users\xxx\...换台电脑立刻失效。所以路径引用一律用相对路径或者干脆在 SKILL.md 里只写“脚本位于 scripts/ 目录下由模型自行定位”让模型根据当前环境去探索。很多自称“多平台兼容”的技能包实际做不到这一点装到第二个平台就报错十有八九是路径写死了。4. 自己动手写一个 Agent Skill从零到可复用4.1 需求拆解做一个实用的视频脚本生成技能光会装别人写的技能包只能算入门。把工作流里最常用的一套流程封装成自己的技能才算真正掌握了 Agent Skills 的精髓。我以“短视频脚本生成”为例完整走一遍写技能的过程。先拆需求平时做短视频需要先定主题、列大纲、写逐字稿、配画面建议这个流程每次都要重复而且不同账号的风格要求还不一样。如果能在技能里定义好这几个步骤并让 AI 按固定格式输出效率能提升不少。我决定做一个技能包命名为short-video-script输出格式统一为“主题一句话 开头钩子 分段内容 画面建议”。这个技能不需要连外部 API也没有复杂的数据处理核心就是“按照 SKILL.md 里的规则产出结构化内容”所以对脚本的要求很低。我甚至不需要写任何 Python 代码纯 Markdown 就够。但为了演示辅助脚本的用法我还是加了一个format_checker.py用它检查输出是否包含所有必要字段避免模型漏写画面建议这种常见问题。4.2 SKILL.md 的写法与注意事项技能包的核心还是SKILL.md。我写好的版本大致是这样的结构# 短视频脚本生成技能 当用户需要为一期短视频生成脚本、逐字稿或拍摄大纲时使用。 触发词写个短视频脚本、帮我出个视频大纲、这期视频怎么拍。 不适合场景用户已经有完整脚本只需要润色措辞。 ## 执行步骤 1. 询问视频主题、目标观众、时长要求如用户未提供按默认值处理主题用户最新对话主题观众泛大众时长90秒 2. 输出“主题概括”不超过30个字 3. 输出“开头5秒钩子”用疑问句或反常识结论吸引注意 4. 将内容拆成3-5段每段给出口播文案和对应画面建议 5. 在结尾输出“行动号召” 6. 运行 format_checker.py 检查字段完整性缺少字段时补齐 ## 注意事项 - 语言风格默认为口语化禁止书面语 - 每段口播文案不超过80字 - 画面建议需要用括号标注方便拍摄时对照写 SKILL.md 时最容易忽略的一个细节是“模型要能判断什么时候不触发”。很多人在描述的时候只写了“什么时候该用”完全没写“什么时候不该用”结果模型容易把普通对话也套进技能流程里。我在上面示例里特意加了“不适合场景”这一行这种显式负例对模型非常有帮助它的误触发率能下降一大截。另外执行步骤不要写得太抽象。像“分析用户需求并输出脚本”这种描述等于没说模型不知道该按什么顺序做。好的步骤应该像菜谱一样先干什么、再干什么、什么条件做什么判断每一步都是可执行的指令。我自己迭代下来的体会是把步骤写得越机械输出质量越稳定。4.3 测试、迭代与分发写完之后测试环节不可跳过。我一般分三个层次来测第一层直接在当前平台对话里触发看模型是否会自动读取 SKILL.md第二层连测 5 个不同主题检查输出是否都符合格式要求第三层把技能包复制到 Claude Desktop 和 Cursor确认跨平台可用我在测试short-video-script时发现一个问题在 Cursor 下模型总能正常触发但输出经常漏掉“画面建议”原因是 Cursor 对 Markdown 里括号内容的重视程度不如 Claude Code。后来我在 SKILL.md 里把“画面建议”单独加了一行强调并让格式检查脚本在缺字段时打印提示问题才算解决。这也说明不要指望一份 SKILL.md 在所有平台表现完全一致你需要在每个目标平台上各测试一轮然后针对性补强描述。分发方面最省事的做法是把技能包推到 GitHub 仓库然后让别人用npx skills add 你的用户名/仓库名 --agent claude-code -g -y来安装。发布前记得确认仓库根目录有SKILL.md并且不要塞入无关的大文件因为别人是用 Git 拉取的仓库体积直接影响安装速度。如果你不想公开也可以放到私有仓库npx skills add同样支持带 token 的私有仓库地址。5. 常见问题与排查技巧实录5.1 模型不调用技能怎么办这是问得最多的问题。装好了技能但对话时模型完全不理会好像技能不存在一样。根据我多次踩坑的经验优先排查顺序如下先看 SKILL.md 里的触发描述是否足够具体。如果技能说明只写了一句话模型在快速判断时很容易漏掉它。解决办法是像前面说的列出多种用户可能的表达方式并在“不适合场景”里写清楚不属于自己职责的情况让模型的匹配判断有据可依。再看平台对技能目录的扫描路径是否正确。不同平台读的不是同一个目录Claude Code 读项目级.claude/skillsDesktop 读用户级~/Library/Application Support/Claude/skillsCursor 则靠 rules 文件桥接。很多人装好技能后模型不识别最后发现就是路径搞错了。最后检查模型版本和平台版本。Agent Skills 依赖模型对“按需读取说明文件”的理解能力版本较旧的模型可能不会主动去读技能目录。遇到这种情况只能在对话里直接指定“读一下某个技能文件夹里的 SKILL.md”先确认技能文件本身没问题再考虑升级模型或客户端。5.2 安装路径和加载不到的问题npx skills add装完后可以用这几条命令快速确认技能是否真的装到了预期位置npx skills list --agent claude-code ls ~/.claude/skills/ # 全局技能目录 ls .claude/skills/ # 项目级技能目录如果skills list能看到技能但对话里不生效多半是平台的“技能加载开关”没打开或者用了多配置文件导致目录被覆盖。Claude Code 的配置文件是递归合并的如果你的项目根目录和子目录里有多份配置后加载的可能会覆盖先加载的技能目录设置。排查思路就是把自定义配置尽量收敛到一个地方避免多处声明同一项。另外技能包文件夹命名不要带空格和特殊字符否则模型在解析路径时容易出错。这是我早期遇到的一个真实问题技能文件夹叫my-skills-final-v2看起来没问题但里面包含的引用文件名带了括号和空格导致脚本调用时路径解析失败。后来统一改成短横线命名问题立刻消失。5.3 多平台配置注意事项多平台复用时最烦人的不是功能差异而是“配置分散”。Claude Code 的配置在项目里Desktop 的配置在用户目录Cursor 的配置在.cursor文件夹下三个地方互不相通很容易出现“在一端改了技能另一端还在用旧版”的情况。我的解决办法是围绕一个中心技能仓库做软链接分发。所有技能文件只维护一份放到~/skills-central/下然后让 Claude Code、Desktop、Cursor 各自加载这个目录的链接或引用。这样更新技能时只需要改中心目录一份所有平台下次触发时自动用到新版本。唯一要注意的是如果你有技能脚本依赖外部依赖包比如 Python 库就必须在每个平台的运行环境里都装好否则会出现“Claude Code 能跑、Desktop 报 module not found”的尴尬局面。5.4 技能包安全性与来源审查社区里的技能包数量增长很快但质量参差不齐安全性必须放在心上。技能包里的脚本会在你的本机执行和直接运行别人发的脚本没有本质区别。我的习惯是安装社区技能包后先打开SKILL.md和所有脚本文件通读一遍确认没有可疑操作再在测试项目里跑一次。具体看哪些东西重点关注脚本里是否有网络请求、环境变量读取、文件删除等高风险操作。不是说有这些操作就不能用而是你得清楚它在做什么。比如一个视频处理技能要调用 ffmpeg这很正常但如果它在启动时就往某个陌生地址传数据那就得警惕了。多平台环境下这个风险会被放大因为你在三个平台都装了同一份技能等于给了它三个执行入口。另外一个容易忽略的点是技能包的版本锁定。如果直接使用 GitHub 仓库的默认分支作者更新代码后你下次安装时拉到的可能是新版本。对于关键生产环境的技能建议锁定仓库的 commit hash 或 tag避免“昨天还能用今天莫名出错”的问题。我自己维护技能仓库时每次稳定版本都会打 tag并在文档里写明推荐安装的版本号这样团队内部使用不会互相踩踏。最后分享一点个人体会我大概是花了一周时间把 Agent Skills 从“听说过”到“日常离不开”的。最开始是被吴恩达教程里那句“把技能封装成文件”打动后来真正用起来才发现它真正的价值不是省 token而是强制我把自己模糊的工作流变成了可复用的规则。这个过程的收获甚至超过了技能本身的效率提升。如果你现在正处在“刚听完概念、准备动手”的阶段我的建议很直接先找一个重复次数最多、规则最明确的小任务照着文章里的结构写一个技能包测试通过后再往多平台铺开。不要一上来就追求大而全那只会让你迷失在配置细节里。所有所谓踩坑经验本质都是从一个足够小的技能开始、逐步扩展的过程中积累出来的。希望这篇实战记录能帮你少走点弯路。 
长河君 · 2026/9/12 4:38:09 · 阅读 1.2k Agent Skills实战指南：用SKILL.md打造跨平台AI技能包
1. Agent Skills 到底是什么为什么值得花时间学1.1 一颗技能子弹从“工具调用”到“随身技能”最早注意到 Agent Skills 这个概念是因为吴恩达的 AI Cursor 系列教程。他反复强调一个观点别再把所有东西都塞进 system prompt也别动不动就上 MCP 服务器很多重复性工作其实可以打包成一个“技能”让 Claude 按需调用。后来我试着把日常工作里的重复任务一个个封装成 skills从 Claude Code 到 Claude Desktop 再到 Cursor 全部接到一起才发现这条路是真的实用。如果用一句话说清楚 Agent Skills它是一组“自然语言说明书 可选代码脚本”的集合放在一个固定的文件夹里模型在需要的时候读到说明就知道自己能做什么、按什么步骤做、需要调用哪些脚本完成操作。你可以把它理解成发给 AI 的“岗位培训手册”——平时不占记忆拿到任务时翻开对应页码照着执行。这个设计和传统 prompt 工程最大的区别在于“按需加载”。之前我们习惯把所有指令、规则、示例都堆在 system prompt 里模型每次调用都要读一遍既浪费 token又容易互相干扰。Skills 是放到一边的模型先理解用户请求判断这件事是否匹配某个已安装技能的描述匹配到才会去读它的 SKILL.md并按里面的流程走。所以它能做到“技能再多也不拖慢主对话”这也是它在多平台场景下表现稳定的核心原因。1.2 吴恩达为什么反复推荐核心价值在哪吴恩达在多个公开课程和直播里专门拆解过 Agent Skills 的写法他的推荐理由很直接开发门槛低、复用性高、跨平台友好。相比微调模型或者搭一套完整的 Agent 框架写一个 skills 包的投入简直微不足道——一个文件夹、一个 Markdown 文件再加上几段脚本就能让 Claude 多一项可靠能力。我看完他那套教程后的复盘是Agent Skills 并不是什么高深理论它更像一套“实践公约”。Anthropic 定义了目录结构和 SKILL.md 的格式社区就按这个约定贡献了大量技能包你直接拉下来就能用不用自己从零造轮子。举个例子有人做视频内容直接安装vidmuse-skills里面通常已经包含了脚本生成、分镜拆解的说明有人做数据分析装一个数据分析技能的包Claude 就能按规范完成清洗、统计、图表输出。这里面有一个没被广泛提到的细节吴恩达推荐的顺序一般是“先做自己的技能再去社区的技能库找现成的”。因为自己封装技能的过程实际上是在把工作流里的隐性经验变成显性规则这比单纯安装别人技能包带来的帮助大得多。我后来也是这么做的先是装现成的跑通然后拆开看结构再模仿着写自己工作流的技能前后不到一周就顺手了。1.3 谁适合用什么时候该用它说实话不是所有人都需要立刻上 Agent Skills。如果你是偶尔让 AI 写个邮件、做张表那直接对话就够了。但如果你满足下面任何一条它就值得上手你在用 Claude Code、Cursor、Claude Desktop 做日常开发或内容生产且发现同样的要求反复解释你的工作流里有固定套路比如“每次写完代码都要检查一遍边界条件”“每篇文章都要按固定结构输出摘要”你希望团队里的 AI 行为一致而不是每个人手动写一段五花八门的系统提示词多平台应用是我体验最深的场景Claude Code 里它能作为原生技能直接触发Claude Desktop 里通过配置文件也能塞进去Cursor 则可以通过规则文件间接复用甚至连 OpenCode 这类开源工具也能接入同一套技能目录。也就是说一份技能包可以在多个平台之间反复横跳真正实现“写一次到处跑”。这篇文章接下来的所有内容都是围绕“一份技能包多端复用”这件事展开的。2. 拆开看核心机制SKILL.md 与技能包的文件结构2.1 SKILL.md 是灵魂自然语言说明书如果你打开任何一个 Agent Skills 技能包第一眼看到的肯定是SKILL.md。它不写代码而是用自然语言描述这个技能是干什么的、在什么场景下触发、有什么约束。对模型而言这份 Markdown 就相当于“工作手册”模型能不能正确判断“我该不该用这个技能”完全取决于这份手册写不写得好。我在反复尝试后总结出 SKILL.md 最理想的结构是四段式第一段一句话说明技能用途尽量包含关键词方便模型快速匹配第二段说明这个技能在什么情况下该用、什么情况下不该用避免误触发第三段给出具体的执行步骤最好按序号拆开复杂步骤要写判断条件第四段列出依赖工具、脚本用法、输入输出格式以及常见注意点这里给你一个示例开头是我做视频封面摘要时写的# VidMuse 封面摘要生成技能 在用户需要为一期视频生成封面方案或内容摘要时使用。 适合的场景视频发布前需要设计封面文案、提取视频主题要点。 不适合的场景用户只是简单询问视频内容不需要输出封面建议。这份文件不需要写得多华丽但一定要“机器友好”。模型不像人能领会潜台词它靠语义匹配决定是否触发所以你在描述使用场景时最好把“用户可能会怎么说”都列出来比如“帮我出个封面”“这期讲什么的”“做个视频摘要”这类句子写清楚命中率会高很多。这也是我对比过多个技能包之后发现的共同点那些装了不会触发的技能九成都是 SKILL.md 里场景描述写得模棱两可。2.2 辅助脚本把重复劳动交给代码SKILL.md 解决“模型知道该怎么做”的问题辅助脚本解决“事情能不能稳定做完”的问题。比如你要让 AI 总结一篇播客转录稿如果全靠模型自己读全文、归纳重点每次发挥可能都不一样但如果你在技能里放一个 Python 脚本规定它按固定逻辑切分文本、统计词频、提取关键句模型只需要调用脚本再基于脚本输出做润色结果就稳定得多。所以一个规范的技能包目录通常长这样my-skill/ ├── SKILL.md ├── scripts/ │ ├── summarize.py │ └── split_text.py └── reference/ └── template.mdscripts目录放可执行代码reference目录放参考材料比如输出模板、评分标准、案例样本。模型在按照 SKILL.md 执行时如果需要读参考材料它会自己去 reference 目录里翻如果要做计算或文本处理它会执行 scripts 里的脚本。有一点必须提醒脚本里的逻辑要尽量“原子化”。你宁可写三个小脚本每个只负责一件事也不要写一个 500 行的大脚本因为模型定位和调用大脚本时容易出错。我自己早期犯过的错误就是把“抓取链接、清洗内容、生成摘要”全写在一个文件里结果模型经常搞不清该传什么参数后来拆成三个脚本一次报错率立刻降下来了。2.3 Skills 和 MCP 的差别别再混为一谈很多人把 Agent Skills 和 MCPModel Context Protocol放在一起比较其实它们解决的完全不是一类问题。用生活化类比来说MCP 像是给电脑插上 U 盘它提供的是“连接能力”——连数据库、连浏览器、连内部系统重点在获取外部实时数据而 Skills 像是给员工发操作手册它提供的是“做事方法”——连不连外部系统无所谓重点是把一套流程稳定执行出来。MCP 的核心是服务器你需要配置 endpoint、定义工具、管理鉴权模型通过协议去动态发现和调用这些工具。Skills 的核心是文件和说明本地安装、按需读取、不依赖网络服务。所以如果你只是想让 AI 学会“按固定格式写周报”那完全没有必要上 MCP如果你想让它直接查公司数据库里的销售额那 Skills 做不了得用 MCP。这个区分在实际配置时至关重要。因为多平台场景下MCP 服务器每换一个客户端就要重新配置一遍甚至连鉴权方式都可能不一样而 Skills 只是一个文件夹你把它复制到对应平台的技能目录就能用分发成本低得多。这也是“多平台实战”里我最看重 Skills 的原因——它天生就是可移植的。3. 多平台应用实战从 Claude Code 到 Desktop 到 Cursor3.1 用一条命令装好首个技能包npx skills add 全参数解析最开始上手时我建议直接安装现成的技能包跑通流程。社区里最常见的安装命令长这样npx skills add sandai-org/vidmuse-skills --agent claude-code -g -y这条命令看着短但每个参数都有讲究我拆开讲。npx skills是 Anthropic 官方推出的 skills 命令行工具npx会自动下载并执行它不需要你先全局安装。add sandai-org/vidmuse-skills表示从sandai-org这个 GitHub 组织下把vidmuse-skills这个仓库当作技能包添加进来。这里要留意不是所有 GitHub 仓库都能直接作为技能源仓库根目录下必须有SKILL.md文件才行。--agent claude-code指定的是“这个技能要装给谁用”。不同平台对技能目录的要求不一样官方 CLI 目前支持claude-code、desktop、cursor、opencode等多个目标。-g是全局安装的意思如果不加技能默认只装到当前项目的.claude/skills目录。-y则是跳过交互确认适合脚本化批量安装。完整安装后Claude Code 会在启动时自动扫描技能目录不需要重启客户端也能识别到新技能这是我实测过很多次的结论。如果你只想装到当前项目里方便团队共享同一套技能配置把-g去掉就行。装完后在项目目录下会生成.claude/skills/vidmuse文件夹提交到 Git 仓库后团队成员 pull 下来就能直接用技能配置的版本管理也顺带解决了。3.2 Claude Desktop 的配置方法Claude Desktop 虽然叫“桌面版”但技能目录和 Claude Code 并不共享。很多人第一次接触时在这里卡住明明在 Claude Code 里装好的技能切到 Desktop 却找不到。原因是 Desktop 读取的是用户级配置目录下的skills文件夹而不是项目目录里的。按照官方规范Claude Desktop 的技能目录是~/Library/Application Support/Claude/skills/ # macOS %APPDATA%\Claude\skills\ # Windows你只需要把技能包整个文件夹复制到这个目录下重启 Claude Desktop 就能生效。这里有一个坑Desktop 的模型有时不会主动调用技能因为它没有一个明确的“用户让 AI 用技能”的上下文。我的经验是在对话里直接说“用 VidMuse 技能给这个视频出个封面方案”命中率会明显提高。原因是 Desktop 界面上没有像 Claude Code 那样暴露/skills命令入口只能靠语义触发所以你的指令里最好带上技能名或功能描述。如果你嫌手动复制麻烦可以写一个同步脚本用软链接把 Claude Code 的全局技能目录和 Desktop 的技能目录映射起来这样两边始终用同一套文件。我个人就是这么干的软链接建好后再也没有“装了两份、改了一处忘了另一处”的烦恼。3.3 Cursor 与 OpenCode 的接入思路Cursor 官方对 Agent Skills 的支持方式很轻量它通过.cursor/rules目录来加载规则文件而 Agent Skills 的 SKILL.md 本质上也是一种规则。所以要让 Cursor 用上同一个技能包最简单的方法是把技能包里的SKILL.md复制到.cursor/rules目录下或者写一个引用它的封装规则。但我实测发现直接复制有个问题SKILL.md 里如果写了要调用scripts/里的脚本Cursor 并不会像 Claude Code 那样自动找到相对路径。所以更好的做法是在.cursor/rules/vidmuse.mdc里写清楚技能文件夹的绝对路径并告诉 Cursor “遇到相关任务时阅读指定路径的 SKILL.md 并按其执行”。这样既保留了技能包的原始结构又能在 Cursor 里稳定触发。OpenCode 的接入稍微灵活一些它的插件体系支持加载本地目录。我参考社区方案在 OpenCode 的config里注册了一个功能模块启动时读取SKILL.md并注入上下文效果和 Cursor 类似。需要提醒的是OpenCode 的生态变化比较快如果你用的是较新版本建议优先看官方文档确认是否原生支持 Agent Skills避免花时间配了半天发现接口已经变了。3.4 多平台共用一套技能库的目录规划既然是讲多平台实战最理想的状态就是“一套技能文件三种平台共享”。我的做法是建立一个独立的技能仓库结构大致如下my-skills-repo/ ├── skills/ │ ├── vidmuse/ │ ├── weekly-report/ │ └── code-review/ ├── install-claude-code.sh ├── install-desktop.sh └── cursor-rules/ ├── vidmuse.mdc └── weekly-report.mdcClaude Code 直接用npx skills add安装或通过项目级路径引用Desktop 用软链接映射到全局技能目录Cursor 则通过cursor-rules里的引用文件桥接。配好之后你在任何一端更新技能内容其他平台下次触发时读到的都是同一份最新文件。关于目录规划我有一条重要心得技能包里不要写死任何绝对路径。因为 Claude Code、Desktop、Cursor 的技能目录路径完全不同一旦 SKILL.md 里写了C:\Users\xxx\...换台电脑立刻失效。所以路径引用一律用相对路径或者干脆在 SKILL.md 里只写“脚本位于 scripts/ 目录下由模型自行定位”让模型根据当前环境去探索。很多自称“多平台兼容”的技能包实际做不到这一点装到第二个平台就报错十有八九是路径写死了。4. 自己动手写一个 Agent Skill从零到可复用4.1 需求拆解做一个实用的视频脚本生成技能光会装别人写的技能包只能算入门。把工作流里最常用的一套流程封装成自己的技能才算真正掌握了 Agent Skills 的精髓。我以“短视频脚本生成”为例完整走一遍写技能的过程。先拆需求平时做短视频需要先定主题、列大纲、写逐字稿、配画面建议这个流程每次都要重复而且不同账号的风格要求还不一样。如果能在技能里定义好这几个步骤并让 AI 按固定格式输出效率能提升不少。我决定做一个技能包命名为short-video-script输出格式统一为“主题一句话 开头钩子 分段内容 画面建议”。这个技能不需要连外部 API也没有复杂的数据处理核心就是“按照 SKILL.md 里的规则产出结构化内容”所以对脚本的要求很低。我甚至不需要写任何 Python 代码纯 Markdown 就够。但为了演示辅助脚本的用法我还是加了一个format_checker.py用它检查输出是否包含所有必要字段避免模型漏写画面建议这种常见问题。4.2 SKILL.md 的写法与注意事项技能包的核心还是SKILL.md。我写好的版本大致是这样的结构# 短视频脚本生成技能 当用户需要为一期短视频生成脚本、逐字稿或拍摄大纲时使用。 触发词写个短视频脚本、帮我出个视频大纲、这期视频怎么拍。 不适合场景用户已经有完整脚本只需要润色措辞。 ## 执行步骤 1. 询问视频主题、目标观众、时长要求如用户未提供按默认值处理主题用户最新对话主题观众泛大众时长90秒 2. 输出“主题概括”不超过30个字 3. 输出“开头5秒钩子”用疑问句或反常识结论吸引注意 4. 将内容拆成3-5段每段给出口播文案和对应画面建议 5. 在结尾输出“行动号召” 6. 运行 format_checker.py 检查字段完整性缺少字段时补齐 ## 注意事项 - 语言风格默认为口语化禁止书面语 - 每段口播文案不超过80字 - 画面建议需要用括号标注方便拍摄时对照写 SKILL.md 时最容易忽略的一个细节是“模型要能判断什么时候不触发”。很多人在描述的时候只写了“什么时候该用”完全没写“什么时候不该用”结果模型容易把普通对话也套进技能流程里。我在上面示例里特意加了“不适合场景”这一行这种显式负例对模型非常有帮助它的误触发率能下降一大截。另外执行步骤不要写得太抽象。像“分析用户需求并输出脚本”这种描述等于没说模型不知道该按什么顺序做。好的步骤应该像菜谱一样先干什么、再干什么、什么条件做什么判断每一步都是可执行的指令。我自己迭代下来的体会是把步骤写得越机械输出质量越稳定。4.3 测试、迭代与分发写完之后测试环节不可跳过。我一般分三个层次来测第一层直接在当前平台对话里触发看模型是否会自动读取 SKILL.md第二层连测 5 个不同主题检查输出是否都符合格式要求第三层把技能包复制到 Claude Desktop 和 Cursor确认跨平台可用我在测试short-video-script时发现一个问题在 Cursor 下模型总能正常触发但输出经常漏掉“画面建议”原因是 Cursor 对 Markdown 里括号内容的重视程度不如 Claude Code。后来我在 SKILL.md 里把“画面建议”单独加了一行强调并让格式检查脚本在缺字段时打印提示问题才算解决。这也说明不要指望一份 SKILL.md 在所有平台表现完全一致你需要在每个目标平台上各测试一轮然后针对性补强描述。分发方面最省事的做法是把技能包推到 GitHub 仓库然后让别人用npx skills add 你的用户名/仓库名 --agent claude-code -g -y来安装。发布前记得确认仓库根目录有SKILL.md并且不要塞入无关的大文件因为别人是用 Git 拉取的仓库体积直接影响安装速度。如果你不想公开也可以放到私有仓库npx skills add同样支持带 token 的私有仓库地址。5. 常见问题与排查技巧实录5.1 模型不调用技能怎么办这是问得最多的问题。装好了技能但对话时模型完全不理会好像技能不存在一样。根据我多次踩坑的经验优先排查顺序如下先看 SKILL.md 里的触发描述是否足够具体。如果技能说明只写了一句话模型在快速判断时很容易漏掉它。解决办法是像前面说的列出多种用户可能的表达方式并在“不适合场景”里写清楚不属于自己职责的情况让模型的匹配判断有据可依。再看平台对技能目录的扫描路径是否正确。不同平台读的不是同一个目录Claude Code 读项目级.claude/skillsDesktop 读用户级~/Library/Application Support/Claude/skillsCursor 则靠 rules 文件桥接。很多人装好技能后模型不识别最后发现就是路径搞错了。最后检查模型版本和平台版本。Agent Skills 依赖模型对“按需读取说明文件”的理解能力版本较旧的模型可能不会主动去读技能目录。遇到这种情况只能在对话里直接指定“读一下某个技能文件夹里的 SKILL.md”先确认技能文件本身没问题再考虑升级模型或客户端。5.2 安装路径和加载不到的问题npx skills add装完后可以用这几条命令快速确认技能是否真的装到了预期位置npx skills list --agent claude-code ls ~/.claude/skills/ # 全局技能目录 ls .claude/skills/ # 项目级技能目录如果skills list能看到技能但对话里不生效多半是平台的“技能加载开关”没打开或者用了多配置文件导致目录被覆盖。Claude Code 的配置文件是递归合并的如果你的项目根目录和子目录里有多份配置后加载的可能会覆盖先加载的技能目录设置。排查思路就是把自定义配置尽量收敛到一个地方避免多处声明同一项。另外技能包文件夹命名不要带空格和特殊字符否则模型在解析路径时容易出错。这是我早期遇到的一个真实问题技能文件夹叫my-skills-final-v2看起来没问题但里面包含的引用文件名带了括号和空格导致脚本调用时路径解析失败。后来统一改成短横线命名问题立刻消失。5.3 多平台配置注意事项多平台复用时最烦人的不是功能差异而是“配置分散”。Claude Code 的配置在项目里Desktop 的配置在用户目录Cursor 的配置在.cursor文件夹下三个地方互不相通很容易出现“在一端改了技能另一端还在用旧版”的情况。我的解决办法是围绕一个中心技能仓库做软链接分发。所有技能文件只维护一份放到~/skills-central/下然后让 Claude Code、Desktop、Cursor 各自加载这个目录的链接或引用。这样更新技能时只需要改中心目录一份所有平台下次触发时自动用到新版本。唯一要注意的是如果你有技能脚本依赖外部依赖包比如 Python 库就必须在每个平台的运行环境里都装好否则会出现“Claude Code 能跑、Desktop 报 module not found”的尴尬局面。5.4 技能包安全性与来源审查社区里的技能包数量增长很快但质量参差不齐安全性必须放在心上。技能包里的脚本会在你的本机执行和直接运行别人发的脚本没有本质区别。我的习惯是安装社区技能包后先打开SKILL.md和所有脚本文件通读一遍确认没有可疑操作再在测试项目里跑一次。具体看哪些东西重点关注脚本里是否有网络请求、环境变量读取、文件删除等高风险操作。不是说有这些操作就不能用而是你得清楚它在做什么。比如一个视频处理技能要调用 ffmpeg这很正常但如果它在启动时就往某个陌生地址传数据那就得警惕了。多平台环境下这个风险会被放大因为你在三个平台都装了同一份技能等于给了它三个执行入口。另外一个容易忽略的点是技能包的版本锁定。如果直接使用 GitHub 仓库的默认分支作者更新代码后你下次安装时拉到的可能是新版本。对于关键生产环境的技能建议锁定仓库的 commit hash 或 tag避免“昨天还能用今天莫名出错”的问题。我自己维护技能仓库时每次稳定版本都会打 tag并在文档里写明推荐安装的版本号这样团队内部使用不会互相踩踏。最后分享一点个人体会我大概是花了一周时间把 Agent Skills 从“听说过”到“日常离不开”的。最开始是被吴恩达教程里那句“把技能封装成文件”打动后来真正用起来才发现它真正的价值不是省 token而是强制我把自己模糊的工作流变成了可复用的规则。这个过程的收获甚至超过了技能本身的效率提升。如果你现在正处在“刚听完概念、准备动手”的阶段我的建议很直接先找一个重复次数最多、规则最明确的小任务照着文章里的结构写一个技能包测试通过后再往多平台铺开。不要一上来就追求大而全那只会让你迷失在配置细节里。所有所谓踩坑经验本质都是从一个足够小的技能开始、逐步扩展的过程中积累出来的。希望这篇实战记录能帮你少走点弯路。