大概从2025年初开始Agent Skills这个词在AI应用开发圈子里突然就火了。吴恩达专门为此出了一套公开教程各大Agent平台陆续跟进原生支持社区里也冒出了大量可以直接安装的skill仓库。我自己从三月份开始把项目逐步迁移到Skills这套工作方式上先后在Claude Code、OpenAI Codex CLI这类工具里跑过期间踩了不少坑也总结出一些可复用的套路。这篇就把完整经验写出来适合正在做Agent应用、或者被巨型系统提示词折磨得够呛的开发者参考。1. 从「咒语式提示词」到「技能库」Agent Skills 解决的到底是什么问题1.1 传统提示词工程的天花板聊聊我之前的做法。早期做Agent类应用我的思路和绝大多数人一样把所有领域知识、业务规则、输出格式、工具调用说明全部塞进一个巨大的系统提示词里。一个稍微复杂一点的业务提示词轻松超过3000行token占用量直奔2万甚至更多。这种做法的第一个问题出在上下文预算。拿Claude这类模型来说长上下文虽然能装下几十万token但系统提示词占用的空间越大真正留给对话历史、工具返回结果、用户例子的空间就越小。用户在长会话里多问几个问题模型要么开始丢前面的关键信息要么回答质量肉眼可见地下降。我自己实测过一个塞满领域知识的提示词在前三轮对话里效果还行到第十轮以后就开始前言不搭后语很多明明写在提示词里的规则它突然就忘了。第二个问题是维护性的崩溃。提示词是高度耦合的文本你改了一个业务规则可能影响另一个完全不相关的功能。某次我加了一段新的输出格式约束结果把之前调好的对话风格带偏了花了一个下午排查才发现是两段指令在语义上冲突。这种按了葫芦起了瓢的体验做过复杂提示词的人应该都懂。第三个问题是复用几乎为零。同一个功能在A项目里的提示词是几万字系统提示词中的一小段完全没法直接搬到B项目。团队里另一位同事想用我写的视频脚本生成逻辑他只能复制粘贴那几百行文字然后重新适配自己的业务。这本质上就是复制代码而不是引用库。1.2 Skill 范式的核心变化以及吴恩达那套课到底讲了什么Agent Skills的核心思路其实特别朴素把一次注入全部知识改成按需查阅知识。每个能力封装成一个独立的skill目录目录里用一份SKILL.md描述这个能力怎么用、在什么场景下用再加上必要的脚本、模板、参考资料。Agent的主提示词保持精简只写一条元规则当遇到某个任务时去技能库里找到描述匹配的那个skill加载它的SKILL.md严格按里面的步骤执行。这个设计是借鉴人类工作的方式。你入职一家公司不会在第一天就把几百页操作手册全背下来而是遇到具体任务时去查对应章节。Agent Skills把这种即时加载和传统提示词那种预先加载区分开来让模型在完成任务时只看当前任务需要的知识。吴恩达那套公开教程的核心论点我很认同决定Agent能力上限的不再是你往提示词里塞了多少内容而是你有没有一套好的技能检索与装载机制。他演示的案例里一个复杂的业务Agent被拆成多个小skill之后不仅回答质量提升了调试定位问题也变得非常直接——每个skill是独立单元可以单独测试、单独替换。上一节说的三个痛点在这个范式下都被解决了上下文不再被一次性占满各skill之间互相隔离改A不影响Bskill可以跨项目、跨人复用就像安装一个库一样简单。2. 拆开一个 Skill 看内部结构SKILL.md 才是真正的核心资产2.1 SKILL.md 的格式与关键字段一个skill的物理形态就是一个目录。以我目前用的经验来看最少应该包含一个SKILL.md文件加上可选的scripts脚本与assets资源目录。SKILL.md的头部是YAML格式的frontmatter里面有几个字段直接影响Agent能否正确使用这个skill--- name: vidmuse description: 视频创意生成与剪辑辅助技能当用户需要生成视频脚本、分镜设计、镜头列表、剪辑建议时使用。纯文本对话场景不需要此技能。 version: 1.0.0 metadata: author: sandi-org license: MIT --- # 视频创意生成技能 ## 适用场景 ... ## 工作流程 1. ... 2. ...name是唯一标识会在日志和调度信息里出现version用于版本管理最值得注意的是description因为Agent实际上是靠读description来决定这个任务要不要调用这个skill的。description写得太宽泛Agent会在不该用的时候也加载写得太具体遇到相似但略有差别的任务又会漏触发。我见过一份写得特别好的description里面明确写了两部分何时使用、何时不使用这种负例信息对模型判断非常有帮助。如果你不想引入额外依赖那么一个只有SKILL.md的skill完全够用。SKILL.md正文用Markdown写内容结构随便你但通常包含这几个部分能力概述、适用场景、工作流程步骤、输入输出约定、参考示例、常见错误规避。2.2 配套脚本与资源什么该放 scripts什么该放 assets当skill里只需要指导模型怎么做时SKILL.md就够了。但只要涉及确定性计算就必须上脚本。比如视频分镜的时间轴计算、镜头数跟时长的换算、或者生成结构化JSON这些用模型心算容易出错而用Python脚本就能保证100%准确。我的目录组织习惯是这样的vidmuse-skills/ ├── SKILL.md ├── scripts/ │ ├── storyboard.py │ └── validate_script.py └── assets/ ├── templates/ │ ├── storyboard_template.md │ └── shot_list_template.csv └── references/ └── examples.mdscripts放可以被SKILL.md调用的可执行逻辑每个脚本都要在SKILL.md里写清楚什么时候调用、参数是什么、输出是什么。assets放两类东西templates是输出模板比如让模型按某个固定表格结构生成分镜references是参考资料比如一些好的示例、完整的说明文档。references里的内容通常比较大SKILL.md里只需要引用文件路径让Agent按需读取具体小节而不是把整个references塞进上下文。这里有个细节值得注意SKILL.md本身应该控制在合理长度我的经验是1500到3000个token比较合适。再长就考虑移到references里让SKILL.md只保留索引和核心步骤。3. 多平台适配Claude Code、OpenAI Codex 与通用 Agent 的落地差异3.1 各家对 skill 的支持方式并不相同所谓多平台应用核心问题其实是同一份skill怎么在不同Agent平台上跑起来而不是每个平台重写一遍。截至我写这篇文章时的状态Claude Code对skill的支持最原生它能在项目目录的.claude/skills或者用户目录下自动发现skill遇到任务时自动检索加载。OpenAI Codex CLI走的是另一种路线它更依赖AGENTS.md这类项目约定文件配合自定义命令钩子来实现类似能力。Gemini CLI的思路也接近但命令行参数和目录约定各有差异。这就导致了一个现实问题一个skill目录本身是跨平台通用的但怎么让特定平台发现并加载它这一步各家的机制不一样。好在社区正在推动统一标准skills.sh就是其中的代表项目。它定义了一套中立的目录和元数据规范并提供CLI命令帮助你把同一个skill安装到不同平台安装到Claude Code时放在它能自动扫描的目录安装到Codex时生成对应的AGENTS.md配置安装到Gemini时走对应的约定。平台之间的差异我整理了一个简单对照平台/工具技能加载方式目录约定生态成熟度Claude Code自动发现 按需加载项目级 .claude/skills 或用户级配置目录较高OpenAI Codex CLIAGENTS.md 命令钩子项目级配置文件中等Gemini CLI类似 AGENTS.md项目级配置中等通用 Agent手动注入 SKILL.md无统一标准各异3.2 跨平台 skill 的三个设计原则我在迁移过程中总结了三条原则按重要性排序。第一把策略留在SKILL.md把计算留给脚本。SKILL.md描述的是怎么做决策、按什么顺序做scripts负责的是怎么计算出确定结果。这样即使平台换了只影响加载机制不影响skill内部逻辑。第二脚本语言优先选跨平台的Python或纯标准库方案。我一开始写过一份用bash实现的skill在macOS上跑得好好的换到Windows环境就各种问题。后来全部改成Python用argparse处理参数、用JSON作为输入输出格式跨平台稳定多了。第三description是你与各平台调度器之间的唯一契约。不要试图在正文里让Agent去理解这个skill什么时候该用而要把description写得足够精确。平台层面的调度逻辑越不同description的作用就越关键。为了验证这套原则我自己写了一个简单skill在Claude Code里测通之后用skills CLI装到Codex那边只改了安装参数skill本体没动运行结果一致。这也是一种可以复用的验证方法。4. 实操复盘用 npx skills add 完成一个第三方 Skill 的安装与调用4.1 安装命令的完整拆解这条命令现在在社区里很常见npx skills add sandi-org/vidmuse-skills --agent claude-code -g -y逐段拆解一下。npx skills表示直接通过npm执行skills这个CLI工具本地不需要预先全局安装npx会临时拉取最新版本当然如果你经常用还是建议全局装一次省去重复下载。add子命令负责安装。sandi-org/vidmuse-skills是GitHub仓库的简写即组织名sandi-org下的vidmuse-skills仓库从命名推断这套skill和视频生成、创意脚本相关。--agent claude-code告诉CLI把skill安装到哪个平台它决定目标目录和注册方式。-g是全局安装意味着对所有项目生效如果不加这个参数默认装到当前项目目录只对当前项目生效。-y则是跳过所有交互确认。4.2 安装前需要做的检查与实际执行动手之前先确认几个前置条件。首先是Node.js版本npx要求Node 18以上命令node --version看一眼太老就升级。其次确认目标Agent本身已经装好并能正常运行。最后如果你打算全局安装建议先确认目标目录的写权限。然后执行安装命令。执行完之后可以用两条命令验证skills list --agent claude-code查看已安装的skill列表或者直接去对应平台的工作目录检查目录结构Claude Code的全局skills一般在用户配置目录下打开能看到vidmuse-skills文件夹及其中的SKILL.md。4.3 在 Agent 里实际触发一次并验证输出质量安装完不等于能用我强烈建议做一次端到端验证。打开Claude Code输入一个与vidmuse场景匹配的请求比如帮我用vidmuse技能生成一个30秒短视频的脚本和分镜。正确的行为是Agent先定位到这个skill加载SKILL.md然后按其中的工作流程执行。怎么判断它真的加载了skill而不是在凭通用能力硬答两个信号。第一看Agent的思考或日志里有没有出现skill名字或SKILL.md路径第二看输出的结构化程度。如果它产出的是SKILL.md中template目录下定义的表格格式说明整个链路是通的。如果格式对不上优先检查description是否写得太窄或太宽导致Agent没有命中。5. 多平台实战中真正值得警惕的坑以及我的解决方式5.1 上下文膨胀skill 不是越多越好我前面一直在夸按需加载的好处但有一个反向问题容易被忽略如果系统里装了太多skillAgent在检索阶段可能会把多个描述相似的skill都加载进上下文结果上下文照样膨胀。我遇到过最极端的一次项目里装了十来个偏设计类的skill其中三个description都包含生成视觉内容字样。Agent处理一个简单海报需求时把三个都load进来了一轮对话就多烧了近一万token而且多份指令同时生效反而互相干扰输出风格变得很奇怪。解决方式有两个层面。一是从源头控制description里写清楚差异尤其是本skill不负责哪些事二是在Agent侧配置加载策略能限定每次最多加载几个skill的平台就尽量限定必要时手动在系统规则里加一条除非用户明确要求否则一次只加载最匹配的一个skill。5.2 第三方 skill 的安全边界-y 不是随手敲的这是我最想说的一条教训。-y参数跳过所有确认装起来确实爽但代价是你可能没意识到这个skill包里带了可执行脚本。skill天然具备让Agent调用脚本的能力那么一个来源不明的skill仓库理论上完全可以在你机器上执行任意代码。我自己现在的做法是只要不是作者明确说明过用途的skill一律不装全局先装到项目目录然后打开SKILL.md和scripts目录里的脚本人肉检查一遍。重点看脚本里有没有网络请求、有没有读写敏感路径、有没有可疑的eval或exec调用。别嫌麻烦第三方skill的供应链攻击是真实存在的风险尤其当你在处理带机密性的业务时。另外提醒一个细节npx skills add的-g和-y是两个独立参数建议至少保留一个交互确认。不熟悉的仓库用不带-y的命令让它在安装前展示清楚要往哪里写文件再决定是否继续。我见过不少人在部署脚本里图省事直接加上-y这等于把安全检查全关了。5.3 版本漂移与多平台不一致比想象中更容易发生skill仓库是会持续更新的作者今天改一行脚本你项目里的行为就变了。如果你追求可复现就要想办法锁定版本。skills CLI本身会记录安装来源但实测下来更稳妥的做法是在项目里维护一份清单写明每个skill的仓库地址、commit hash或tag定期手动复核。多平台不一致的问题则更隐蔽。同一个skill在Claude Code里跑得好好的换到另一个平台可能出现脚本路径解析错误。原因是不同平台对skill目录的搜索逻辑、工作目录的当前路径定义不一样。解决方式是脚本里不要用相对路径尽量用SKILL.md所在目录推导路径或者让CLI在安装时生成平台感知的路径引用。最后再说一个实用小技巧在SKILL.md正文里加一段自检清单。比如要求Agent在执行完任务后对照清单检查输出是否完整、格式是否正确。这个做法能帮你省下大量人工复核时间也是我在这轮多平台迁移中收获最大的习惯之一。