Agent Skills实战指南：从提示词工程到技能库的多平台迁移

大概从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不影响B；skill可以跨项目、跨人复用，就像安装一个库一样简单。

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.md

scripts放可以被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时走对应的约定。

平台之间的差异，我整理了一个简单对照：

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 不是越多越好

我前面一直在夸按需加载的好处，但有一个反向问题容易被忽略：如果系统里装了太多skill，Agent在检索阶段可能会把多个描述相似的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在执行完任务后对照清单检查输出是否完整、格式是否正确。这个做法能帮你省下大量人工复核时间，也是我在这轮多平台迁移中收获最大的习惯之一。