这两年只要你在用 AI 写代码大概都听过同一个词skills。尤其是 Claude Code、Codex、OpenCode 这类编码代理流行起来之后前端开发 skills、测试用例 skills、数学建模 skills 到处刷屏GitHub 上光是搜“awesome skills”就能翻好几页。我第一次真正被 skills 震撼到是拿到一份社区里分享的“图片还原设计稿”skills它能把一张截图直接变成一版接近还原的前端代码整个过程比我手动写 prompt 再反复纠偏快了不止一倍。但说实话一开始我是懵的。skills 到底是提示词、插件、脚本还是某种新的 Agent 框架为什么别人用的 skills 效果那么好我自己照着抄却经常“失灵”后来花了两三周把 Claude Code、Codex、OpenCode 几套流程都跑了一遍自己又造了几个内部常用的 skills才慢慢摸清这东西的门道。这篇文章就把我从“听概念”到“自己写”再到“批量落地”的完整经验拆开讲适合刚接触 skills 的开发同学也给那些已经用过但效果不稳的人一份避坑清单。1. 内容整体设计与思路拆解1.1 skills 到底是什么不是插件也不是普通提示词先说结论skills 是一套结构化的、可复用的、面向 Agent 的能力单元。它比一条 system prompt 更重比一个完整的独立应用更轻核心目标是把某个高频任务的处理流程固化下来让 AI 代理下次遇到同类任务时能按固定步骤执行而不是每次从零开始猜。我用一个生活化的类比来解释。你让一个实习生去整理会议纪要普通 prompt 相当于你口头说一句“把纪要整理好”实习生可能理解成用户要逐字稿、可能整理成待办、也可能写一封邮件结果全看运气。而 skills 相当于你给实习生一份标准作业指导书先读原文、按“结论—讨论—待办”三段拆分、输出 Markdown、同时生成一封摘要邮件。只要实习生肯照着做质量就差不了。放到编码代理里skills 的典型形态是一个文件夹里面包含SKILL.md作为主说明文件再加上脚本、模板、引用资料等附属资源。Agent 在执行任务时会先加载SKILL.md按里面描述的行为流程和调用规则工作。比如一个“代码审查 skills”它会约定先检查什么文件类型、按什么顺序看、重点看并发还是安全性、最终输出什么格式的报告。这个流程一旦被固化结果的可控性会大幅提升。注意很多网上的“skills 推荐”文章把 skills 和 MCP 服务器混为一谈。实际上两者不是一回事。skills 偏“做事的方法论和步骤”MCP 偏“接外部工具和数据源的能力”。它们可以搭配但功能层级不同。1.2 为什么 skills 是 Agent 时代的“超级能力”很多人会有个疑问我有 ChatGPT、有 Claude为什么还要专门搞一套 skills直接对话不就行了我刚开始也这么想直到我在一个真实项目里被逼疯了。那个项目要从一个老旧的 Vue 2 后台系统迁移到 Vue 3 TypeScript。我让 Claude 帮我分析代码现状它回答得很流畅但每次分析的方式都不一样有时候先统计文件数量有时候先看 package.json有时候直接给我一段改造路线图。对话一长它就把之前的分析框架忘光了同一个问题换个问法结果又不一样。后来我把“Vue 2 迁移分析”做成了一个 skills里面固定了分析步骤先扫描 package.json 确认依赖再统计options API/mixin/$emit的使用频率再识别路由和状态管理最后按优先级输出迁移清单。从那以后同类项目我只需要把路径丢给代理它就能按照统一标准输出我一个人维护多个迁移任务也不乱。这就是 skills 真正的价值——它把你的最佳实践、领域经验和执行标准沉淀下来让 AI 不是“聪明但随心所欲”而是“聪明并且稳定可预期”。在团队协作里尤其重要一个精心打磨的 skills 就是团队能力的拷贝新人用起来也能达到老手七成功力。1.3 适合谁用前端、测试、数据建模都受益理论上任何需要 AI 反复执行同一套流程的领域都适合引入 skills。我从实际试用中感受到收益最明显的三波人前端开发者把页面还原、组件生成、样式梳理、可访问性检查做成 skills日常工作压力会小很多。而且前端任务范式非常统一特别适合 skill 化。测试工程师把测试用例设计、边界值分析、自动化测试脚本生成做成 skills能显著提高用例覆盖的完整度减少漏测。数学建模 / 数据分析人员把数据探索、特征工程、模型对比、论文图表风格统一等工作固化能让分析过程可复现、结果更规范。这几类人群最大的共同点就是他们的工作里“流程”非常重而且流程可以抽象成明确的步骤。换句话说只要你能把一件任务说清楚步骤它就有成为 skills 的潜力。1.4 先认清边界skills 不是万能钥匙说了这么多好处我也得泼盆冷水。skills 不是银弹它解决的是“标准化流程的稳定性”问题解决不了“完全创新的探索”问题。如果你每天的任务都是全新且没有固定套路的比如研究某个从没见过的算法、写一篇需要强创意的文案那 skills 的帮助会非常有限。另外skills 需要维护。它和代码一样会过期、会失效。API 变了、框架版本升级了、你团队的规范调整了skills 里的旧指令就成了绊脚石。我看到不少人下载了社区 skills 之后不与自己的项目做任何适配跑了一次发现效果一般就断定“skills 是智商税”。实际上任何工具都需要配置期投入skills 也一样。2. 核心细节解析与实操要点2.1 标准目录结构与SKILL.md的撰写规范想动手写自己的第一个 skills首先得理解它的标准目录长什么样。拿目前社区里最常见的一套规范举例my-skill/ |-- SKILL.md # 主说明文件Agent 首先读取这个 |-- reference/ # 参考资料可选放领域相关的文档 |-- scripts/ # 可执行脚本可选例如格式化、抓取、计算 |-- templates/ # 输出模板可选让结果格式统一 -- assets/ # 其他静态资源可选比如样例图片SKILL.md是整个 skills 的大脑。它通常包含以下模块名称与适用场景说明这个 skill 解决什么问题什么时候值得加载。行为流程明确 Agent 要按照什么顺序做哪几步每步输入输出是什么。规则边界告诉 Agent 哪些不该做哪些问题要拒绝回答防止越界。输出格式规定最终交付物的结构比如用 Markdown 表格、JSON 还是特定目录结构。举个例子我在给团队内部做一个“前端页面设计稿还原”的 skills 时SKILL.md里开篇就写了当用户输入一张图片或一个设计稿链接时先判断图片类型和尺寸然后按从整体布局、配色、字体、间距、交互状态到响应式断点的顺序进行还原最后输出 Vue Tailwind 组件代码并附一个实现说明。这让代理从一开始就知道该往哪个方向努力。实操心得写 SKILL.md 时指令越具体越好。不要用“请仔细分析”这种废话要用“先列出接口返回的 JSON 字段标注每个字段的用途和类型再据此生成界面”这种可执行描述。Agent 对模糊指令的发挥空间比你想象的大得多限制越好结果越稳。2.2 顶层目录、命名与版本管理一个容易被忽略但实际操作中很要命的点是 skills 的目录和命名规范。不同工具对 skills 存放位置的要求不同但通用的习惯是放进个人配置目录下的skills文件夹中。以 Claude Code 为例通常会放在~/.claude/skills/下每个子文件夹就是一个 skillCodex 和 OpenCode 也有类似的约定只是路径不同。命名上我强烈建议用小写英文 短横线连接比如frontend-design-recovery、api-test-case-generator。不要用中文命名、不要带空格、不要起特别长且没有意义的名字。原因很简单skills 名字会被 Agent 用作加载触发的一部分越清晰的名字越容易被准确地唤醒。如果一个叫frontend-design-recovery的 skills 和一个叫frontend-recovery-toolkit的 skills 同时存在Agent 很可能会混淆它们的职能。版本管理同样重要。我是一个人 solo 开发但也会给每个 skills 目录加 Git 仓库打 tag。因为 skills 迭代速度快有时候只是加了一条新规则效果就完全不同。没有版本管理的话回滚会非常痛苦。2.3 触发机制怎么让 Agent 正确调用 skills真正上手之后你会发现写好 skills 只是第一步怎么让代理“想起来”用它才是关键。很多人的失败是把 skill 下载下来放在目录里然后发了一个很普通的请求Agent 根本没去加载这个 skill结果自然和平时没什么两样。要解决这个问题核心是让触发词和你的任务描述强关联。比如你写了一个“代码审查”的 skill那在 prompt 里最好明确带上“用 code review skill”或“按 review 规范检查”这样的短语。老手还会在 SKILL.md 的顶部写一段“触发条件描述”告诉 Agent 当用户请求中出现了哪些关键词时应当加载本 skill。例如当用户要求“还原这个设计稿”、“把这个图变成页面”、“根据截图写前端代码”时加载frontend-design-recoveryskill。这样一来就算用户没有直接点名 skillAgent 只要理解到这是设计稿还原任务就会主动加载。我在实际测试中加了这段说明之后命中率从不到一半提升到了九成以上。2.4 资源文件怎么准备参考知识库与模板很多网上的 skills 模板只提 SKILL.md 和 scripts但我实际用下来的经验是reference/和templates/这两个目录对结果稳定性的提升非常显著。reference/适合放领域文档的摘录、团队规范、项目风格指南。比如你做前端开发可以在 reference 里放一份团队的代码规范摘要让 Agent 在生成代码时自动对齐。我见过有人把整个项目的 README、接口文档、设计 token 都塞进去效果立竿见影——生成出来的代码风格和团队已有代码如出一辙。templates/适合放输出模板尤其在测试用例、需求文档、代码审查报告这类的场景下。只要规定了“输出必须包含背景、改动点、风险、测试建议”这四个模块生成结果就不会长成一篇散文。我建议 templates 里的模板要精简一页左右即可太长的模板反而会让 Agent 迷失重点。3. 实操过程与核心环节实现3.1 手写一个“测试用例生成” skills 的完整过程概念说太多了直接上实操。以一个很常见也很有价值的“测试用例生成” skills 为例我带大家从零写一遍顺便讲讲我在过程中踩过的坑。第一步新建目录结构mkdir -p ~/.claude/skills/test-case-gen/{scripts,templates,reference} touch ~/.claude/skills/test-case-gen/SKILL.md第二步写 SKILL.md 的核心内容。我一开始写得特别简单只有一段话“请生成测试用例”。结果生成的用例都是教科书级的“输入正确数据验证结果正确”这种废话。后来我改成下面这种结构化描述# 测试用例生成 Skill ## 适用场景 当用户提供接口定义、函数代码或需求描述要求生成测试用例时使用。 ## 执行流程 1. 解析输入明确被测对象的输入参数、输出、边界条件和外部依赖。 2. 按等价类划分法列出有效等价类和无效等价类。 3. 按边界值分析法列出上点、内点、离点。 4. 检查异常场景超时、依赖失败、空值、并发、权限不足。 5. 输出测试用例表格包含编号、场景、前置条件、输入、操作步骤、预期结果、优先级。 ## 规则 - 每个参数必须覆盖至少 3 个有效值3 个无效值。 - 涉及第三方服务的用例必须使用 Mock 描述。 - 不输出与测试无关的内容不输出代码实现建议。第三步写一个简单的脚本用来从接口定义里提取参数。这个脚本不强求但对于接口比较多的项目它能显著提升效率。我用的就是一个 Python 脚本解析 OpenAPI 文档输出参数清单然后 SKILL 里引用它# scripts/extract_params.py import json import sys def main(spec_path): with open(spec_path, r, encodingutf-8) as f: spec json.load(f) for path, methods in spec.get(paths, {}).items(): for method, detail in methods.items(): params detail.get(parameters, []) for p in params: print(f{method.upper()} {path} | {p.get(name)} | {p.get(in)} | {p.get(schema, {}).get(type)}) if __name__ __main__: main(sys.argv[1])第四步找一个真实接口跑一遍看输出是否达到预期。我拿一个登录接口做了测试它给了我非常细的用例表包括密码长度 6-20 位的边界值、连续输错五次的锁定场景、验证码过期场景等。这个粒度已经可以拿去直接和开发对齐测试范围了。注意这里有一个很重要的教训就是第一次跑的时候它把所有用例的优先级都标成了 P0。我就在 SKILL 的规则里补了一句“将不常见且低影响的异常场景标记为 P2”后面输出就合理多了。这种小修小补是 skills 迭代的常态。3.2 如何利用 skills 调用 MCP 工具关于 skills 和 MCP 的关系我前面提到过不是一回事但它们可以配合得很好。很多人搜索“skills如何调用MCP工具”其实就是想问怎样在固定流程里接入真实的数据源或外部操作能力。举一个场景我的“前端页面还原” skill 里需要在还原前拉取设计稿对应的接口真实数据否则还原出来的页面全是假数据。这时候我会在 SKILL.md 里声明在分析设计稿之前如果设计稿标注了接口地址使用 MCP 的 fetch 工具请求该接口获取真实返回 JSON再基于该 JSON 设计页面结构。然后再通过 MCP 服务器配置好 fetch 工具Agent 在执行 skill 的流程时一旦需要真实数据就会调用这个 MCP 工具去请求接口。这样 skills 负责“决定怎么做”MCP 负责“能把事做成”。再举个例子我做数学建模的时候经常要操作 Excel、CSV 数据集。我把“数据探索分析”做成一个 skill里面规定要先查看数据维度、缺失值、分布情况再决定要不要做特征工程而具体读写表格文件的操作就通过 MCP 的文件工具加上 Pandas 脚本来执行。两者一配合分析流程高度自动化。实操中有一点要留心MCP 工具调用是有副作用的比如写文件、发请求。所以在 SKILL.md 里一定要写明哪些阶段允许调用工具、哪些阶段禁止避免 Agent 在分析阶段就把文件改了。我最早没写这条它跑着跑着直接把源文件覆盖了还好有 Git 兜底。3.3 从 GitHub 下载并适配社区 skills 的正确姿势我知道大部分人不是想从零写而是想直接“skills 下载”现成的。社区里比较好的 skills 项目通常会自带 README 和使用示例但直接复制粘贴往往效果不佳。我总结了一套下载之后必须做的适配流程第一先看 SKILL.md 的依赖声明。很多高级 skills 会依赖特定脚本、Python 包甚至 MCP 服务器。如果它说需要pandas你就得确认环境里装了否则流程走到一半必然报错。第二把 skill 里的示例路径改成你自己的项目路径。这是最常见的坑。很多仓库作者写死了自己的路径比如/Users/xxx/project/src你下载下来不改成/data/my-project/srcAgent 一执行就是文件找不到。第三用自己的典型任务跑一遍记录偏差。我下载任何 skills 之后都会拿一个我已经知道正确答案的旧任务做回归测试。如果输出和我知道的正确答案偏差很大我就去读 SKILL.md 里哪条规则导致了偏差逐句修正。这个过程的收益远大于你花一天时间去找更多的 skills。我试过几个社区里较火的、含前端开发相关的 skills比如“图片还原设计稿”和“组件代码生成”坦白讲开箱即用的惊喜存在但大多数组件生成的视觉效果距离设计稿还有差距。真正把它调到可用的状态花了我大概一个下午。调完之后这个 skill 就成了我日常写页面最常用的搭档之一。4. 常见问题与排查技巧实录4.1 Skill 不被触发问题多半出在触发条件上现象我把 skill 放进了正确目录也发了请求但代理完全没有采用行为跟没装一样。排查思路先看 SKILL.md 的“适用场景/触发条件”里写没写清楚。如果没有写Agent 就不知道什么时候该用。如果写了但没触发就检查用户请求里是否存在足够明确的关键词。还有一个我经常踩的坑多个 skill 的适用场景描述重叠Agent 不知道该加载哪个最后干脆都不加载。遇到这种把每个 skill 的场景描述改成互斥的。还有一个容易被忽略的问题目录嵌套层级错误。比如 Claude Code 要求 skill 直接放在skills/xxx/SKILL.md如果你多套了一层变成了skills/xxx/more/SKILL.md有的版本能识别有的不能。我的建议是严格遵守工具文档的目录说明不要想当然。4.2 输出“模板感”太重或太泛规则写得不够紧现象技能确实被加载了流程也走了但输出的内容非常泛泛换个项目也能用等于没用的废话报告。这几乎是新手写 skills 最普遍的问题。根源在于 SKILL.md 里只有“要做什么”没有“不许做什么”也没有“具体到什么粒度”。比如你写“分析代码质量”Agent 可能输出“代码存在结构问题”这种废话。你要改成“列出所有超过 200 行的函数并标注各自负责的职责检查是否有重复超过 30 行的代码段落”。我后来养成了一个习惯每次看到输出里出现像是废话的句子就把它反推成规则写回去。比如看到“建议使用更安全的鉴权方式”这种废话就补一条规则“必须指出具体是哪一处接口缺少鉴权、属于何种类型、建议改成 JWT 还是 OAuth”输出质量立刻好得多。4.3 技能有过期风险依赖包和 API 版本现象skill 上个月还好好的这个月突然失灵或者输出结果明显过时。这里分两类。第一类是外部 API 变化比如它依赖的 MCP 工具地址变了、第三方服务接口升级了。第二类是知识过期比如 SKILL.md 里写的是某个框架的旧 API 用法而项目已经升级到新版本了。排查办法打开 skill 的脚本和 reference 文档看是否存在硬编码的版本号、URL、Schema。把这些经常变化的内容独立到配置文件中而不是写死在 SKILL.md 里。每次工具大版本升级时顺手跑一遍测试脚本比等到出错再排查高效得多。还有一个不起眼但实用的经验给每个 skill 在文档头部加一个“最后验证日期”字段。我和团队约定的规则是如果某个 skill 超过 30 天没验证过用之前先做一次冒烟测试。这个习惯帮我们避免了好几次生产事故级别的误操作。4.4 社区 skills 良莠不齐怎么快速判断是否值得下载现象GitHub 上 skills 项目又多又杂不知道哪个靠谱。我的筛选方法有这么几步首先看 SKILL.md 是否写得足够详细是否有明确的执行流程和规则边界如果一个 skill 只有三句话大概率价值有限。其次看是否带测试样例和示例输出这比 README 写一堆吹捧性描述有用得多。最后看更新时间和 issue 区如果作者已经半年没动静而 issue 里有人反馈新版本不兼容就要谨慎了。4.5 常见问题速查表症状可能原因排查动作skill 完全没有加载触发条件不明确 / 目录层级错误检查 SKILL.md 场景描述核对官方目录规范加载了但输出废话规则太泛缺少禁止项逐句把废话反推成具体规则中途报错找不到文件路径写死 / 相对路径错误统一改成基于项目根目录的相对路径调 MCP 工具时出错工具未配置好 / 权限不足单独测试 MCP 工具是否正常再让 skill 调用输出风格不对缺少模板或风格指南在 reference/ 里加入团队代码规范或模板执行时间过长分析范围过大限定只扫描指定目录不要全仓库扫描5. 从 skills 到 superpower skills进阶组合玩法5.1 把多个 skills 串成一条流水线单个 skill 解决单个任务但真实工作往往由多个任务组成。这时候就轮到“superpower skills”出场。所谓 superpower不是单个技能多复杂而是把多个 skills 排成一条流水线让代理按照顺序协同完成一个大目标。我举个我日常的例子。接到一个“新页面开发”任务时我实际上会依次用到三个 skills先用“设计稿分析” skill把图片里的布局、颜色、字体、交互拆解成结构化描述。再用“前端组件生成” skill根据结构描述生成 Vue/React 组件。最后用“代码审查” skill检查生成代码里有没有可访问性问题、性能隐患、命名不一致。如果这三个 skills 独立调用我得手动切换上下文效率提升有限。但把这套流程写成一个新的“super skill”在 SKILL.md 里依次调用子 skill代理就能一口气把整个任务跑完。我实际对比过同样的需求分步调用大概要 20 分钟的人工介入流水线化之后 5 分钟就能拿到完整交付物而且中间不需要我来做“翻译”。5.2 用变量和条件分支让 skill 适应更多场景简单的 skill 适合稳定场景复杂场景就得引入变量和条件分支。我常用的做法是在 SKILL.md 里用“如果……则……”的句式让代理根据输入的不同走不同流程。比如我的“接口文档生成” skill会判断输入的接口类型如果输入是 OpenAPI JSON走“解析 JSON提取每个接口的路径、方法、参数、响应”这条流程如果输入是代码里的函数定义走“静态解析函数签名推断入参类型与返回值”这条流程。条件分支让一个 skill 的覆盖面变宽同时不牺牲单一流程的清晰度。这里有个平衡问题分支太多会让 SKILL.md 变得臃肿代理反而容易迷失。我的建议是一个 skill 最多支持三到五条主分支。一旦超过这个量就拆成多个子 skill 再串成流水线。5.3 让 skill 变成团队经验库单个开发者的 skills 再强也不过是个人效率工具真正有规模效应的是把 skills 变成团队的经验库。我和小伙伴们在实践中有几个做法值得分享第一每个 skill 必须有一个“作者”字段和“设计背景”说明。这样后来人阅读时能理解当初为什么制定这条规则而不是机械执行。第二skill 必须是活文档每当有人在使用中发现更好的流程直接在 issue 里提改进而不是私下改自己的副本。第三团队仓库里放一套“黄金样例”也就是这个 skill 的最优输出结果新成员可以照着黄金样例来校验 AI 的输出质量。这种做法在团队协作里的价值远超单个 skill 本身。它本质上把每个成员踩过的坑、总结出的套路都固化成了资产新人不用踩一遍前辈踩过的坑就能直接站在不错的起点上。5.4 从效率到创造力skill 还有哪些想象空间很多人以为 skills 只能用来干那些“无聊的重复活”其实不是。我测试过把创意设计类的工作也 skill 化比如给一个“文案风格迁移” skill让它先拆解原作者的句式节奏、用词偏好、开头钩子结构再把这些特征应用到新的主题上。效果虽然不完美但能稳定地输出具有某种风格的初稿再经过人工微调效率确实翻倍。所以判断一个任务能不能 skill 化关键不是看它“重不重复”而是看你能不能把它拆成清晰且可指导的流程。哪怕是偏创作的任务只要你能总结出自己的方法论就可以用 skill 来放大它。6. 写在最后的实践体会我在实际使用中发现把 skills 用好最关键的品质不是技巧而是“持续迭代的耐心”。任何一个成熟的 skill都不是一次写成的而是通过一次次垃圾输出的打击、一句句规则的反推、一次次回归测试的打磨才慢慢变得好用起来的。现在我的工作流里凡是遇到过两次以上的任务我都会下意识地想一想这个能不能抽象成一个 skill如果能花半小时把流程固化下来下次再遇到我就不用再做重复劳动。这个习惯的改变比我会写多少种 prompt 模板都更有价值。最后再分享一个小技巧刚开始做 skills 时不要贪多先挑一个自己每天都会做的任务写到能用为止。一个真正好用的 skill胜过十个躺在目录里吃灰的半成品。等你跑通一次“设计—落地—迭代”的闭环后面再做新 skill 就是水到渠成的事了。