最近大半年我一直泡在 Claude Code、Codex、OpenCode 这类 AI 编程工具里前端项目、测试用例、文档生成、设计稿还原都在往 Agent 工作流上迁。一开始我有个非常直接的困惑同一个模型、同一个工具为什么有些人跑出来的效果像带了三五年经验的帮手我跑出来的效果更像一个“什么都懂一点但做什么都毛手毛脚”的实习生后来对比了几套配置和用法发现差距基本不在模型本身而在“skills”上。这里说的 skills不是 LeetCode 那种算法刷题技能也不是 PPT 模板里那种“职场软技能”而是这两年 Agent 生态里特别火的一个概念给 AI 编程助手预置的一套结构化的操作手册、脚本资源和执行流程。GitHub 上 baoyu/skills、mattpocock 的 skills 合集都是这类东西吴恩达还专门出过 Agent Skills 的教程 PDF。我照着这些公开资源把 skills 用起来之后最直观的感受是输出稳定性上了一个台阶模型很少再“自由发挥”了。这篇文章我打算把我从理解、上手到二次开发 skills 的完整过程写下来包括技能目录怎么搭、SKILL.md 怎么写才容易命中、怎么在 skill 里调用 MCP 工具以及我实际踩过的几个坑。内容适合三类人看一是刚接触 Agent 编程、还不知道 skills 是什么的开发者二是已经用上 Claude Code 或 Codex但总觉得输出不稳定的用户三是想在团队里推广 AI 工作流、想把经验沉淀成可复用资产的工程负责人。1. Skills 到底解决了什么问题先从一个最常见的场景说起。假设你让 AI“帮我做一个前端页面的设计稿还原”没有 skills 的时候模型大概率是凭自己的理解写一套 HTML/CSS布局差不多、样式差点意思、交互细节靠猜。但你如果给 Agent 配一个“设计稿还原”的 skill里面写清楚先读取图片元数据、判断设计稿尺寸、识别颜色体系和字体、按栅格系统生成页面骨架、再用 Tailwind 或 CSS Modules 落地整套流程下来输出的还原度会稳定很多。这件事的本质是模型本身没有“做事的顺序”。它有海量的知识但在一个具体任务里它不知道你希望它先做什么、后做什么、用什么标准自检。Skills 就是把这些“过程性知识”固化下来让 Agent 在合适的时候自动加载并执行。1.1 Skills 不是插件也不是 MCP 工具我见过很多人把 skills 和 MCP 工具混为一谈包括我自己一开始也晕。简单区分一下MCPModel Context Protocol解决的是“Agent 能调用什么外部能力”比如读写文件、操作浏览器、查询数据库、调用 GitHub API。Skills 解决的是“Agent 拿到一个任务后该按什么流程执行”它包括判断、步骤、模板、脚本和自检标准。打个比方MCP 是给了厨师一套高端厨具skills 是给了厨师一本标准化菜谱。没有菜谱厨师照样能做菜但口味全看当天状态有了菜谱出品就稳定了而且新来的厨师也能上手。所以你在 GitHub 上看到的 baoyu/skills 仓库里面绝大多数并不是封装好的 API 工具而是一个个带说明文档的“操作流程包”。每个 skill 都有一份核心说明文件外加若干脚本和参考资料Agent 读到这份说明后就知道在什么场景下该调用这个技能、按什么步骤执行。1.2 Skills 火起来的三个推动力Skills 从概念到变成生态背后有三个很实际的推动力。第一Agent 编程工具开始支持自定义技能目录。Claude Code 支持在.claude/skills下放自定义技能Codex 也支持自定义指令目录OpenCode 和 Cursor 这类工具也在快速跟进。这意味着技能文件不再只是给模型“讲故事”而是真正能被工具自动加载、在合适的任务中发挥作用。第二头部玩家的示范效应。baoyu/skills 这种仓库把大量经过验证的 skill 开源出来领域覆盖编程、写作、数据分析、文档生成、PPT 制作等你直接就能拿去用。吴恩达的教程又把 skills 的概念科普给了更广的人群。于是大家发现原来自己也能开发技能而不只是等官方更新。第三企业对“稳定流程”的渴望。团队里用 AI 写代码的时候最大的问题不是不懂而是不稳定。今天让 AI 写测试用例它给你一套风格明天换个人提问它又给你另一套风格。Skills 可以把团队认可的规范固化下来让 AI 输出风格统一、可审查。我自己的体会是Skills 是 Agent 工作流里“确定性”的重要来源。模型本身是概率性的但流程是确定的。把流程固化出来概率性带来的偏差就被约束住了。2. 拆解一个 Skill 的标准结构SKILL.md、scripts 与组织方式在动手写自己的 skill 之前最好先把别人写的成熟 skill 解剖一遍。我最开始参考的是 baoyu/skills 仓库里的一些典型技能也看过 mattpocock 那套偏 TypeScript 方向的技能。看得多了会发现它们虽然领域不同但底层结构高度相似。一个标准 skill 通常长这样skills/ └── test-case-generator/ ├── SKILL.md ├── scripts/ │ └── generate_test_cases.py ├── references/ │ └── test_case_template.md └── assets/ └── example_output.jsonSKILL.md技能的核心说明Agent 会优先读取这个文件来判断技能用途和步骤。scripts/可执行的脚本用来处理那些“模型临场手写容易出错”的操作。references/参考资料、模板、规范文档需要时再读取不占主上下文。assets/示例输出、静态资源、预期结果用来给模型做 few-shot 参考。2.1 SKILL.md 不是普通的 READMEfrontmatter 决定命中率SKILL.md 最大的特点是开头有一段 YAML 格式的 frontmatter这段信息是 Agent 判断“当前任务要不要加载这个技能”的依据。我见过最简单但有效的 SKILL.md 长这样--- name: test-case-generator description: 当需要为函数、模块或接口生成单元测试用例时使用支持基于输入输出示例自动推导边界条件。 --- # 测试用例生成技能 ## 适用场景 ... ## 执行步骤 1. 读取目标代码文件提取函数签名和核心逻辑 2. 识别输入参数的类型与边界条件 3. 生成正常路径、异常路径和边界值三类测试用例 4. 按模板输出测试用例附覆盖说明这段 frontmatter 里的description是整个技能的“门面”。它的写法直接决定了这个技能会不会在正确的时候被触发。我自己的经验是description 最好写成“当……时使用”的句式把触发场景尽可能明确。比如“当用户需要为函数或接口生成单元测试用例时”就比“测试用例工具”这种说法精确得多。因为 Agent 是根据语义匹配来判断是否加载某个技能的描述越精确误触发的概率越低。2.2 scripts 目录与其让模型临场写代码不如备好脚本SKILL.md 里写的是“怎么想”scripts 目录里放的是“怎么执行”。举个实际例子。前端做设计稿还原的时候经常需要从页面截图里提取主色、字体大小、间距。你可以让模型临场写一个 Python 脚本去解析图片但这非常不稳定——模型写的脚本可能需要两三次调试才能跑通而且每次输出的格式都不一样。更好的做法是在 skill 的 scripts 目录里放一个已经调好的图片解析脚本SKILL.md 里告诉模型“先运行这个脚本再基于脚本输出进行处理”。这里要注意脚本的通用性。脚本最好通过命令行参数接收输入输出标准 JSON 或文本不要写死文件路径不要依赖某个特定版本的第三方库。这样模型在不同项目里都能复用。我见过一些质量很高的 skill其 scripts 目录甚至自带一个小型的 README说明每个脚本的入参、出参和依赖。这样即便模型没有在 SKILL.md 的主流程里读到脚本细节也能在需要时快速理解。2.3 assets 和 references 不是摆设它们是 few-shot 的关键大模型在做一些格式敏感的任务时你给它一段示例比给它十条规则更管用。assets 目录就是放示例用的。比如你希望 skill 输出的测试用例是某种风格BDD 风格、表格风格、或严格带覆盖率的格式那就在 assets 里放一个“金牌示例”SKILL.md 中让模型先读这个示例再动手。References 目录则适合放那些“不一定每次都用但用到时必须准确”的内容比如团队编码规范、接口文档、数学建模的论文排版要求。我有段时间犯过把 references 内容全部写进 SKILL.md 的毛病结果主上下文被塞得满满当当模型反而忽略了真正的执行步骤。后来才意识到SKILL.md 里只写决策逻辑细节和模板全部放到 references让模型按需读取。这是 skill 设计里特别重要的一个原则。3. 从零开发一个自己的 Skills完整操作链路理解了结构之后下一步就是自己动手写一个 skill。我建议任何人都别一上来就挑战“全能助手型”技能——那既难写又难验证。更好的路径是找一个你日常工作里高频、重复、过程相对固定的任务把它固化成第一个 skill。以下是我自己开发一个“测试用例生成”技能的全过程你完全可以套到这个流程里换成你自己的场景。3.1 场景选择从“高频重复”开始我最早锁定的场景是“为 Python 函数生成 pytest 测试用例”。原因很简单我每周要写大量测试但很多测试的套路是完全一样的——正常输入、边界输入、异常输入。模型直接生成测试用例时经常漏边界条件我手动补又很烦。这个场景过程固定、结果可验证非常适合做成 skill。同样适合第一个 skill 的场景还有前端设计稿还原、数学建模数据的预处理、代码仓库结构和架构图生成、PPT 内容结构化整理。共同特点是你能说清楚“做这件事的标准步骤”是什么。3.2 落地一个可跑通的 Skill“测试用例生成”实战我创建了这样一个目录.skills/ └── pytest-case-generator/ ├── SKILL.md ├── scripts/ │ └── analyze_function.py └── assets/ └── example_cases.jsonSKILL.md 的核心内容我写成了这样--- name: pytest-case-generator description: 当需要对 Python 函数或类方法生成 pytest 测试用例时使用特别适合纯函数、工具类和 API 服务函数支持边界值和异常路径分析。 --- # Pytest 测试用例生成技能 ## 执行流程 1. 读取目标代码文件定位需要测试的函数或方法。 2. 运行 scripts/analyze_function.py传入目标文件路径和函数名获得函数签名、参数默认值、返回值类型和依赖信息。 3. 基于分析结果生成三类测试用例 - 正常路径覆盖典型输入与预期输出。 - 边界值包括空值、最大/最小长度、特殊字符、None、超长字符串等。 - 异常路径断言抛出的异常类型与异常信息。 4. 输出为 pytest 风格测试文件每个测试函数使用清晰命名并附带简要注释说明测试意图。 ## 输出规范 - 文件名test_模块名.py - 使用 fixture 隔离依赖不访问网络和真实数据库 - 测试数据内联不依赖外部文件analyze_function.py 这个脚本的作用是静态分析目标函数的参数和逻辑路径原理就是借助 Python 的ast模块解析源码提取函数定义、默认参数、return 语句、异常抛出点和调用依赖。AI 模型虽然能读代码但在“提取函数结构和分支路径”这件事上脚本比它更精确、更省 token。这就是为什么我会把这一步从“让模型思考”转变为“让脚本执行”。3.3 验证与迭代让模型自己诊断自己的输出写完 skill 之后我做的第一件事不是在真实项目上用而是先用一个我完全熟悉、手写测试也很容易的函数去验证def divide(a, b): if b 0: raise ValueError(除数不能为零) return a / b然后我在 Claude Code 里提问“为 divide 函数生成 pytest 测试用例”观察它是否自动加载了 pytest-case-generator 这个 skill以及输出是否覆盖了正常、边界b0、异常路径。如果没触发我就回去调整 frontmatter 里的 description如果触发了但输出格式不对我就去看是不是 SKILL.md 里的“输出规范”写得不具体。这里我有一个小技巧让模型自己评价自己的输出。生成测试用例后我会追问“这个测试套件有没有漏掉边界条件覆盖率大概多少”它往往能指出自己刚才没考虑到的情况。然后我把这些新的要求补进 SKILL.md这就完成了一次技能迭代。开发 skills 本身就是一个“迭代调参”的过程。别指望一次写完美先跑通再收紧比什么都强。4. Skills 与 MCP 工具的协作方式你大概已经注意到了skills 和 MCP 是两套不同的东西但它们在实际工作流中经常需要配合。很多人在社区里问“skills 如何调用 MCP 工具”我一开始也卡在这后来才想明白skills 不直接“调用” MCP而是通过 Agent 的上下文和工具注册机制让二者在一个工作流里协同工作。4.1 MCP 和 Skills 的分工用一个场景说明举一个我实际跑过的场景给现有前端项目生成页面截图的可访问性分析报告。这个任务如果只靠 MCP我需要一次次手动调浏览器工具、截图工具、DOM 解析工具然后再让模型分析整个过程很散。如果只靠 skillskill 里能写清楚分析维度但它自己没有“打开浏览器截图”的能力。正确的解法是把 MCP 工具作为执行能力把 skill 作为流程编排。我在 skill 的 SKILL.md 里写明步骤——“使用浏览器工具打开页面使用截图工具捕获关键视图使用 DOM 解析工具提取按钮和图片元素的属性然后基于这些数据生成可访问性报告”。真正执行时Agent 会按 skill 的描述去调用已注册的 MCP 工具。它们的区别与配合我用一个表总结一下维度MCP 工具Skills回答的问题Agent 能做什么Agent 应该怎么做例子读文件、操作浏览器、调 API测试用例生成流程、设计稿还原流程失败时的表现工具报错调用失败流程混乱输出不符合规范组合关系提供原子能力编排这些原子能力4.2 Skill 里引用 MCP 工具的具体写法在 SKILL.md 中“调用” MCP 工具不需要写代码只需要把工具的用途和期望用法写清楚。比如## 依赖工具 - 使用浏览器工具mcp-server-playwright打开目标页面并截图。 - 使用 DOM 解析工具提取关键元素属性。 - 使用文件工具将最终报告写入 ./reports/ 目录。Agent 在执行时会自动把浏览器工具与已注册的 MCP 工具能力做匹配。前提是这些 MCP 工具已经在 Claude Code、Codex 或 OpenCode 里注册好。以 Claude Code 为例你可以用 CLI 参数指定 MCP 配置claude --mcp-config {browser: {command: npx, args: [mcp-server-playwright]}}有的工具也支持在项目根目录放.mcp.json{ mcpServers: { browser: { command: npx, args: [mcp-server-playwright] } } }配置完成之后你的 skill 里只需要声明“我依赖什么能力”而不需要关心 MCP 的具体连接细节。这也是我推荐的协作方式MCP 负责接通能力skills 负责把能力组织成流程。4.3 两个常见误区第一个误区是把 skills 当 MCP 用。有人在 skill 里写“调用 my_custom_api 获取数据”但实际上这个 API 根本没有通过 MCP 或任何方式暴露给 Agent模型只能自己编一个实现结果自然不对。正确的做法是凡是需要真实外部能力的先通过 MCP 注册再在 skill 里引用。第二个误区是觉得有了 MCP 就不需要 skills。MCP 工具是一堆零散的原子能力没有流程编排时Agent 可能会用错顺序、漏掉步骤。我实测中发现同样是调用浏览器工具有 skill 引导和无 skill 引导分析报告的完整度差很多。所以两者不是替代关系而是互补关系。5. 我在实测中踩过的坑和排查思路写了大概十几个 skill、跑了不下百次之后我积累了一些比较有共性的“翻车”经验。这些问题不亲自用一遍很难发现我把排查思路写出来希望你能少走点弯路。5.1 坑一description 写得像论文摘要Agent 根本不知道什么时候用这是我犯得最多的错误。最开始我给一个设计稿还原技能写的 description 是description: 提供全面的前端设计稿还原能力包括图片理解、布局还原、样式提取、响应式适配等技术方案。听起来没什么问题但实测下来Agent 经常在“帮我把这个页面背景色改成和设计稿一致”这种小任务上把整套设计稿还原的 skill 加载进去白白拉高 token 消耗。而在真正需要完整还原一组设计稿时它又可能不去加载这个 skill。后来我把 description 改成了更“触发式”的写法description: 当用户提供网页设计稿图片PNG/JPG/Figma 导图并要求生成对应前端页面代码时使用包括尺寸、颜色、字体、间距、布局的完整还原。这一改触发准确率明显提升。关键点在于description 要写清“输入长什么样”“用户要什么”比写清“你能做什么”更管用。Agent 是通过当前任务与 description 的语义匹配来决定是否加载的所以你描述的应该是任务的“样子”而不是技能的“能力”。排查的时候我会先打开工具的运行日志看每次提问时到底加载了哪些 skill。如果该加载的没加载就去改 description如果每次啥任务都加载同一个 skill说明 description 范围太宽需要收紧关键词。5.2 坑二SKILL.md 写成“大而全手册”上下文反而被拖垮第二个坑是我这种“资料收集癖”容易踩的。我写数学建模相关的 skill 时把各种获奖论文的结构、数据预处理方法、画图配色建议、论文排版规范全写进了 SKILL.md。结果就是每次触发这个 skill光读取 SKILL.md 就要消耗大量上下文留给真正生成内容的空间就不多了。正确的做法我刚才也提过SKILL.md 里只放决策逻辑和核心步骤把细节内容放 references。比如“画图配色建议”这种内容可以整理成一份references/chart_style_guide.md然后在 SKILL.md 里写“绘图前先阅读 references/chart_style_guide.md”。这样既保证了模型在需要时有据可查又不会让主上下文被塞满。动手组织 skill 文件时我把“SKILL.md 控制在 80 行以内”作为经验法则。超过这个长度我就要考虑是不是有什么内容该移到 references 里。5.3 坑三脚本“能跑”但“带不走”还有一次我写了一个依赖系统全局 Python 环境的脚本在自己的机器上怎么跑怎么对但换了一台机器或者换了个项目目录脚本就报依赖缺失。原因是脚本里 import 了一个我没写进 requirements 的第三方库然后路径还写成了绝对路径。这个问题在别的开发者复现你的 skill 时特别致命。我现在的做法是脚本一律使用相对路径入口统一在脚本内判断当前工作目录脚本头部写清需要的 Python 版本和第三方依赖最好附带一个requirements.txt或让 SKILL.md 里写“运行前执行 pip install -r requirements.txt”能只用标准库解决的就不用第三方库如果必须用第三方库就把安装步骤写进 SKILL.md 的“前置条件”中。我后来做数据分析类技能时所有依赖都固定版本并在脚本里加了“检查依赖缺失时提示具体安装命令”的逻辑这样模型执行脚本出错时也能根据提示快速自愈。5.4 坑四多个 skill 职责重叠Agent 选择困难技能一旦多起来就会出现另一种问题几个 skill 的 description 都覆盖同一个场景Agent 不知道该加载哪个或者干脆随机加载一个。比如我同时写过“代码提交信息生成”和“代码评审建议生成”两者的 description 都提到了“分析代码变更”结果就是提交信息时偶尔把评审技能也加载进来。解决方法是职责单一化一个 skill 只做一件事并且 description 之间做差异化。后来我把提交信息生成技能的描述聚焦在“基于 git diff 生成 Conventional Commits 格式的 commit message”把评审技能的描述聚焦在“审查代码变更中的性能、安全性、可维护性风险”。两者触发场景就有了明确边界。我还用了一个笨办法把常用技能做成一张表格放在项目的AGENTS.md或全局配置里让 Agent 在遇到任务时“先看这个技能地图再决定加载哪个”。这比只依赖语义匹配稳定不少。下表把这几个坑汇总一下坑典型现象排查思路description 写得空泛该触发时没触发不该触发时乱触发改成“当……、且用户要……时使用”句式SKILL.md 太长上下文被占满输出质量下降正文精简细节移入 references脚本依赖不稳定换环境报错、乱跑固定版本、相对路径、写清前置依赖多技能职责重叠Agent 加载混乱职责单一化description 差异化配置技能地图6. 把 Skills 做成团队资产而不是私人玩具当你把单个 skill 打磨到稳定之后自然会想把它分享给团队或者基于团队规范去定制一套。这一步的坑比个人用的时候更多但也更有价值。我自己现在正在团队里推这套做法有几个体会比较深。6.1 团队 Skills 库的规划目录、命名与入口团队级 skills 库建议单独建一个仓库不用绑死在具体业务项目里。这样技能和项目解耦新人入职拉一次就可以在多个项目里复用。目录结构可以按“领域”而不是按“工具”来划分skills/ ├── frontend/ │ ├── design-to-code/ │ ├── component-review/ │ └── a11y-check/ ├── data/ │ ├──>