1. 从“skills”这个标题说起：它到底指什么

第一次看到“skills”这个标题，很多人会以为是某个泛泛而谈的能力清单，或者一份职场软技能合集。但结合热搜词里的 Agent Skills、Google Cloud、npx、AI agents、claude agent skills、codex skills 这些关键词，基本可以确定，这里说的 skills 不是人类的能力，而是给 AI Agent 使用的一套可插拔能力包。简单讲，它是一组结构化的指令、脚本和资源文件，让一个通用的大模型代理在特定任务上表现得像一个训练有素的专才。

我把它理解成“给 AI 装的技能插件”。一个裸的 Agent 就像一个刚入职的聪明实习生，什么都懂一点，但真让它干具体活，比如写一份符合公司规范的周报、跑一套前端构建流程、按固定格式做分镜脚本，它就会开始自由发挥。skills 的作用，就是把这些“自由发挥”收敛成“按套路出牌”。每个 skill 通常包含一段描述、触发条件、执行步骤，有时还带可执行脚本和参考文件。Agent 在遇到匹配场景时，自动加载对应 skill，按里面写好的流程走。

这套东西解决的核心问题是一致性和可复用性。你不可能每次让 AI 干活都重新写一遍超长提示词，也不可能保证每次描述都一样。skills 把提示词工程沉淀成文件资产，可以版本管理、可以分享、可以组合。适合谁来参考？三类人：一是天天和 AI Agent 打交道、想提升输出稳定性的开发者；二是想把团队内部流程固化下来的技术负责人；三是好奇 AI Agent 到底怎么扩展能力、想自己动手写一个 skill 的爱好者。哪怕你只是用 AI 写写文档、做做分镜，理解 skills 的机制也能让你少踩很多坑。

我下面会从设计思路、核心结构、实操流程、常见问题几个角度，把 skills 这套东西拆开讲清楚。内容基于公开的 Agent Skills 常见实践和我在实际项目里的使用经验，涉及具体平台的地方会说明通用做法，不绑定某一家。

2. 整体设计思路：为什么是“技能包”而不是“超级提示词”

2.1 从提示词膨胀到能力模块化

早期用 AI Agent 的人都有一个共同经历：提示词越写越长。一开始只是“帮我写个函数”，后来变成“帮我写个函数，要求命名规范是某某，注释格式是某某，异常处理要这样，测试要那样”，再后来干脆把整个代码规范文档贴进去。提示词膨胀带来三个问题：token 成本飙升、模型注意力被稀释、维护困难。你改一个规范，得在所有对话里同步改。

skills 的设计思路就是把提示词从对话里抽出来，变成独立文件。每个 skill 只负责一类任务，文件里写清楚这个技能是干什么的、什么时候用、怎么执行。Agent 的运行时系统负责在合适的时候把合适的 skill 加载进来。这样提示词不再是一坨，而是一个个可组合的模块。类比一下，超级提示词像把整个工具箱焊死在一个手柄上，skills 像标准化的螺丝刀头，用哪个换哪个。

这个设计背后有一个关键判断：通用能力和专用能力应该分离。大模型本身提供通用推理和语言能力，skills 提供领域知识和流程约束。分离之后，通用能力升级不影响专用流程，专用流程调整也不需要重新训练模型。这是软件工程里“关注点分离”思想在 AI Agent 上的直接应用。

2.2 触发机制：Agent 怎么知道该用哪个 skill

skills 能不能用起来，核心在触发。常见做法有两种：一种是描述匹配，skill 文件里有一段自然语言描述，Agent 根据当前任务和描述做语义匹配，觉得相关就加载；另一种是显式调用，用户在指令里直接点名某个 skill，比如“用分镜 skill 处理这段脚本”。实际系统里往往是两者结合。

描述匹配的难点在于边界。描述写太宽，什么任务都触发，等于没触发；写太窄，该用的时候用不上。我的经验是，描述里要同时包含动作和对象，比如“当用户要求把一段文字拆解成带镜头编号和画面描述的分镜表时使用”，而不是“用于分镜”。前者限定了输入输出形态，后者太模糊。另外，描述里最好带上反例，说明什么情况不该用，减少误触发。

显式调用则依赖命名。skill 的名字要短、可读、无歧义。storyboard比video-script-split-tool好，因为前者一眼知道干什么，后者像内部工号。命名规范这件事看起来小，实际影响很大，尤其在 skill 数量多起来之后，名字混乱会让调用变成猜谜。

2.3 组合与优先级：多个 skill 冲突怎么办

真实任务往往需要多个 skill 协作。比如“根据这份需求文档生成前端页面”，可能涉及需求解析 skill、组件生成 skill、样式规范 skill。这时候就涉及组合和优先级。常见策略是分层：基础规范类 skill 优先级高，具体任务类 skill 优先级低，后者在前者约束下执行。如果两个 skill 给出矛盾指令，系统需要有一个裁决机制，通常是按加载顺序或显式声明的优先级。

我在实际使用中遇到过样式规范 skill 和快速原型 skill 冲突的情况：前者要求严格按设计系统，后者要求先跑通再说。解决办法是在任务开始时明确当前阶段，原型阶段禁用严格规范 skill，进入正式开发再启用。这说明 skills 的组合不是自动的，需要使用者有意识管理。把 skills 当成一堆可以随时叠加的插件，迟早会出乱子。

3. 核心结构解析：一个 skill 文件里到底有什么

3.1 元信息部分：名称、描述、版本

一个规范的 skill 通常以元信息开头。名称用于调用和索引，描述用于触发匹配，版本用于管理和回滚。这三样看起来简单，但每一样都有讲究。名称建议用英文小写加连字符，避免空格和特殊字符，因为很多工具链对文件名敏感。描述要写成完整的句子，包含触发场景，不要只写关键词堆砌。版本号建议遵循语义化版本，改流程升中版本，改文案升小版本，方便追溯。

元信息里还可以加作者、依赖、适用平台等字段。依赖字段特别重要，如果一个 skill 依赖某个命令行工具或某个库，必须写清楚，否则 Agent 加载后执行到一半发现环境没有，任务就断了。我见过有人把依赖写在正文里，结果触发匹配时读不到，白白浪费时间。元信息就是元信息，该放前面的别放后面。

3.2 指令正文：步骤、约束、输出格式

正文是 skill 的核心，通常包含三块：执行步骤、约束条件、输出格式。执行步骤要写成有序列表，每一步是一个可操作的动作，避免“分析一下”“考虑一下”这种模糊表述。约束条件写清楚不能做什么，比如“不要引入新的第三方库”“不要修改现有测试文件”。输出格式最好给出模板或示例，让 Agent 有明确的模仿对象。

这里有一个容易被忽略的点：步骤的粒度。太粗，Agent 自由发挥空间大，输出不稳定；太细，Agent 变成提线木偶，遇到稍微不同的情况就卡住。我的经验是，关键决策点写细，常规操作写粗。比如“读取配置文件”可以粗，“当配置里 mode 为 strict 时必须先校验 schema”就要细。粒度控制是 skill 写作里最考验经验的地方，没有标准答案，只能靠反复测试调整。

3.3 资源文件：脚本、模板、参考数据

复杂 skill 往往附带资源文件。脚本用于执行确定性操作，比如格式化、校验、转换；模板用于生成固定结构的内容；参考数据用于提供领域知识，比如术语表、映射表。资源文件的好处是把确定性逻辑从模型推理里拿出来，交给代码执行，既快又准。

但资源文件也带来管理成本。脚本要考虑跨平台，模板要考虑版本同步，参考数据要考虑更新机制。我一般建议，能用纯指令解决的就不加脚本，能用一个模板解决的就不加多个。每加一个资源文件，就多一个可能失效的点。skills 的维护成本往往不在写的时候，而在改的时候。一开始图方便塞进去的东西，后面都会变成债。

4. 实操流程：从零写一个能用的 skill

4.1 环境准备与目录结构

动手之前先把目录结构定好。常见做法是在项目根目录下建一个 skills 文件夹，每个 skill 一个子目录，子目录里放主文件和资源。主文件名通常固定，比如SKILL.md或skill.yaml，具体看所用工具链的要求。资源文件放在同级的assets或scripts目录里，保持整洁。

如果你用的是支持 npx 的工具链，安装和初始化往往一条命令搞定。比如某些 Agent 框架提供npx <tool> init skill之类的命令，自动生成目录骨架。但我不建议完全依赖脚手架，最好手动过一遍生成的结构，知道每个文件是干什么的。脚手架省事，但出问题时你得有能力排查。环境准备阶段还要确认运行时版本，Node 版本、Python 版本这些基础依赖不匹配，后面报错会很难找。

提示：目录名和 skill 名保持一致，避免大小写混用。在区分大小写的系统上，MySkill和myskill是两个不同的东西，跨平台协作时容易出问题。

4.2 编写第一个 skill：以“分镜拆解”为例

假设我们要写一个把文字脚本拆成分镜表的 skill。第一步定名称：storyboard-split。第二步写描述：“当用户提供一段叙事文字并要求拆解成带镜头编号、画面描述、时长建议的分镜表时使用。不适用于纯对话生成或视频剪辑指令。”第三步写步骤：读取输入文字，识别场景切换点，为每个场景分配镜头编号，生成画面描述，估算时长，输出表格。第四步定输出格式，给一个两行的示例表。

写完之后不要急着用，先做干跑测试。找三段不同类型的文字，一段动作描写、一段对话、一段心理描写，分别让 Agent 加载这个 skill 执行，看输出是否符合预期。动作描写容易拆，心理描写难拆，如果心理描写输出一堆空镜头，说明步骤里缺少对非视觉内容的处理规则。这时候回去补一条约束：“遇到心理描写时，转换为可视觉化的动作或环境细节，不要生成无法拍摄的抽象镜头。”这种补丁就是实操中攒出来的经验，文档里不会写。

4.3 测试与迭代：怎么判断一个 skill 合格

判断标准我总结成三条：触发准、执行稳、输出可预期。触发准是指该用的时候用上，不该用的时候不掺和。测试方法是准备一批正例和反例，正例看召回，反例看误触发。执行稳是指同样输入多次运行，结果结构一致，细节可以有差异但框架不变。输出可预期是指输出格式符合模板，字段齐全，没有缺胳膊少腿。

迭代时一次只改一个变量。改了描述就测触发，改了步骤就测执行，不要同时改好几处，否则出问题不知道是哪处引起的。我习惯给每个 skill 建一个测试记录，记下每次修改的内容和测试结果，几轮下来就能看出哪些改动有效。这个过程有点像调参，急不得，但每轮都有收获。

4.4 发布与共享：打包和分发

skill 写完自己用没问题之后，可以考虑共享。共享方式有几种：直接复制目录、打包成压缩包、发布到内部仓库或公开市场。如果发布到公开平台，要注意脱敏，把内部路径、密钥、业务数据清理干净。我见过有人把带内部接口地址的 skill 直接传上去，虽然不一定造成事故，但总归不专业。

打包时建议附一个简短的 README，说明用途、依赖、使用方法、已知限制。README 不用长，但要有。别人拿到你的 skill，第一眼看到的就是 README，写清楚能省很多沟通成本。版本号也要在打包时更新，别改了内容还挂着旧版本号，用的人会困惑。

5. 常见问题与排查技巧实录

5.1 触发失败：该用的时候没用上

触发失败是最常见的问题。表现是 Agent 明明遇到匹配任务，却没加载对应 skill。原因通常有三个：描述太窄、名称太偏、加载机制没配对。排查顺序是先看描述，把描述里的触发条件放宽一点，再测；如果还不行，检查名称是否被正确索引；最后确认运行时是否真的扫描了 skill 目录。

有一个隐蔽原因是描述语言和任务语言不一致。如果 skill 描述用中文写，用户用英文提问，语义匹配可能失败。解决办法是描述里同时包含中英文关键词，或者统一用英文写描述。这个坑我在跨语言项目里踩过，排查了半天才发现是语言问题。

5.2 执行中断：跑到一半报错

执行中断通常和依赖有关。skill 里调用了某个命令，但环境里没装；或者调用了某个文件，但路径不对。排查时先看报错信息，定位到具体步骤，然后手动执行那一步，看是否复现。如果手动能跑通，说明是 Agent 执行环境的问题；如果手动也跑不通，说明是 skill 本身的问题。

还有一种中断是权限问题。脚本没有执行权限，或者输出目录不可写。这类问题在本地开发时不容易发现，换到 CI 环境就暴露了。建议在 skill 里加一步环境检查，提前发现权限和依赖问题，而不是跑到一半才挂。

5.3 输出漂移：结果和预期不一致

输出漂移指结构大致对，但细节跑偏。比如要求输出三列，结果有时两列有时四列；要求用中文，结果夹杂英文。原因往往是约束不够硬。解决办法是在输出格式部分给出严格模板，并加一句“严格按照模板输出，不要增删列”。如果还漂，就在步骤最后加一步自检，让 Agent 输出前对照模板检查一遍。

漂移的另一个来源是模型本身的随机性。同样的 skill，不同时间运行结果不同。这时候可以调低温度参数，或者把关键字段的取值限定在枚举范围内。完全消除随机性不现实，但可以把漂移控制在可接受范围内。

5.4 常见问题速查表

这张表是我自己排查时用的，基本覆盖八成常见问题。遇到新问题先归类，再按对应方向处理，比盲目改文件高效得多。

6. 进阶玩法：让 skills 真正融入工作流

6.1 与版本控制结合：skill 也是代码

把 skills 纳入版本控制是迟早的事。每个 skill 一个目录，改动走提交，发布打标签。这样做的好处是可追溯、可回滚、可协作。团队里谁改了哪个 skill，什么时候改的，为什么改，都有记录。skill 虽然是自然语言写的，但它的管理方式和代码没区别。

我建议给 skills 仓库单独建一个，不要和业务代码混在一起。业务代码迭代快，skills 迭代慢，混在一起提交历史会很乱。单独仓库也方便权限管理，不是所有人都需要改 skills，但所有人都需要用。用的时候可以通过子模块或包管理引入，保持同步。

6.2 与自动化流程结合：CI 里跑 skill 测试

skill 多了之后，手动测试不现实。可以把 skill 测试接进 CI，每次提交自动跑一遍正例和反例，看触发和执行是否正常。测试用例就是输入和预期输出，断言可以写得宽松一点，检查关键字段是否存在、格式是否符合，不要求逐字匹配。

CI 里跑 skill 测试有个额外好处：能发现环境差异导致的问题。本地能跑，CI 跑不了，说明依赖没声明清楚。这种问题越早发现越好，等到线上才暴露就麻烦了。

6.3 与团队协作结合：skill 评审和文档

团队共用 skills 时，评审机制很重要。一个新 skill 或一次修改，最好有人过一眼，看描述是否清晰、步骤是否合理、有没有安全风险。评审不用太重，一个 checklist 就够：名称规范吗，描述有触发条件吗，步骤可执行吗，输出有模板吗，依赖写了吗。五条过一遍，基本质量就有保障。

文档方面，除了每个 skill 自己的 README，建议维护一个总索引，列出所有可用 skill、用途、负责人。索引不用花哨，一个表格就行。新人进来先看索引，知道有哪些能力可用，比一个个翻目录高效得多。

7. 我踩过的坑和几条实在建议

第一个坑是贪多。一开始想写一个大而全的 skill，把所有相关任务都塞进去，结果描述模糊、步骤臃肿、触发混乱。后来拆成三个小 skill，每个只干一件事，反而好用。skill 的粒度应该像函数，一个函数只做一件事，做精做透。

第二个坑是忽视反例。只写正例不写反例，导致误触发频繁。后来在每个 skill 描述里加一句“不适用于某某情况”，误触发明显下降。反例和正例一样重要，甚至更重要，因为它定义了边界。

第三个坑是不写依赖。skill 里用了某个命令，没在元信息里声明，换台机器就挂。现在我的习惯是，只要 skill 里出现外部命令或文件，一律在依赖字段里列出来，宁可多写不可漏写。

第四个坑是改完不测。改了一行描述觉得无所谓，结果触发全乱。现在改任何 skill，哪怕只改一个词，也要跑一遍测试用例。测试用例不用多，三五个能覆盖主要场景就行，关键是每次改都跑。

最后分享一个小技巧：给 skill 写一个“变更日志”段落，记下每次改了什么、为什么改。过几个月回头看，能快速回忆起当时的决策背景，避免重复踩坑。这个习惯看起来麻烦，实际省的时间远超记录的成本。