最近我在折腾 Agent Skills 这件事断断续续玩了几周从踩坑到稳定产出中间有不少体会。网上关于 Skills 的概念讨论很多但真到动手阶段不少人还是卡在这东西到底是啥、我的场景适不适用、文件到底该放哪这种一半靠文档一半靠猜的问题上。这篇文章打算把我自己的实践路径完整拆一遍适合对 Agent 开发刚入门的人也适合已经在用 Claude、Codex 这类工具但一直没有正式接过 Skills 的普通用户。先直接说结论Agent Skills 本质上就是给 AI 助手配一份标准作业指导书 配套脚本的组合包。它解决两件事一是把重复性的任务描述固化下来不用每次重新打几十行 Prompt二是让输出格式和动作流程可控减少模型自由发挥带来的偏差。我实际用过之后最大的感受就是以前那种每次都要把需求重新解释一遍的疲劳感消失了不少很多操作只要一句话就能触发而且结果稳定得多。1. Agent Skills 到底是个什么东西1.1 一个 Skill 的内部结构很多人第一次接触 Skills把它理解成一段长 Prompt这个理解不算错但漏掉了最关键的脚本部分。一个标准的 Skill 目录通常包含一个人类可读的说明文件SKILL.md以及若干可执行的脚本或模板文件。SKILL.md负责告诉 Agent什么时候用我、我是干嘛的、该怎么用脚本则负责实际的机械性工作比如解析数据、调用 API、生成特定格式的文件。以我写的分镜脚本 Skill 为例目录结构是这样的~/.claude/skills/storyboard/ ├── SKILL.md └── scripts/ └── create_storyboard.pySKILL.md里的内容看起来像这样--- name: storyboard description: 根据用户提供的文字描述生成视频分镜脚本输出镜头号、景别、运镜、画面描述、台词和时长。当用户提到分镜、镜头、视频脚本时使用。 --- # 视频分镜生成 把情节描述拆解为可执行的镜头列表格式固定为表格。 ## 工作流程 1. 分析用户给出的场景文本。 2. 按语义切分镜头。 3. 对每个镜头补充景别、运镜、画面细节、台词与建议时长。 4. 输出 Markdown 表格保持结构一致。这种设计不是随便定的它背后有个很重要的原则把思考策略和机械执行分开。Agent 擅长的是理解需求、拆解逻辑、写出自然语言描述脚本擅长的是精确、稳定地做重复计算。让两者各干各擅长的部分整个 Skill 才既灵活又可靠。1.2 和普通 Prompt、Function Call 有什么区别我在写 Skills 之前用的主要是两条路一是把常用指令写成大段 Prompt需要时复制进去二是在程序里注册 Function Call让模型调用接口。这两条路都有明显局限。普通 Prompt 的问题是它太软了。同样一段指令模型在不同上下文里发挥差异很大改一个措辞输出格式就可能跑偏。而且 Prompt 没有配套的执行逻辑像分镜这种需要做文本切分、生成固定结构的任务光靠 Prompt 让模型硬输出格式经常不稳定。你让它输出表格它给你输出列表你强调三遍必须是五列它还是可能漏掉一列。Function Call 则相反它太硬了。每个函数都要提前定义参数、注册接口适合单次精确调用但不适合承担一段完整的、多步骤的工作流。你很难把一个写分镜的完整流程塞进一个 function 里硬塞的话函数签名会变得非常复杂维护成本直线上升。Skills 更像是中间形态文档部分负责描述目标和边界脚本部分负责具体动作Agent 自己判断现在该不该用。你不需要在每次对话里给它塞完整说明它读到场景自然会去翻 Skill。1.3 为什么说它是 Agent 能力的乐高我后来想明白了一个比喻Prompt 是一次性口头吩咐Function Call 是单个按钮而 Skill 是一盒带着说明书的标准件。单独拿一块出来都不稀奇但当你攒了一批 Skill就相当于给 Agent 建了一套可拼装的能力库。比如我做的内容工作流里一个 Skill 管分镜一个 Skill 管素材清洗还有一个 Skill 管文章结构拆解。它们互相独立又能拼在一起用先用清洗 Skill 整理素材再用结构拆解 Skill 规划文章最后套一个排版 Skill 固化输出。这种组合能力才是我觉得 Skills 真正值钱的地方。2. 第一次实操5 分钟写一个分镜 Skill2.1 目录结构与环境准备动手之前先确认一下你的 Agent 工具是否支持 Skills。目前主流的 Claude 和 Codex 都支持基于SKILL.md约定的机制存放目录有用户级和项目级两类一般放在用户目录下的skills文件夹里。用户级目录对所有对话生效项目级目录只对当前项目生效。你自己开发验证阶段放用户级目录最省事。环境方面不需要额外装什么依赖只要确保 Python 可运行就行。分镜脚本用 Python 写是因为处理文本方便、跨平台通用、Agent 调用时不用编译。在 macOS 和 Linux 上一般自带 Python 3Windows 用户装了 Python 环境也没问题。2.2 SKILL.md 的写法SKILL.md是整个 Skill 的灵魂它的写法直接决定 Agent 会不会在正确时机调用你。第一行 front-matter 里的name用简短的项目名description必须写清楚两件事这个 Skill 解决什么问题以及什么情况下该用它。我踩过一个典型坑description 写得太泛比如处理文本这种描述结果模型在改写邮件、纠错、做摘要时都会尝试把它拉出来输出经常不合预期。后来我把 description 改成当用户提供一段视频情节描述并希望生成分镜表格时使用误触发的情况就明显少了。这个细节看着不起眼但对实际体验影响极大。正文部分要用清晰的当...时使用不要用于...来定义边界同时给出工作流程和输出格式示例。模型很依赖示例来对齐格式给一个完整的输出样例比写十句要注意格式都管用。2.3 脚本部分怎么写脚本的职责是处理那些模型不擅长精确执行的部分比如把文本切分、生成固定结构的数据。我写分镜 Skill 时用了一个很简单的 Python 脚本#!/usr/bin/env python3 import sys import json import re def parse_input(raw): return raw.strip() def generate_storyboard(text): # 按句子边界切分镜头 sentences re.split(r[。\n], text) sentences [s for s in sentences if s] rows [] for i, sent in enumerate(sentences, 1): rows.append({ shot: i, scene_type: 中景, camera: 固定, visual: sent, dialogue: , duration: 5s }) return rows if __name__ __main__: raw sys.stdin.read() storyboard generate_storyboard(raw) print(json.dumps(storyboard, ensure_asciiFalse, indent2))你可能注意到了脚本里很多字段比如景别、运镜是给了一个默认值这没问题。AI 会在调用脚本前读SKILL.md它会基于用户的具体描述去修改脚本输出或者补充更合理的镜头设计。脚本给的是一个稳定的骨架AI 做的是往骨架里填肉。这样分工的好处是格式永远不会乱。就算模型这次发挥不佳脚本输出的 JSON 结构还是完整的后续格式化、出表格、甚至推到剪辑软件里都不会崩。2.4 安装、触发与验证把目录放到~/.claude/skills/下面重启会话Skill 就会被扫描到。触发分两种显式触发就是在对话里直接说帮我把这段文字转成分镜脚本自动触发则是让模型自己判断。为了测试效果我建议第一次用显式方式。验证时重点看三件事模型有没有读到SKILL.md中的工作流程、有没有真的调用脚本、输出格式是不是和你预期的一致。如果模型只用自然语言描述分镜而没跑脚本说明它没有把任务判断成该走 Skill 流程。此时检查一下 description 是否写得够明确或者直接在当前对话里把目录路径指给它。3. 从能用到好用Skill 开发的进阶要点3.1 description 和触发边界的艺术前面提过 description 的重要性这里展开说。好的 description 本质上是一个分类器它决定了模型在无数可能的请求中会不会精确命中你这个 Skill。我的经验是description 里至少要包含三样东西能力范围能做什么、触发信号哪些话术或场景会用到它、禁用边界哪些场景不要乱用。举个反例如果你只写处理视频分镜模型在用户问什么是分镜时也可能去调用它因为语义上沾边了。但如果你写当用户提供一段可以拍摄的情节描述并需要拆分镜头时使用不用于解释概念误触发率会降低非常多。边界写得越细Skill 的自主性才越可靠这恰恰是好用的关键。3.2 规范化输入输出我见过不少 Skill内部逻辑没问题但输入输出一团乱导致没法被其他环节复用。规范化分三层第一层是脚本内部建议用明确的parse函数处理输入不直接拿裸数据运算第二层是输出格式能出 JSON 就别出纯文本JSON 可以让 Agent 二次加工时更准确地理解内容第三层是错误处理空输入和缺字段要给出明确提示而不是让脚本崩溃。在分镜例子里我要求脚本输出固定字段shot、scene_type、camera、visual、dialogue、duration。这些字段后来直接对接了剪辑时间线模板省掉了大量手工转录时间。这让我意识到写 Skill 的时间有一部分是在做数据建模而不是写功能。3.3 多脚本组合与版本管理Skill 内部不一定只有一个脚本。复杂任务可以拆成多个脚本比如一个run.py做入口调度一个validate.py做输出校验一个format.py做最终格式化。这种拆分让每个脚本都很短模型读起来也不费劲。版本管理同样别忽略。Skills 本质是代码工程把整个 Skill 目录放进 Git 仓库里每轮优化都留个 commit。我经历过一次灾难式改动把分镜脚本的输出字段重命名后忘了更新SKILL.md的示例结果模型照着旧格式调整脚本按新格式输出两边冲突整个流程崩掉。后来我把SKILL.md和脚本放在同一目录、同一 Git 仓库里强制绑定再没出过这种问题。3.4 测试与迭代的心得测试 Skill 和测试普通程序不一样因为中间夹了一个不稳定层模型。我常用的方法是准备一个测试集里面包含 5-6 个典型输入覆盖正常场景、边缘场景和不该触发场景。每一次改动后都拿测试集跑一遍观察模型行为变化的走向。迭代时要紧盯脏数据或格式歪斜的地方。第一版分镜 Skill 输出的视觉描述经常太短只有一两个字这对实际拍摄没什么用。我在SKILL.md里特意加了一句每段画面描述不少于 15 个字要包含主体、动作、环境再跑结果就好了很多。这个例子说明在很多情况下你需要调的不是脚本逻辑而是给模型的说明文本。4. 当下最值得投入的 Skills 方向4.1 前端与工程提效很多做前端开发的朋友已经把 Skills 纳入日常流程了。常见做法是把团队代码规范、常用组件模式、脚手架模板写成一个 Skill让 Agent 直接生成符合规范的代码片段。这样做最大的收益是一致性不同人写的代码风格可能不同但 Agent 生成的代码因为始终走同一套 Skill风格和架构都统一。我见过有人把项目的 eslint 规则、组件库约定、提交信息格式都塞进 Skill 里效果相当好。代码生成类 Skill 特别适合把机械规则文档化因为规则是明确的模型照着执行不太容易出错。这个方向对于开发团队至少有两点价值新同学上手快老同学省去重复 review 基础规范的时间。4.2 写作、研究与内容创作写作类 Skills 是我自己用得最多的。别看有些人调侃用 Skill 写论文听起来像偷懒实际操作下来这个方向的正确用法应该放在辅助而不是代写把文献整理、结构搭架、摘要提炼、引用核验这些环节做标准化。比如文献整理的 Skill可以要求输出统一的条目格式包含作者、年份、核心结论、与本次研究的关联这样后续写综述时素材就是现成的。分镜、短视频脚本、文案结构这类内容创作场景也很适合 Skills。因为它们都有相对固定的模板而模型天然擅长创意发散两者结合起来效果很好。我写分镜 Skill 的直接触发点就是发现每次让 AI 出分镜我都要在对话里把输出格式重新粘贴一遍太累了。4.3 安全审计中的克制使用搜 Skills 资源时能看到自动挖洞 skills这类词我必须提醒一句安全测试类的自动化操作有严格的法律边界。在我接触过的靠谱团队里这类 Skill 的正确打开方式是用于授权范围内的辅助审计比如把常规的资产信息收集、已知漏洞检测项的复现流程封装成脚本让 Agent 帮助整理报告。任何涉及安全测试的能力前提都是书面授权并且应该由人对参数和执行范围做最终控制绝对不建议让 Agent 全自主执行漏洞利用行为。这个领域价值大但入行门槛不只是技术还有合规意识。4.4 为什么行家说打开新世界很多人第一次稳定跑通一个 Skill 时会觉得打开新世界我也有同感。这种体验的来源不是因为 Skill 本身多复杂而是它改变了一个根本的工作模式过去你是在和 AI对话每一次都是从零开始描述现在你是在和一个积累了经验值的 AI协作你的能力库在慢慢变大。今天你写了一个分镜 Skill明天加一个数据分析 Skill后天加一个报告排版 Skill。这些能力不断沉淀Agent 能处理的复杂度就会越来越高。你可能会发现以前需要完整规划才能让 AI 做的事现在随便甩给它一个相关任务它就会自己调用合适的 Skill帮你完成。5. 常见问题与避坑速查5.1 问题排查表实际使用中我整理了一张排查表遇到问题可以先对着查现象大概率原因处理方式Agent 完全不调用 Skill目录位置不对或 description 里没有触发信号检查skills目录路径重启会话明确触发话术调用了但没用脚本SKILL.md 正文流程写得不够清楚在文档里突出必须执行脚本并基于输出继续输出格式不稳定SKILL.md 中缺少完整示例在文档里增加一段完整的输出示例脚本报中文乱码Python 输出编码未指定 UTF-8脚本中确保输出前用ensure_asciiFalse或设置环境变量Agent 在无关场景触发 Skilldescription 写得太泛收窄边界写明不用于...脚本提示缺少依赖脚本用了第三方库但没声明在 SKILL.md 中写明依赖与安装命令5.2 我踩过的一些坑第一个坑description 写得太短导致模型把分镜 Skill 当成通用创作工具写章回体小说时都要去调用输出的画面描述塞进小说里毫无用处。那次的教训是写 description 时务必把自己放在分类器的位置去抠细节。第二个坑脚本依赖环境变量和第三方包没有声明。一个图像处理的 Skill在本地跑得好好的换到另一个环境就报ModuleNotFoundError而且模型没有权限自动装包整个流程就卡住了。后来我在所有 Skill 的SKILL.md顶部都加了一个依赖与准备小节把pip install命令直接写进去。第三个坑输出没有做二次校验。早期分镜脚本输出 JSON 后我没做字段校验某次输入的文本太长脚本切出了几十个镜头导致后续 Agent 处理时上下文被撑爆。后来我在脚本里加了一个镜头数量上限超出时自动提示分段处理问题就解决了。5.3 下一步可以怎么扩展一个 Skill 跑通之后千万别停在这里。我自己的做法是先跑一周记录下哪些输出还要人工改然后回过头迭代文档和脚本。第二个方向是尝试让多个 Skill 联动比如素材清洗 Skill 输出直接传给分镜 Skill 作输入中间不需要人手整理。第三个方向是去 GitHub 等平台找别人分享的 Skill 来学习尤其是看他们的SKILL.md怎么组织、边界怎么描述、脚本怎么调度然后吸取经验改造自己的。最后再分享一个小技巧写完一个 Skill 后不妨假设自己完全不知道内部实现只把最终结果复现一遍。比如给一个分镜 Skill 喂一段真实文案然后问自己这个表格我能不能直接交到剪辑手里如果还需要手动改结构就回到SKILL.md调输出模板。我在开发分镜 Skill 时就是这样反复调整了好几版才做到现在一句话触发表格直接可用的效果。这个原则对所有内容生成类的 Skill 都适用检验一个 Skill 是不是好用不是看过程多顺而是看结果能不能省掉人工。