1. 为什么“skills”突然成了Agent圈的热词最近无论刷社区还是看技术群到处都在说“skills”这个词而且基本都集中在同一个语境里AI Agent 的 skills。有人第一次接触之后说“今天学会了skills打开新世界”也有人把 skill 描述成“superpower skills”还有人在 GitHub 上疯狂收集“skills大全”。我自己把这些东西完整玩了一圈之后最直观的感受是这只是把以前散落在提示词里的“隐性经验”变成了可以被 Agent 随时调用的“显性能力包”。你可以把它理解成一种“给 Agent 用的操作手册 工具箱”。打开一个 skill里面可能是一个 Markdown 文档也可能搭配几个脚本目标都是让 Agent 在特定场景下不再从零摸索而是按一套已经被验证过的流程干活。市面上目前最常被提到的就是 Claude Agent Skills 和 Codex Skills 这两类前者偏通用型 Agent 工作流后者更侧重代码仓库内的开发任务但底层思路是一致的。这篇文章不打算做那种纯翻译的“原理解读”而是从我实际下载、安装、编写、调试 skills 的体验出发把核心机制、工程结构、找资源渠道、常见坑和设计心得一次讲透。适合三类人看想弄明白 skills 跟普通提示词到底有什么区别的初学者已经会用但想自己写 skill 的开发者以及正在考虑把技能包引入团队工作流、但又担心安全和维护成本的人。1.1 一个比“插件”更贴近直觉的类比如果你的第一反应是“这不就是插件吗”我得说像但不完全一样。传统插件是给软件增加一个独立功能模块而 skill 更像“给 Agent 装上的职业素养”。举个例子你把一个“论文润色 skill”丢给 Agent它打开后会看到一套非常具体的操作规范先分析段落结构再统一术语最后按目标期刊风格调整语态。这些内容原本可能是你每次都在对话框里重新输入的一段长提示词现在被固化成了一份文件。更直白地说普通提示词是“你告诉 Agent 怎么做”而 skill 是“Agent 看到任务后自己知道该去翻阅哪份操作手册”。这个“主动翻阅”的差异才是打开新世界的关键。因为 Agent 不会再凭大模型的泛化能力瞎猜而是被引导到一个更可控的流程里。试过几次之后你会发现用同一个 skill 处理同类任务输出质量的稳定程度明显上升。1.2 它和传统提示词、function calling 的区别我整理了一张表方便对照理解对比项普通提示词Function CallingAgent Skill载体对话框里的文本接口定义文件目录 Markdown 可选脚本作用时机每次都手动输入模型判定需要调用时触发Agent 按描述自动匹配并加载可复用性差靠复制粘贴较好但偏底层调用强可分发、可组合维护成本低但碎片化高要改代码中改文档即可能力边界纯文本指导外部工具/API流程规范 工具脚本 知识库这里最容易被误解的一点是skill 并不替代 function calling也不替代 MCP。MCP 更偏向给 Agent 暴露“实时工具”比如查数据库、调 API而 skill 更像是在说“做这一类事情时应该按什么思路来”。两者可以同时存在一个负责提供能力一个负责提供方法和流程。搞清这个边界后面筛选和学习会顺畅很多。2. 从“每次重新告诉模型”到“沉淀为肌肉记忆”我最早接触 skills 时也有点不以为然觉得无非是把提示词换个姿势写。真正让我改变想法的是一个特别小的场景。我经常需要给短视频写分镜脚本每次都要在对话框里重复输入“请按景别、画面内容、台词、时长四个维度来写”还得补一句“分镜表要能直接给摄影师看”。这个提示词我用了快两个月还是会偶尔因为漏掉某段描述导致输出不对。把这段逻辑封装成一个“分镜 skill”之后整个体验变了。我只需要说一句“给这个产品宣传视频写分镜”Agent 会自动读取 skill 定义按里面预设的表格格式、镜头逻辑、时长估算方式直接产出。最关键的还不是省了重复输入而是我发现它能稳定触发一套我自己可能都没总结完整的检查流程。比如 skill 里写好了高潮段镜头密度要高于铺垫段这个细节我平时根本不会想起写进提示词但固化到 skill 里就成了默认动作。这种“沉淀”带来的另一个好处是可以跨项目复用。以前我在不同项目里写前端页面审查代码的标准都不一样遇到复杂一点的提交经常要临时组织语言。后来我写了一个“前端 code review skill”把常见性能问题、可访问性缺失、组件拆分原则都写进去。只要是代码审查类任务Agent 便会自动按这套标准执行我在群里分享给同事大家也能直接用评价出奇一致输出像是一个熟悉团队规范的人写的评审意见。2.1 为什么别人家的 Agent 看起来像“Superpower Skills”我见过不少人在网上秀自己的 Agent 组合一个负责查资料做调研一个负责生成内容一个负责把内容转成固定格式的报表整个过程下来几乎不用管。这种效果不是模型的魔力而是他们把场景拆成了多个独立的 skill每个 skill 只解决一个环节。比如做调研类任务可以拆成“资料收集 skill”和“观点提炼 skill”做内容生产可以拆成“选题 skill”“初稿 skill”“排版 skill”。Agent 会按任务描述自动选择匹配的 skill甚至串联使用。当技能包足够多、边界足够清晰时整套系统的能力就不再是单个模型所能体现的“通用智能”而是一套被经验校准过的“专业流程”。这大概就是热词里“superpower skills”想表达的那种状态单个技能不算什么组合起来才恐怖。2.2 不同场景下的典型技能举例社区里流传较广的几类技能包也可以帮你更具体地感知这块能做什么。前端开发场景代码生成、样式规范检查、组件提取、依赖安全审查。这类 skill 通常会结合仓库里的配置文件输出能直接落地的代码建议。写作场景长文大纲、公众号排版、分镜脚本、论文结构优化。分镜类技能近期特别火因为 Stable Diffusion 之类的工具变多之后大家需要统一的分镜描述格式。研究场景文献摘要、术语表生成、复现步骤整理。Codex 写论文的 skill 之所以受关注是因为它能把“读论文—梳理方法—生成实验记录”这条链路标准化。安全测试场景自动化漏洞扫描、依赖风险评估、配置审计。这类技能通常被限制在合法授权或本地靶场环境里使用但流程本身很值得参考。这些场景背后的共同点是任务有明确结构、有重复性、有可沉淀的判断标准。反过来如果一件事每次做都天马行空没有固定套路那硬塞一个 skill 反而不如直接让模型自由输出。3. 自己动手写一个 Skill工程结构与实操步骤写 skill 的难度没有想象中高说白了就是搭好目录、写好描述文档、配上合适的脚本然后不断测试调优。我会以目前社区里比较常见的 Agent Skill 设计为例给你一个可以直接抄的模板。3.1 最小可用文件结构一个标准的 skill 通常长这样my-skill/ ├── SKILL.md ├── scripts/ │ ├── generate_split_screen.py │ └── requirements.txt └── assets/ └── templates/ └── split_screen_template.mdSKILL.md是整个技能的核心负责告诉 Agent “你是什么”“何时用你”“怎么用你”。scripts/放可执行的辅助脚本比如格式化输出、批量处理文件、调用本地工具。assets/放模板、参考文件、示例数据。对于 Agent 来说它会先读取SKILL.md的 frontmatter 和正文根据 description 判断是否匹配当前任务。所以 description 写得好不好直接决定技能能否被正确触发。很多人的技能“调不出来”八成问题都出在这一步。3.2 写好 SKILL.md 才是核心一个合格的SKILL.md至少包含以下内容元信息skill 名称和触发描述适用边界明确说什么情况可以用什么情况不该用执行步骤从输入到输出的操作流程输出格式要求模型最终输出的结构或模板参考示例一个完整的输入输出样例。举一个我实际在用的“分镜脚本生成 skill”示例核心文档是这样的--- name: 分镜脚本生成 description: 当用户需要为短视频、宣传片、产品演示视频编写分镜脚本时使用。 输入可以是主题描述或完整文案输出为可直接用于拍摄的表格分镜。 --- # 分镜脚本生成 ## 适用场景 - 产品宣传视频 - 社媒短视频 - 活动记录短片 ## 执行步骤 1. 读取用户提供的主题或文案提炼出 3 到 5 个关键信息点。 2. 按“引入—展开—高潮—收尾”的结构拆分段落。 3. 对每个段落规划景别、画面内容、字幕、时长和音效建议。 4. 将结果输出为 Markdown 表格。 ## 输出格式 | 序号 | 景别 | 画面描述 | 台词/字幕 | 时长 | 备注 | | ---- | ---- | ---- | ---- | ---- | ---- | ## 注意点 - 高潮段落镜头切换密度应高于铺垫段落。 - 单个镜头时长建议控制在 2 到 5 秒。 - 画面描述要具体到光线、主体动作和背景环境。这个文档不到 40 行但已经把目标、边界、流程、格式和注意事项都覆盖到了。我实测下来模型按这套流程产出的结果比单纯给一句“帮我写分镜”稳定得多因为每一层的判断标准都被明确写出来了。3.3 脚本部分怎么选型SKILL.md能覆盖纯文字流程但遇到需要操作文件、调用接口、批量处理场景最好配一个脚本。选型的核心原则是别为了炫技而加脚本。一个纯文本任务完全可以用 Markdown 文档解决硬加 Python 脚本反而会让依赖变多、出错概率变大。如果是需要跑脚本的场景我一般会用 Python因为它兼容性最好。配上一个requirements.txt把依赖列清楚然后在SKILL.md的执行步骤里写明“先用pip install -r scripts/requirements.txt安装依赖再运行python scripts/xxx.py”。Agent 在生成内容时看到这类指令通常会先执行环境检查再运行脚本整体下来流程感很强。4. 去哪里找现成的 Skills以及安装避坑指南对多数人来说先从现成的技能包开始体验是最快的路径。但如果只知道去 GitHub 搜“skills”很容易搜出一堆垃圾仓库。根据我这段时间的搜集经验渠道可以分成几类。4.1 值得关注的几类渠道渠道特点适合人群官方 Skill 市场经过官方审核格式统一支持搜索和直接安装新手首选GitHub 主题仓库数量大质量参差需要人工筛选有一定鉴别能力的人个人博客/社区分享作者有详细使用说明常附带实战案例想了解具体玩法的人聚合导航站将分散技能包分类整理方便批量发现想快速看全部类目的人GitHub 上搜awesome-agent-skills这类主题能找到不少汇总列表。下载前优先看仓库的 stars、更新时间、README 是否写清楚使用方式和测试结果。如果一个仓库只有代码没有说明或者作者连示例输出都不敢贴老老实实绕开没必要拿自己环境去试错。4.2 安装与启用三种常见方式不同 Agent 工具的安装机制不完全一致但大致可以归为三类自动市场安装在 Agent 配置里搜索技能名点击安装。这种方式最简单适合新手。手动拷贝到技能目录把下载的 skill 文件夹放到 Agent 指定的 skills 路径下再在配置里启用。这种方式最通用也最容易理解。基于版本管理安装直接把仓库git clone到技能目录方便后续git pull更新。我个人的习惯是除非市场里明确有官方标识否则优先用第二种方式。原因很简单我能清楚看到技能包落在哪个目录、里面包含哪些文件后续排查出问题也能快速移除。更高阶一点的做法是把多个技能统一放在一个目录里纳入 Git 管理这样团队协作时每个人拉下来就能用。4.3 装第三方技能前必须做安全审查这部分我必须多说几句。Skill 的核心是 Markdown 文档但它可能携带脚本脚本会在本地环境执行。如果脚本写得有问题轻则报错重则可能做一些你没预期到的操作。我现在的检查步骤基本固定打开SKILL.md通读一遍确认描述与用途一致逐个打开scripts/下的脚本重点看有没有执行系统命令、读写异常路径的代码检查是否存在混淆过的代码片段比如 base64 解码执行这种在测试环境先跑一遍流程确认行为符合预期再放入日常使用的目录。提示不要从无法溯源的地方获取技能包也不要因为某个作者粉丝多就跳过审查。技能的运行环境是你的电脑执行权限也是你的。花五分钟读代码能省掉很多麻烦。5. 实测中踩过的坑与排查清单代码写多了都会踩坑skills 也不例外。我遇到的典型问题可以整理成一个速查表希望对你有参考价值。现象可能原因排查思路技能从来没被触发description 写得太模糊Agent 无法匹配优化 frontmatter 里的触发描述加入明确任务关键词触发了但输出格式乱了输出模板不够明确在SKILL.md中给出最终格式的完整示例运行时报错找不到模块脚本依赖未安装检查requirements.txt是否与脚本一致优先用虚拟环境脚本权限不足可执行文件没有chmod x显式给脚本加执行权限跨平台路径混乱Windows 与 Linux 路径分隔符不同脚本里用pathlib处理路径不要硬编码/或\\技能之间冲突多个技能 description 互相覆盖尽量让每个技能覆盖独立场景避免描述交叉5.1 技能没被调用的“玄学”问题技能用不出来十次里有七次是 description 写得不够好。Agent 判断是否调用某个技能靠的是语义匹配不太可能像人一样“感受”你的意图。如果你的 description 写的是“视频脚本”而你的需求是“拍一个产品介绍短片”匹配度就可能不足。我的写法是把可能的用户输入变体都列进去再提供典型任务的示例描述。另外如果多个技能的描述相近Agent 可能选错。我自己吃过一次亏同时装了“PPT 大纲生成”和“汇报文案生成”开会前想写演讲稿结果 Agent 把 PPT 大纲调出来了。后来把两个技能的描述边界重新划清问题才消失。技能描述之间要尽量“各管一摊”。5.2 脚本报错与环境不一致我最早遇到的一个报错是 Python 脚本里用了/tmp作为临时目录在 Windows 环境直接崩溃。这其实是脚本作者没有做跨平台处理。后来我在自己的技能里统一改用tempfile模块就没再出过问题。遇到别人的技能包时我也会先看脚本里有没有硬编码路径有就直接放弃因为这类问题后续维护起来很痛苦。还有一个容易被忽略的坑Agent 在调用脚本时可能没有激活你预期的 Python 环境。所以如果某个技能依赖第三方库我通常会在步骤说明里要求 Agent 先执行环境安装命令再运行脚本。这样虽然会多花一点时间但能避免“模块不存在”的尴尬。5.3 权限与依赖问题Linux 或 Mac 环境下的脚本文件下载后经常没有执行权限。解决方式很简单chmod x scripts/xxx.py。如果你在团队里分发技能包记得在 README 里写清楚这一步否则别人第一次用一定会卡住。依赖方面强烈建议给每个技能配独立的虚拟环境或者至少一个明确的requirements.txt。它可能只是一个小脚本但 Agent 环境往往装了多个技能依赖之间的版本冲突很容易让人头大。把环境隔离好运行稳定度会提升一个档次。6. 几个让我觉得“进阶”的设计心得如果你已经会安装技能、也会写简单技能下一步就是思考如何把技能设计得更好。这部分是我自己实践里有感触的几个点。6.1 一个技能只做一件事看似很简单但特别容易违反。我在早期写过一个大而全的“内容创作 skill”涵盖选题、写稿、排版、配图建议结果每次调用都变慢输出重点也不突出。后来狠下心把它拆成四个独立技能每个只负责一段准确度和速度都上来了。一个技能的最佳状态是“看到描述就知道它能干什么”。描述里一旦出现“同时”“以及”“还可以”这类词大概率就是职责过重。别不舍得拆技能之间可以组合调用这比一个万能技能可靠得多。6.2 先固定输出格式再写执行步骤我写技能时习惯把结尾的输出样例先写出来再去补前面的执行步骤。这和正常写作习惯是反的但对 Agent 特别有效。当模型知道最终要交付什么样的东西它每一步的执行都会朝向那个结构聚合而不是自由发挥。比如写分镜技能我先定义好“序号、景别、画面描述、台词、时长”这个表格再告诉模型“请按每 30 字一个镜头的方式拆分文案”。有了明确终点输出质量会立刻提升。这个思路同样适用于 code review 技能先规定输出必须包含“问题等级、影响范围、修改建议”三个区块再让 Agent 去扫描代码。6.3 做测试时别只测“正常路径”我在给技能设计完流程后会特意拿几个“边界输入”来测试。比如分镜技能我会给它一段没有明显情绪起伏的产品说明书看它能不能找出高潮点比如代码审查技能我会给它一段没有注释但逻辑清晰的代码看它会不会硬编出问题。边界输入能帮你发现技能的盲区也能提醒你把规则写得更完整。另外我会坚持把测试样例和输出结果记录在技能仓库的 README 里。下次改了一个描述直接跑一遍样例就能知道有没有把原有行为弄坏。这相当于给技能本身做“回归测试”长期下来能省不少力气。最后分享一个个人体会不要一上来就囤几十个技能包。我刚开始玩的时候看到 GitHub 上好的仓库就拉下来放进技能目录结果真正频繁用到的只有三四个其余的全躺在那里增加干扰。更合理的做法是把最近一个月最常让 Agent 做的十件事列出来优先为其中重复次数最多的两三个场景配置技能用熟了再慢慢扩展。技能的质量永远比数量重要一个好的技能带来的效率提升远胜过二十个用不上的技能占的那点存在感。如果你也想体验一把“打开新世界”的感觉先别急着四处搜刮挑一个小任务自己写一个技能跑通那种掌控感比任何现成包都来得更踏实。 
长河君 · 2026/10/29 14:17:14 · 阅读 1.2k AI Agent Skills完全指南：从提示词思维升级到技能工程
1. 为什么“skills”突然成了Agent圈的热词最近无论刷社区还是看技术群到处都在说“skills”这个词而且基本都集中在同一个语境里AI Agent 的 skills。有人第一次接触之后说“今天学会了skills打开新世界”也有人把 skill 描述成“superpower skills”还有人在 GitHub 上疯狂收集“skills大全”。我自己把这些东西完整玩了一圈之后最直观的感受是这只是把以前散落在提示词里的“隐性经验”变成了可以被 Agent 随时调用的“显性能力包”。你可以把它理解成一种“给 Agent 用的操作手册 工具箱”。打开一个 skill里面可能是一个 Markdown 文档也可能搭配几个脚本目标都是让 Agent 在特定场景下不再从零摸索而是按一套已经被验证过的流程干活。市面上目前最常被提到的就是 Claude Agent Skills 和 Codex Skills 这两类前者偏通用型 Agent 工作流后者更侧重代码仓库内的开发任务但底层思路是一致的。这篇文章不打算做那种纯翻译的“原理解读”而是从我实际下载、安装、编写、调试 skills 的体验出发把核心机制、工程结构、找资源渠道、常见坑和设计心得一次讲透。适合三类人看想弄明白 skills 跟普通提示词到底有什么区别的初学者已经会用但想自己写 skill 的开发者以及正在考虑把技能包引入团队工作流、但又担心安全和维护成本的人。1.1 一个比“插件”更贴近直觉的类比如果你的第一反应是“这不就是插件吗”我得说像但不完全一样。传统插件是给软件增加一个独立功能模块而 skill 更像“给 Agent 装上的职业素养”。举个例子你把一个“论文润色 skill”丢给 Agent它打开后会看到一套非常具体的操作规范先分析段落结构再统一术语最后按目标期刊风格调整语态。这些内容原本可能是你每次都在对话框里重新输入的一段长提示词现在被固化成了一份文件。更直白地说普通提示词是“你告诉 Agent 怎么做”而 skill 是“Agent 看到任务后自己知道该去翻阅哪份操作手册”。这个“主动翻阅”的差异才是打开新世界的关键。因为 Agent 不会再凭大模型的泛化能力瞎猜而是被引导到一个更可控的流程里。试过几次之后你会发现用同一个 skill 处理同类任务输出质量的稳定程度明显上升。1.2 它和传统提示词、function calling 的区别我整理了一张表方便对照理解对比项普通提示词Function CallingAgent Skill载体对话框里的文本接口定义文件目录 Markdown 可选脚本作用时机每次都手动输入模型判定需要调用时触发Agent 按描述自动匹配并加载可复用性差靠复制粘贴较好但偏底层调用强可分发、可组合维护成本低但碎片化高要改代码中改文档即可能力边界纯文本指导外部工具/API流程规范 工具脚本 知识库这里最容易被误解的一点是skill 并不替代 function calling也不替代 MCP。MCP 更偏向给 Agent 暴露“实时工具”比如查数据库、调 API而 skill 更像是在说“做这一类事情时应该按什么思路来”。两者可以同时存在一个负责提供能力一个负责提供方法和流程。搞清这个边界后面筛选和学习会顺畅很多。2. 从“每次重新告诉模型”到“沉淀为肌肉记忆”我最早接触 skills 时也有点不以为然觉得无非是把提示词换个姿势写。真正让我改变想法的是一个特别小的场景。我经常需要给短视频写分镜脚本每次都要在对话框里重复输入“请按景别、画面内容、台词、时长四个维度来写”还得补一句“分镜表要能直接给摄影师看”。这个提示词我用了快两个月还是会偶尔因为漏掉某段描述导致输出不对。把这段逻辑封装成一个“分镜 skill”之后整个体验变了。我只需要说一句“给这个产品宣传视频写分镜”Agent 会自动读取 skill 定义按里面预设的表格格式、镜头逻辑、时长估算方式直接产出。最关键的还不是省了重复输入而是我发现它能稳定触发一套我自己可能都没总结完整的检查流程。比如 skill 里写好了高潮段镜头密度要高于铺垫段这个细节我平时根本不会想起写进提示词但固化到 skill 里就成了默认动作。这种“沉淀”带来的另一个好处是可以跨项目复用。以前我在不同项目里写前端页面审查代码的标准都不一样遇到复杂一点的提交经常要临时组织语言。后来我写了一个“前端 code review skill”把常见性能问题、可访问性缺失、组件拆分原则都写进去。只要是代码审查类任务Agent 便会自动按这套标准执行我在群里分享给同事大家也能直接用评价出奇一致输出像是一个熟悉团队规范的人写的评审意见。2.1 为什么别人家的 Agent 看起来像“Superpower Skills”我见过不少人在网上秀自己的 Agent 组合一个负责查资料做调研一个负责生成内容一个负责把内容转成固定格式的报表整个过程下来几乎不用管。这种效果不是模型的魔力而是他们把场景拆成了多个独立的 skill每个 skill 只解决一个环节。比如做调研类任务可以拆成“资料收集 skill”和“观点提炼 skill”做内容生产可以拆成“选题 skill”“初稿 skill”“排版 skill”。Agent 会按任务描述自动选择匹配的 skill甚至串联使用。当技能包足够多、边界足够清晰时整套系统的能力就不再是单个模型所能体现的“通用智能”而是一套被经验校准过的“专业流程”。这大概就是热词里“superpower skills”想表达的那种状态单个技能不算什么组合起来才恐怖。2.2 不同场景下的典型技能举例社区里流传较广的几类技能包也可以帮你更具体地感知这块能做什么。前端开发场景代码生成、样式规范检查、组件提取、依赖安全审查。这类 skill 通常会结合仓库里的配置文件输出能直接落地的代码建议。写作场景长文大纲、公众号排版、分镜脚本、论文结构优化。分镜类技能近期特别火因为 Stable Diffusion 之类的工具变多之后大家需要统一的分镜描述格式。研究场景文献摘要、术语表生成、复现步骤整理。Codex 写论文的 skill 之所以受关注是因为它能把“读论文—梳理方法—生成实验记录”这条链路标准化。安全测试场景自动化漏洞扫描、依赖风险评估、配置审计。这类技能通常被限制在合法授权或本地靶场环境里使用但流程本身很值得参考。这些场景背后的共同点是任务有明确结构、有重复性、有可沉淀的判断标准。反过来如果一件事每次做都天马行空没有固定套路那硬塞一个 skill 反而不如直接让模型自由输出。3. 自己动手写一个 Skill工程结构与实操步骤写 skill 的难度没有想象中高说白了就是搭好目录、写好描述文档、配上合适的脚本然后不断测试调优。我会以目前社区里比较常见的 Agent Skill 设计为例给你一个可以直接抄的模板。3.1 最小可用文件结构一个标准的 skill 通常长这样my-skill/ ├── SKILL.md ├── scripts/ │ ├── generate_split_screen.py │ └── requirements.txt └── assets/ └── templates/ └── split_screen_template.mdSKILL.md是整个技能的核心负责告诉 Agent “你是什么”“何时用你”“怎么用你”。scripts/放可执行的辅助脚本比如格式化输出、批量处理文件、调用本地工具。assets/放模板、参考文件、示例数据。对于 Agent 来说它会先读取SKILL.md的 frontmatter 和正文根据 description 判断是否匹配当前任务。所以 description 写得好不好直接决定技能能否被正确触发。很多人的技能“调不出来”八成问题都出在这一步。3.2 写好 SKILL.md 才是核心一个合格的SKILL.md至少包含以下内容元信息skill 名称和触发描述适用边界明确说什么情况可以用什么情况不该用执行步骤从输入到输出的操作流程输出格式要求模型最终输出的结构或模板参考示例一个完整的输入输出样例。举一个我实际在用的“分镜脚本生成 skill”示例核心文档是这样的--- name: 分镜脚本生成 description: 当用户需要为短视频、宣传片、产品演示视频编写分镜脚本时使用。 输入可以是主题描述或完整文案输出为可直接用于拍摄的表格分镜。 --- # 分镜脚本生成 ## 适用场景 - 产品宣传视频 - 社媒短视频 - 活动记录短片 ## 执行步骤 1. 读取用户提供的主题或文案提炼出 3 到 5 个关键信息点。 2. 按“引入—展开—高潮—收尾”的结构拆分段落。 3. 对每个段落规划景别、画面内容、字幕、时长和音效建议。 4. 将结果输出为 Markdown 表格。 ## 输出格式 | 序号 | 景别 | 画面描述 | 台词/字幕 | 时长 | 备注 | | ---- | ---- | ---- | ---- | ---- | ---- | ## 注意点 - 高潮段落镜头切换密度应高于铺垫段落。 - 单个镜头时长建议控制在 2 到 5 秒。 - 画面描述要具体到光线、主体动作和背景环境。这个文档不到 40 行但已经把目标、边界、流程、格式和注意事项都覆盖到了。我实测下来模型按这套流程产出的结果比单纯给一句“帮我写分镜”稳定得多因为每一层的判断标准都被明确写出来了。3.3 脚本部分怎么选型SKILL.md能覆盖纯文字流程但遇到需要操作文件、调用接口、批量处理场景最好配一个脚本。选型的核心原则是别为了炫技而加脚本。一个纯文本任务完全可以用 Markdown 文档解决硬加 Python 脚本反而会让依赖变多、出错概率变大。如果是需要跑脚本的场景我一般会用 Python因为它兼容性最好。配上一个requirements.txt把依赖列清楚然后在SKILL.md的执行步骤里写明“先用pip install -r scripts/requirements.txt安装依赖再运行python scripts/xxx.py”。Agent 在生成内容时看到这类指令通常会先执行环境检查再运行脚本整体下来流程感很强。4. 去哪里找现成的 Skills以及安装避坑指南对多数人来说先从现成的技能包开始体验是最快的路径。但如果只知道去 GitHub 搜“skills”很容易搜出一堆垃圾仓库。根据我这段时间的搜集经验渠道可以分成几类。4.1 值得关注的几类渠道渠道特点适合人群官方 Skill 市场经过官方审核格式统一支持搜索和直接安装新手首选GitHub 主题仓库数量大质量参差需要人工筛选有一定鉴别能力的人个人博客/社区分享作者有详细使用说明常附带实战案例想了解具体玩法的人聚合导航站将分散技能包分类整理方便批量发现想快速看全部类目的人GitHub 上搜awesome-agent-skills这类主题能找到不少汇总列表。下载前优先看仓库的 stars、更新时间、README 是否写清楚使用方式和测试结果。如果一个仓库只有代码没有说明或者作者连示例输出都不敢贴老老实实绕开没必要拿自己环境去试错。4.2 安装与启用三种常见方式不同 Agent 工具的安装机制不完全一致但大致可以归为三类自动市场安装在 Agent 配置里搜索技能名点击安装。这种方式最简单适合新手。手动拷贝到技能目录把下载的 skill 文件夹放到 Agent 指定的 skills 路径下再在配置里启用。这种方式最通用也最容易理解。基于版本管理安装直接把仓库git clone到技能目录方便后续git pull更新。我个人的习惯是除非市场里明确有官方标识否则优先用第二种方式。原因很简单我能清楚看到技能包落在哪个目录、里面包含哪些文件后续排查出问题也能快速移除。更高阶一点的做法是把多个技能统一放在一个目录里纳入 Git 管理这样团队协作时每个人拉下来就能用。4.3 装第三方技能前必须做安全审查这部分我必须多说几句。Skill 的核心是 Markdown 文档但它可能携带脚本脚本会在本地环境执行。如果脚本写得有问题轻则报错重则可能做一些你没预期到的操作。我现在的检查步骤基本固定打开SKILL.md通读一遍确认描述与用途一致逐个打开scripts/下的脚本重点看有没有执行系统命令、读写异常路径的代码检查是否存在混淆过的代码片段比如 base64 解码执行这种在测试环境先跑一遍流程确认行为符合预期再放入日常使用的目录。提示不要从无法溯源的地方获取技能包也不要因为某个作者粉丝多就跳过审查。技能的运行环境是你的电脑执行权限也是你的。花五分钟读代码能省掉很多麻烦。5. 实测中踩过的坑与排查清单代码写多了都会踩坑skills 也不例外。我遇到的典型问题可以整理成一个速查表希望对你有参考价值。现象可能原因排查思路技能从来没被触发description 写得太模糊Agent 无法匹配优化 frontmatter 里的触发描述加入明确任务关键词触发了但输出格式乱了输出模板不够明确在SKILL.md中给出最终格式的完整示例运行时报错找不到模块脚本依赖未安装检查requirements.txt是否与脚本一致优先用虚拟环境脚本权限不足可执行文件没有chmod x显式给脚本加执行权限跨平台路径混乱Windows 与 Linux 路径分隔符不同脚本里用pathlib处理路径不要硬编码/或\\技能之间冲突多个技能 description 互相覆盖尽量让每个技能覆盖独立场景避免描述交叉5.1 技能没被调用的“玄学”问题技能用不出来十次里有七次是 description 写得不够好。Agent 判断是否调用某个技能靠的是语义匹配不太可能像人一样“感受”你的意图。如果你的 description 写的是“视频脚本”而你的需求是“拍一个产品介绍短片”匹配度就可能不足。我的写法是把可能的用户输入变体都列进去再提供典型任务的示例描述。另外如果多个技能的描述相近Agent 可能选错。我自己吃过一次亏同时装了“PPT 大纲生成”和“汇报文案生成”开会前想写演讲稿结果 Agent 把 PPT 大纲调出来了。后来把两个技能的描述边界重新划清问题才消失。技能描述之间要尽量“各管一摊”。5.2 脚本报错与环境不一致我最早遇到的一个报错是 Python 脚本里用了/tmp作为临时目录在 Windows 环境直接崩溃。这其实是脚本作者没有做跨平台处理。后来我在自己的技能里统一改用tempfile模块就没再出过问题。遇到别人的技能包时我也会先看脚本里有没有硬编码路径有就直接放弃因为这类问题后续维护起来很痛苦。还有一个容易被忽略的坑Agent 在调用脚本时可能没有激活你预期的 Python 环境。所以如果某个技能依赖第三方库我通常会在步骤说明里要求 Agent 先执行环境安装命令再运行脚本。这样虽然会多花一点时间但能避免“模块不存在”的尴尬。5.3 权限与依赖问题Linux 或 Mac 环境下的脚本文件下载后经常没有执行权限。解决方式很简单chmod x scripts/xxx.py。如果你在团队里分发技能包记得在 README 里写清楚这一步否则别人第一次用一定会卡住。依赖方面强烈建议给每个技能配独立的虚拟环境或者至少一个明确的requirements.txt。它可能只是一个小脚本但 Agent 环境往往装了多个技能依赖之间的版本冲突很容易让人头大。把环境隔离好运行稳定度会提升一个档次。6. 几个让我觉得“进阶”的设计心得如果你已经会安装技能、也会写简单技能下一步就是思考如何把技能设计得更好。这部分是我自己实践里有感触的几个点。6.1 一个技能只做一件事看似很简单但特别容易违反。我在早期写过一个大而全的“内容创作 skill”涵盖选题、写稿、排版、配图建议结果每次调用都变慢输出重点也不突出。后来狠下心把它拆成四个独立技能每个只负责一段准确度和速度都上来了。一个技能的最佳状态是“看到描述就知道它能干什么”。描述里一旦出现“同时”“以及”“还可以”这类词大概率就是职责过重。别不舍得拆技能之间可以组合调用这比一个万能技能可靠得多。6.2 先固定输出格式再写执行步骤我写技能时习惯把结尾的输出样例先写出来再去补前面的执行步骤。这和正常写作习惯是反的但对 Agent 特别有效。当模型知道最终要交付什么样的东西它每一步的执行都会朝向那个结构聚合而不是自由发挥。比如写分镜技能我先定义好“序号、景别、画面描述、台词、时长”这个表格再告诉模型“请按每 30 字一个镜头的方式拆分文案”。有了明确终点输出质量会立刻提升。这个思路同样适用于 code review 技能先规定输出必须包含“问题等级、影响范围、修改建议”三个区块再让 Agent 去扫描代码。6.3 做测试时别只测“正常路径”我在给技能设计完流程后会特意拿几个“边界输入”来测试。比如分镜技能我会给它一段没有明显情绪起伏的产品说明书看它能不能找出高潮点比如代码审查技能我会给它一段没有注释但逻辑清晰的代码看它会不会硬编出问题。边界输入能帮你发现技能的盲区也能提醒你把规则写得更完整。另外我会坚持把测试样例和输出结果记录在技能仓库的 README 里。下次改了一个描述直接跑一遍样例就能知道有没有把原有行为弄坏。这相当于给技能本身做“回归测试”长期下来能省不少力气。最后分享一个个人体会不要一上来就囤几十个技能包。我刚开始玩的时候看到 GitHub 上好的仓库就拉下来放进技能目录结果真正频繁用到的只有三四个其余的全躺在那里增加干扰。更合理的做法是把最近一个月最常让 Agent 做的十件事列出来优先为其中重复次数最多的两三个场景配置技能用熟了再慢慢扩展。技能的质量永远比数量重要一个好的技能带来的效率提升远胜过二十个用不上的技能占的那点存在感。如果你也想体验一把“打开新世界”的感觉先别急着四处搜刮挑一个小任务自己写一个技能跑通那种掌控感比任何现成包都来得更踏实。