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 怎么知道该用哪个 skillskills 能不能用起来核心在触发。常见做法有两种一种是描述匹配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. 实操流程从零写一个能用的 skill4.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 常见问题速查表问题现象可能原因排查动作解决方向该触发没触发描述太窄或语言不匹配放宽描述补中英文关键词调整描述重测正反例不该触发乱触发描述太宽或名称歧义加反例说明改名称收紧描述明确边界执行到一半报错依赖缺失或权限不足手动执行该步骤补依赖声明加环境检查输出格式漂移约束不硬或温度过高对照模板检查加严格模板调低温度多 skill 冲突优先级未定义检查加载顺序分层管理显式声明优先级跨平台失效路径或命令不兼容换系统测试用相对路径避免平台特有命令这张表是我自己排查时用的基本覆盖八成常见问题。遇到新问题先归类再按对应方向处理比盲目改文件高效得多。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 写一个“变更日志”段落记下每次改了什么、为什么改。过几个月回头看能快速回忆起当时的决策背景避免重复踩坑。这个习惯看起来麻烦实际省的时间远超记录的成本。