最近在捣鼓 AI Agent 的同学估计都被 Skills 这个词刷屏了。从 Claude 的 Agent Skills 到 Codex 的 Skills 市场再到 GitHub 上各种 superpower 技能集合几乎一夜之间大家发现光是会写提示词已经不够了真正让 Agent 变强的是给它装上一套结构化的技能包。我自己在前端开发和自动化脚本这两个方向试了不少 Skills也自己写过几个从最开始以为它就是多写几段提示词到后来慢慢摸清它的目录规范、指令设计、脚本封装整个过程踩的坑不算少。这篇就围绕 Skills 本身聊聊它到底是什么、能解决什么问题、怎么开发一个能用的 Skill以及我在实操中总结的那些常规文档里不会写的东西。不管你是刚开始接触想装几个现成的还是已经准备自己动手写这篇都能给你一个比较完整的参考。1. 先把 Skills 拆开看它是 Agent 的岗位说明书1.1 从提示词到技能包到底进化了什么传统上我们让 AI 干活靠的是提示词。你把需求写清楚把约束列出来把示例给上模型就照着生成。问题是一旦任务复杂一点比如帮我做一个符合企业规范的前端页面帮我按某本论文格式写初稿提示词就会膨胀到几千字而且每次对话都要重复这些约束又占上下文又容易不一致。Skills 解决的就是这个问题。它不是一段提示词而是一整套打包好的能力单元里面有一个说明文件告诉模型这个技能什么时候用、怎么用、步骤是什么还可以附带脚本、模板、参考数据。模型在对话过程中如果判断当前任务能匹配某个 Skill就会自动加载它然后照着里面的流程和规范去执行。用个生活化的比喻提示词像你临时交代一个实习生你今天帮我把会议室订了要注意投影、人数、茶点……而 Skill 像你直接给他一本《会议筹备手册》里面写清了所有步骤、标准、花名册和常用供应商。你只需要说安排下周的项目启动会剩下的事手册来处理。1.2 Skills 的核心结构SKILL.md 与辅助文件目前主流的 Agent Skills 方案比如 Claude Agent Skills核心是一个目录目录里至少有一个SKILL.md文件。这个文件采用的是 Markdown 格式但它的作用不是给人看而是给模型看的操作手册。SKILL.md 里通常包含这几块内容YAML frontmatter定义 Skill 的名称、描述模型就是靠这个描述来决定什么时候调用它的。写得好不好直接决定模型会不会找对工具。指令主体用清晰的步骤告诉模型该怎么执行要求什么输入、什么输出遇到边界情况怎么处理。示例给一两个完整的输入/输出示例模型可以照着模仿。除了 SKILL.md还可以在同一目录下放scripts/Python、Shell、Node 脚本、assets/模板、图片、PDF、references/参考文档等。模型在执行 Skill 时可以读取这些文件调用脚本甚至把脚本的运行结果当作下一步操作的依据。1.3 一个典型的 Skill 长什么样我自己写过一个用于前端页面生成的 Skill目录结构大致是frontend-builder/ ├── SKILL.md ├── scripts/ │ └── scaffold.py └── templates/ ├── page_template.html └── component_template.jsxSKILL.md开头长这样--- name: frontend_builder description: 根据需求生成符合规范的前端页面。当你需要创建新的页面、组件或修改现有前端结构时使用。 --- # 前端页面生成技能 输入用户对页面的描述包括布局、功能、风格。 步骤 1. 分析需求提取页面区块和组件。 2. 使用 templates 中的基础模板。 3. 调用 scripts/scaffold.py 生成代码骨架。 4. 按规范补全样式与交互逻辑。 5. 输出完整的文件结构和代码。说实话很多教程讲到这就让你去装几十个 Skills但其实真正决定一个 Skill 好不好用的是后面那些细节。接下来我重点展开讲几个核心问题为什么需要它、怎么写才不容易翻车、以及实际开发中哪些地方最容易踩雷。2. 为什么需要 Skills它解决的四个实际问题2.1 从自由发挥变成按规范交付没用 Skills 之前我让 Claude 写一个 React 页面它每次给出的代码风格都不太一样。有时用 class 组件有时用函数组件有时带上 TypeScript有时又变成了纯 JavaScript。不是模型不行而是没有统一规范和流程时它只能靠训练数据里的平均印象来生成。把规范写进 Skill 之后模型每次都会按固定的组件结构、样式方案和目录约定来输出。等于把团队代码审查里那套隐性规则变成了显性指令。我实测过同一个需求用 Skill 生成的代码和直接对话生成的代码在一致性上的差距非常明显至少能少改一半的格式问题。2.2 节省上下文窗口让 Agent 更专注现在大模型的上下文虽然越来越大但也不是无限的。你每次对话都塞 2000 字的前端规范再加上需求描述、历史记录很快就会把窗口占满。而且窗口越长模型在关键地方的注意力就越容易被稀释。Skill 是按需加载的。平时它不占上下文模型看到相关需求时才会去读取SKILL.md和必要的脚本。我自己在项目里试过把规范从对话里挪到 Skill 里之后同样的任务Token 消耗明显下降而且模型输出质量反而更稳定了因为它看到的是精简后的上下文。2.3 让复杂操作可以复用和沉淀有一些流程是需要多步操作的比如检测 APK 文件的基本信息并提取可读内容或者按论文模板的格式要求把目录、引文、参考文献整理规范。这种流程如果每次靠对话重新编排效率太低而且你无法保证每次模型都会按同一套逻辑走。写成 Skills 之后整个流程就固化了团队里的人都能复用。这个思路和传统软件开发里的封装是一样的把频繁使用的复杂逻辑抽成函数一次编写处处调用。2.4 快速对比Claude Skills、Codex Skills 和 GitHub Skills我接触得比较多的是这三类 Skills放在一起对比可能更直观平台格式优势场景注意点Claude Agent Skills目录 SKILL.md 辅助文件通用任务、自动化流程、复杂工具链需要自行组织目录市场里的质量参差Codex Skills类似格式偏开发场景代码生成、仓库级改动、写论文/报告与编辑器/CLI 的集成深度影响体验GitHub Skills官方交互式课程学习 Git 和开源协作流程主要是学习导航不适合当成随取随用的能力库我个人的使用感受是Claude 的 Skills 生态更偏向让 Agent 成为一个懂行的人Codex 的 Skills 则更偏向让 Agent 成为一个熟练的程序员。两者并不冲突完全可以按场景混用。3. 手把手开发一个自己的 Skill从零到可用的完整过程3.1 先定功能边界别让 Skill 太贪心我见过很多新手一上来就想写一个全能 Skill既想让它能写前端又想让它能分析数据还想让它能处理文档。结果反而模型不知道该什么时候调用或者调了之后执行路径混乱。正确做法是像写函数一样保持单一职责。一个 Skill 只做一件事把那件事做到极致。我做前端生成 Skill 的时候最初版本只负责根据需求生成页面结构连样式都没包含。确定这个边界之后写作 SKILL.md 的难度会小很多测试也简单很多。等基础版跑通了我再扩展出前端样式优化组件单元测试生成这样的独立 Skills。3.2 编写 SKILL.md把怎么做写清楚这是一个实际例子。我需要让模型能生成一个完整的移动端 H5 页面包含响应式布局和基础交互。我一开始写的描述太笼统模型经常误判。后来改成这样--- name: mobile_h5_builder description: 在需要生成移动端 H5 页面时使用支持响应式布局、触摸交互和基础表单。适用于用户要求创建一个新的移动端网页页面而非桌面端页面。 --- # Mobile H5 页面生成器 ## 输入 - 页面用途 - 核心功能模块 - 期望的风格/配色可选 ## 步骤 1. 先创建 HTML 文件引入 viewport 设置。 2. 将页面拆分为 header、main、footer 三个区块。 3. main 中按功能模块继续拆分每个模块使用 BEM 类名。 4. 使用 flex 或 grid 进行布局禁止使用 table 布局。 5. 为所有可点击元素添加 touch-action: manipulation。 6. 输出完整源码并附上文件目录说明。 ## 示例 用户帮我生成一个活动报名页 输出见 templates/event_signup.html写到这里我停下来反思了一下其实还有一个关键点让模型明确知道什么情况下不要用。比如这个 Skill 只针对移动端 H5如果用户要的是桌面端 landing page就应该让模型拒绝调用或者切换到其他 Skill。我在description里特意加了而非桌面端页面这半句实测下来误调用的概率低了很多。3.3 引入脚本把重复性的体力活交给代码有些动作让模型直接生成代码很容易出错比如生成一个统一风格的 SVG 图标或者把目录下的图片统一裁剪成 3:2 的比例。这种时候不如在 Skill 里塞一个脚本让模型调用脚本完成操作。以我的frontend-builder为例scripts/scaffold.py脚本负责生成项目骨架的结构和基础文件。它接收参数--name和--type在临时目录里创建好文件之后模型再把具体代码填充进去。这样做的好处是文件结构的规范性由代码保证代码生成的质量由模型保证两者各司其职。脚本不一定要很复杂。哪怕只是整理数据、格式化字符串、批量重命名这类小工具也能帮模型省下很大的功夫。你需要做的是在 SKILL.md 的步骤里写清楚该调用哪个脚本、命令是什么、期望输出是什么。3.4 测试 Skill不能只看一次效果这一步是我最想强调的。很多人在本地把 SKILL.md 写好了跑一次觉得还行就以为完事了。实际上一个 Skill 的可用性需要多轮验证。我的测试方法是准备一组基准测试用例覆盖三种情况标准场景完全符合 Skill 典型使用条件的需求看它能否正确调用并顺利执行。模糊场景需求描述得很模糊比如帮我做个页面没说移动端还是桌面端看模型能不能自己补充合理的假设。反向场景需求明显不该用这个 Skill比如帮我写个 Python 爬虫看模型是否会错误调用前端 Skill。每次测试完我会记录模型做了什么再回头改 SKILL.md。比如我发现当我没写清输出格式时模型有时会只给你一段代码而非完整文件。于是我就在步骤里加了输出完整源码并附上文件目录说明这句话问题就解决了。3.5 一个可以抄作业的完整示例这里给一个最小可用的 Skill 示例方便你快速上手。功能很简单把用户输入的一段中文文本转换为结构化的 Markdown 笔记。目录note-formatter/ ├── SKILL.md └── references/ └── style_guide.mdSKILL.md--- name: note_formatter description: 将自由形式的中文输入整理为结构化的 Markdown 笔记。适合学习笔记、会议记录、灵感速记等场景。当用户提供了零散的文字并要求整理时使用。 --- # 笔记整理器 ## 输入 - 一段或多段非结构化的文本 ## 步骤 1. 阅读全部输入识别核心主题。 2. 使用 references/style_guide.md 中的格式规范。 3. 将内容拆分到 ## 和 ### 标题下。 4. 重要结论用 **加粗** 表示关键数据用表格呈现。 5. 生成的笔记必须包含一个待办事项区块其中列出文本中隐含的行动项。这个 Skill 虽然简单但它包含了 Skill 的关键要素入口条件、执行步骤、参考文件、输出约束。你可以复制这个结构替换成自己需要的内容。4. 实战中的常见坑与排查技巧4.1 命名和描述写得不好模型根本不调用这是我踩过最大的坑。我第一次写了一个 Skill 叫code-reviewer.md描述写的是代码审查技能。结果在对话里无论我怎么说帮我看看这段代码有没有问题模型都不调用它。后来我分析原因模型是根据description里的语义与当前用户意图做匹配的代码审查技能太泛了模型可能觉得直接回答也能搞定没必要动用一个 Skill。正确的描述应该包含触发条件 典型场景 不适用场景。比如改成description: 当用户要求审查代码质量、检查潜在 bug、评估代码规范或者想要在提交前检查代码时使用。适用于 Python、JavaScript、TypeScript 等常见语言。当用户只是询问代码功能或解释某段代码时不要使用。改完之后调用率立刻提升了。你完全可以把这个思路套用到任何 Skill 的description里。4.2 指令不确定时模型会自由发挥如果你的步骤里写着处理数据这种模糊指令模型就会按自己对处理的理解来操作结果经常不达预期。我见过有人写 Skill分析用户给的 CSV 文件提取有用的信息。然后模型就真的只是看了看数据用语言描述了一下并没有输出统计结果。要避免这个问题步骤里的每个动词都应该尽量可验证。不要写分析数据而是写计算每列的平均值、最大值和最小值并生成一个汇总表不要写检查图片而是写确认图片尺寸是否大于 800x600不满足则输出错误提示。模型执行的时候每走一步都知道自己做得对不对最终结果自然更可控。4.3 依赖脚本和外部工具时别忘记异常处理如果你的 Skill 里要调用 Python 脚本或者 Shell 命令一定要考虑脚本可能失败的场景。比如脚本依赖某个 Python 包但当前环境没装模型会报错然后停下来。比较好的做法是在 SKILL.md 里写清楚需要哪些依赖以及安装命令是什么。脚本的退出码含义0 表示成功非 0 表示失败。脚本失败之后应该怎么办是重试、降级还是输出特定提示让用户处理。我通常还会在脚本里加一些--help参数说明这样模型在不确定的时候还能先看看帮助信息再执行相当于潜在的自愈能力。4.4 常见问题速查表现象可能原因排查与修复模型死活不调用 Skilldescription太泛缺乏触发条件名称与语义不匹配用当用户...时使用当...时不要使用句式重写描述调用了 Skill 但执行步骤乱SKILL.md 步骤太抽象没有明确输出格式给每步补充可验证结果结合示例说明脚本报错后卡住未在 SKILL.md 中说明依赖与失败处理补充依赖安装命令、退出码说明、失败后的替代方案同一个 Skill 在不同对话里表现不一致指令中有歧义缺少边界条件增加边界描述加入反例和特例说明Skill 里的文件读不到路径写错或模型没有权限读取辅助文件使用相对路径描述确保目录结构按约定放置我还想额外提一个技巧给 Skill 加自检清单。在 SKILL.md 的最后列一个清单让模型在执行完所有步骤后逐项检查输出。比如是否包含标题是否包含待办事项是否有超链接这招对提升输出稳定性特别有效本质上就是把人工 Review 的节奏前置到了生成阶段。5. 值得关注的 Skills 生态与进阶思路5.1 从哪里找到好的 Skills现在 Skills 的集市还没有一个统一入口但主要来源已经很清晰了GitHub 上的 Skills 仓库搜索agent skills、claude skills、codex skills就能找到大量集合很多是开发者的个人项目质量和风格差异比较大。我建议先看 star 数和更新时间太老的基本不用考虑。官方市场或平台集成Claude 和 Codex 都在逐步完善 Skills 的发现与安装机制。直接在客户端里浏览官方推荐的列表靠谱率最高。社区热词里的 superpower skills这是一套以给模型增强特定领域能力为目的的 Skills 合集覆盖写作、编程、研究等方向它的特点是比较结构化适合拿来当学习范本。我自己下载这些 Skills 之后第一件事不是直接装完用而是解压到本地把SKILL.md全部读一遍。读 10 个别人的设计胜过自己埋头写 3 个。你会发现很多常见的模式描述怎么写、步骤怎么分、哪些内容要放进 references、哪些情况用脚本。5.2 从单技能到技能编排当你手上有十几个 Skills 之后新的问题来了一个复杂任务可能需要多个 Skills 配合完成。比如根据一组数据生成可视化报告可能涉及数据清洗 Skill、图表生成 Skill、文档排版 Skill。目前大部分 Agent 还不能自动完成这种复杂的技能编排但已经有方法可以化解你可以创建一个总控 Skill它的职责不是具体干活而是判断当前任务需要哪些子 Skills然后告诉模型按顺序加载并执行它们。这种总控 Skill的 SKILL.md 更像一个路由表--- name: report_factory description: 负责将数据转化为完整报告。当用户需要从原始数据得到一份包含图表的报告时使用。 --- # 报告工厂 1. 先调用 data_cleaner Skill 处理输入数据。 2. 再调用 chart_builder Skill 生成图表。 3. 最后调用 report_formatter Skill 将结果排版输出。说实话这个方法目前还不够成熟因为模型在跨 Skill 切换时偶尔会丢上下文但已经能在相当程度上提高效率。随着 Agent 框架的发展这种编排能力会越来越强你现在提前把单 Skill 的质量打磨好未来组合起来一定会更顺手。5.3 玩转 Skills 的三个阶段我把使用 Skills 的进阶路径总结成三个阶段方便你对照自己现在的位置阶段一消费。直接下载使用别人写好的 Skills感受它们对输出质量的影响。这时候不用管实现细节先积累体感。阶段二改造。把别人的 Skill 拿来改改成适合自己工作流程的样子。这是学习 Skill 设计最好的方式比从零开始写要容易得多。阶段三创建。把自己反复要做的任务固化成一个全新的 Skill配上脚本和参考文档形成个人能力库。我目前处在二和三之间大部分时间在改造现有 Skills偶尔为特定项目写一两个专用的。写了十几个之后最大的感受是Skills 真正的价值不是让模型会更多而是让模型的每一次输出都更稳定、更专业、更可预期。这种确定性才是大规模使用 Agent 的底气。最后分享一个我一直在用的习惯每次给模型配新的 Skill 之后我会用同一组测试需求跑三次然后记录输出之间的差异。如果三次结果差别太大说明 Skill 的指令还不够严格需要继续打磨。好的 Skill 应该像一台调校良好的机器同样的输入进去出来的结果应当高度一致。这个标准也是你判断一个 Skill 是否值得留下的最简单方法。