AI Agent Skills实战：从SKILL.md到Claude Code技能封装

这几天好几个技术群里都在讨论同一个东西Skills。前脚还在问“claude code skills 官方文档在哪”后脚就有人晒出自己写的“前端开发skills”让Agent自动干完半个页面的活。我盯着屏幕上那个自己动手改代码的终端第一反应是这东西跟之前的套路不一样。如果说过去一年我们都在教AI怎么“听懂人话”那Skills要解决的是AI怎么“记住手艺”。这篇文章不整虚的就把我这两个星期翻官方文档、写技能包、在不同Cli工具里反复折腾的经验全拆开讲。内容包括Skills到底是个什么结构、怎么写一个真正能用的前端Skills、怎么在Claude Code、Codex、OpenCode这些工具里把它跑起来、我踩过的那些“模型假装没看见”的坑以及最后一点圈内八卦。想靠AI工具提效的前端、测试、安全方向的朋友这篇值得收藏。1. 从“每次念叨”到“肌肉记忆”Skills补上的是Agent的长期记忆1.1 为什么最近Skills突然成了全网热词先说一个大背景。过去两年大家用AI写代码的方式基本是“对话流”打开Claude、DeepSeek、Kimi把需求打一段话发过去AI给你吐一段代码。这种模式有个致命问题——每次对话都像第一天上班的实习生什么都要从头教一遍。你上周刚告诉它“公司前端规范是CSS Modules不用Tailwind”这周新开一个对话它照样给你生成一坨Tailwind类名。Skills这个词被炒热本质上就是冲着这个痛点来的。它把“你希望Agent在特定场景下掌握的一套固定方法、流程、检查清单、脚本工具”打包成一个独立文件夹放在约定目录下。Agent读取项目上下文时如果发现自己正在处理的活跟某个Skills描述匹配就会主动把那一整套方法加载进来执行。打开热搜词排在前面的是“claude code skills 官方文档”“codex skills”“opencode skills”后面跟着“前端开发skills”“测试用例skills”。这说明什么说明这波热度根本不是某个自媒体炒出来的是真正写代码的人已经开始在工具链里找“技能复用”的方案了。1.2 新手最容易搞混的三件事Skills、MCP、Prompt我在群里回答过无数次“MCP和Skills到底选哪个”今天用大白话一次讲清楚。Prompt偏方你临时跟AI说“检查一下这段React代码性能问题”。它是一次性指令没记忆换个对话就忘。MCP是外设驱动想象给电脑接了一个打印机AI通过MCP服务器能调外部系统的数据或能力。它解决的是“手够不着”的问题比如查数据库、发请求、读某个内部API。Skills是操作手艺把一套“遇到这类活该怎么干”的流程和工具打包好Agent识别场景后自己取用。它解决的是“脑子记不住、每次都要反复教”的问题。打个比方。MCP像你给新同事开通了公司ERP的账号他能随时查数据Skills却是一份老员工整理好的《报价单审核SOP》——什么字段必须核对、哪类异常要上报、最后走什么流程照着做就行。写Prompt是口头交代一次装Skills是把SOP打印好放在桌上Agent需要时自己翻。1.3 Skills能干什么、不能干什么先把预期摆正Skills不是改变模型智商的神器。它不能把一个能力很弱的模型变成编程大师但它能让一个本来就会写代码的模型在特定任务上表现得极其稳定。稳定这两个字才是它最大的价值。比如我写了一个Skills专门用来审查前端React组件的性能问题。模型本身知道什么是useMemo但每次审查时它总是看心情发挥——有时候记起来要看props稳定性有时候忘了。把它写进Skills后每次触发都会按固定顺序查一圈该看的点一个不落。这个特性决定了Skills最适合的场景是你已经有一套成熟打法、但模型总是不稳定执行的流程性工作。2. 解剖一个Skills文件夹、SKILL.md和触发词2.1 最小的Skills长什么样按Claude官方文档的定义一个Skills本质上就是一个目录。我建议你按下面的结构建立第一份my-awesome-skill/ ├── SKILL.md # 技能说明文件核心中的核心 ├── scripts/ # 可选的辅助脚本 │ └── check_react.js ├── assets/ # 参考模板、示例代码、图片 │ └── react-check-list.md └── references/ # 额外的领域文档 └── company-react-style.md先说最关键的一点SKILL.md这个文件名是固定的不能改成READEME.md也不能拆成多个。Agent在扫描技能目录时靠的就是这个文件。文件名不对整个技能都不会被识别。我见不少人在这上面栽过跟头。2.2 SKILL.md的头部信息决定了Agent什么情况下想起你打开SKILL.md开头有一段YAML格式的frontmatter中括号里是必填内容--- name: react-performance-review description: 只在用户要求审查React组件性能或优化前端渲染时使用。... ---namedescription是核心主线。description要写清楚“什么时候该用”而不是只写“这东西能干什么”。原因在于大多数工具不是把所有Skills原文一股脑塞给模型而是把description当成索引让模型判断当前任务是否与这个技能匹配。description写得含糊不清模型就很可能“想不起”你还有个技能可用。比较一下两个description# 写法一太泛容易在加载JSON时被忽略 description: 审查React组件。 # 写法二触发条件清晰模型一眼就知道该不该用 description: 当用户要求检查前端性能、定位组件不必要的重渲染 或提交代码前希望做一轮React代码走查时使用。后面这种写法命中率高很多实测下来特别明显。2.3 正文怎么组织Agent才会真按步骤走SKILL.md正文部分最怕写成“一段散文”。模型读这种内容时很容易只记住大意然后自由发挥。正确的做法是给一个明确的执行程序用编号步骤约束它按顺序来# React性能审查流程 按照下面步骤依次执行每个步骤完成后输出一句简短结果再进入下一步 1. 收集当前组件涉及的所有state、props、context列出可能导致 重渲染的数据源。 2. 检查是否存在每次渲染都新建的对象字面量或箭头函数列出具体行号。 3. 对useMemo/useCallback的使用做一次反向审查是否存在“用错依赖项”或 “过度缓存”导致可读性下降。 4. 如果发现组件在props未变的情况下发生重渲染指出最可能的原因 并给出修复代码片段。 5. 输出一个Markdown表格问题位置 | 严重程度 | 原因 | 改法。关键点在于不要让模型自己决定“要不要查context”你替它决定了。这就像给实习生布置任务真正好用的SOP不会写“认真检查代码”而是写清楚“检查这个文件里的重渲染问题重点看这三类情况”。2.4 SKILL.md和AGENTS.md别把两件事搅在一起现在很多项目里还有另一个文件叫AGENTS.md有些朋友会问这俩不都是给Agent看的提示词吗我的分类方式很简单AGENTS.md属于“这个项目的人规”比如代码风格、目录结构、测试命令Agent读它来了解当前仓库的项目全局。Skills属于“这个任务的手艺”独立于某个具体项目可以跨项目复用。项目根目录下面那份公司规范、技术栈信息、构建命令这些“项目属性”的东西放AGENTS.md合适而对“遇到React性能问题该按什么思路差”这类方法论的沉淀放进Skills目录才不浪费。项目特定规范和通用技能解耦开维护成本会低很多。3. 亲手写一个前端开发Skills完整拆解3.1 选题别一上来就搞大而全先解决自己的高频痛点我见过有人想一上来就写一个“前端全流程Skills”从创建项目到部署一条龙。这种宏大的东西往往写到一半就废了因为范围太大SKILL.md根本写不细。选你工作里最高频、最烦琐、最需要“每次稳定重复”的一个动作效果最好。我给自己选的第一个Skills是“页面重构前的代码摸底检查”。原因很现实我经常接手老项目每次都要先花半天时间搞清这个页面的数据流、组件结构、样式方案然后才敢动手改。3.2 编写我的“前端摸底检查”SKILL.md我把写好的SKILL.md简化成下面这样--- name: frontend-code-baseline description: 当开始重构一个前端页面/组件或需要了解一个遗留模块的 代码结构时使用。适合Vue和React项目。 --- # 前端代码摸底检查 执行前先读取项目根目录的package.json明确技术栈与脚本命令。 然后严格按照以下顺序输出报告 ## 步骤1页面入口定位 - 根据用户描述或路由配置找到目标页面对应的组件路径。 - 列出该页面引用的所有子组件路径输出组件树的文字版缩进图。 ## 步骤2数据来源分析 - 找到页面内使用的所有useState/useRef/data()定义列出状态名。 - 找到API请求封装位置说明每个接口在什么时机触发。 ## 步骤3样式体系识别 - 判断项目使用的是CSS Modules、Tailwind、Less还是普通CSS。 - 找出全局样式文件中可能覆盖该页面的关键类名。 ## 步骤4风险点输出 - 检查是否存在directly操作DOM、内存泄漏隐患、没有清理的 setTimeout/事件监听。 - 用表格汇总风险位置 | 风险类型 | 影响 | 建议方案。实测过程中我发现一个问题如果“步骤1输出”写得不够具体模型会给出很泛的空话。于是我给每个步骤都追加了“输出格式”约束告诉它“必须给文件路径和行号不能只说某个组件有问题”。加上这一句以后报告质量立刻上了一个台阶。3.3 给Skills配上可执行脚本Skills不止可以塞文字流程还可以放真正的执行脚本。在scripts目录里放一段代码SKILL.md里告诉Agent“需要运行脚本时用node执行”这样就能把重复劳动交给机器。我自己写了一个简单但很实用的小脚本用来扫描一个React组件里所有未使用变量和明显的问题// scripts/quick-scan.js // 用法: node quick-scan.js 文件路径 const fs require(fs); const filePath process.argv[2]; if (!filePath) { console.error(请传入组件文件路径); process.exit(1); } const source fs.readFileSync(filePath, utf-8); const destructuredVars []; const regex /const \{([^}])\} (?:props|useState|useContext)/g; let match; while ((match regex.exec(source)) ! null) { match[1].split(,).forEach((v) { destructuredVars.push(v.trim()); }); } destructuredVars.forEach((variable) { const usedCount (source.match(new RegExp(\\b${variable}\\b, g)) || []).length; if (usedCount 1) { console.log([可能未使用] ${variable} 仅出现在解构处); } }); const timerRegex /setTimeout|setInterval/g; if (timerRegex.test(source)) { console.log([风险] 文件包含setTimeout或setInterval, 请检查组件卸载时是否清理); }脚本很简单但验证了一个思路当一个技能需要稳定执行“代码扫描”这类动作时写成确定性脚本比让模型自由分析可靠得多。后来我又在SKILL.md里写了这么一段“如需对目标文件执行静态扫描运行node scripts/quick-scan.js 目标路径并把扫描结果纳入最终报告”模型就会自己去调脚本。3.4 测试并反复修正才是Skills能不能用的分水岭Skill写完之后不能直接收工。我和大部分人一样第一版就栽过跟头。我先建了一个测试目录专门放几个写得很烂的React组件然后对Agent说“帮我摸一下这个页面的底”。第一次运行它确实激活了Skills但报告只有三段话很多检查点根本没走完。原因是我在SKILL.md里用了“检查是否存在问题”这种措辞模型把“检查一遍”理解成了“大致看看”。改成“每一项必须列出具体行号没有问题的项写‘未发现问题’”之后输出质量立刻稳定了。你越是用“必须”来锁定输出结构模型越不会偷懒。此外还有一些额外的实践建议比如Skill文档就用英文文件名或拼音因为某些CLI工具对中文文件名支持不稳定我把文件夹命名为frontend-code-baseline正文里则用中文描述兼容性最佳。4. Skills在Claude Code、Codex、OpenCode等工具里的安装与调用4.1 Claude Code官方支持的加载路径按官方文档Claude Code里Skills有两种放法一种是项目级一种是用户级。# 项目级放进当前仓库的 .claude/skills 目录 mkdir -p .claude/skills/my-skill cp -r my-skill/* .claude/skills/my-skill/ # 用户级所有项目都能用 mkdir -p ~/.claude/skills/my-skill cp -r my-skill/* ~/.claude/skills/my-skill/放好目录后直接在对话里提需求Agent会扫描目录通过description决定是否加载。想确认有没有识别成功可以在交互里输入斜杠命令查看可用技能列表或直接问一句“当前项目启用了哪些skills”。我自己更喜欢用户级目录因为很多技能与具体项目无关比如审查类、测试类装一次未来所有仓库都能复用。4.2 Codex和OpenCode、Kimi这类网页版工具的情况OpenAI Codex CLI对Skills的用法以官方文档为准核心思路同样是把技能目录放到约定位置。以目前主流做法看常见路径包括工具链典型目录识别方式Claude Code.claude/skills或~/.claude/skills自动扫描匹配descriptionCodex CLI~/.codex/skills或项目内.codex/skills官方持续完善以文档和插件市场为主OpenCode.opencode/skills或个人配置目录支持自定义加载网页版Kimi/DeepSeek等多为平台内置技能或手动上传通过功能面板/技能商店触发分发逻辑和CLI不同多说一句网页版聊天工具里不少所谓“技能市场”和Claude Code的Skills不是一回事。网页版通常是官方在后台预设好了一系列工具能力不太支持你本地上传一个任意Skills目录。很多人在搜索“agent skills”“baoyu skills”时找到的下载包本质是给CLI工具链用的别下下来就往网页版的对话框里塞没有用。4.3 本地模型Ollama能不能玩Skills还有人在问“ollama怎么部署调用java开发的skills”这其实是个很实际的问题。思路并不复杂如果你通过Ollama跑本地模型并且用的是某个支持Skills的终端客户端或自己用LangChain/LlamaIndex这类框架写了Agent调度层那么Skills并没有绑定具体模型——它只是“提示词”的形式组织。你可以把SKILL.md里的正文当成系统的少数示例与执行流程用框架读入再在调度逻辑里根据用户意图判断该加载哪个技能。难点不在Skills而在低参数模型对长流程指令的遵循度。7B模型你让它按五步走经常走着走着就丢了上下文。我的建议如果你主要用本地小模型一个Skills里的步骤不要超过三步每个步骤的输出要求写得更死。等到13B以上的模型步骤可以放宽到五步左右。想用Java开发其实也完全可以核心是把SKILL.md当成结构化文本解析完全语言无关。4.4 测试用例、渗透测试等垂直场景的Skills怎么写除了前端写测试用例的Skills是另一个高频需求。热词里还有测试用例Skills、渗透测试Skills。以测试用例Skills为例一个有效结构是通用测试理论技术栈模板项目级规范。通用部分放在SKILL.md里约定路径覆盖、边界值、异常流这几类测试用例的产出格式技术栈模板可以当脚手架的文件夹做成模板项目级规范就属于AGENTS.md。三者分开复用性会好很高。想写渗透测试相关的Skills时我强烈建议把边界拿捏住只在获得合法授权的项目中使用。把“先读取授权说明再开始信息收集、建模、验证、输出”写进流程这既是职业伦理也是技能可持续使用的底线。5. 我踩过的四个大坑从“没反应”到“上下文爆炸”5.1 模型“看不见”Skills可能是路径和描述的问题第一次测试我的技能时Agent完全没反应就像那个文件夹不存在一样。排查链路是这样的先确认目录名称没有拼错再去查看SKILL.md是否存在然后检查文件名大小写。很多人卡在这一步SKILL.md被写成了skill.md或Skill.mdLinux路径大小写敏感直接导致扫描失败。更隐蔽的一个原因是description写得太宽泛模型看到的20个技能里没有一个跟当前需求强匹配所以它“没想起”来。把描述改成“当用户要求检查前端性能”后识别率明显提升。5.2 技能识别了但执行到一半开始跑偏技能激活成功但Agent只执行到第三步就去干别的了还自作主张加了个“额外检查”。这个问题根源在于SKILL.md正文的指令强度不够。模型遇到“输出格式”后面跟了一个表格模板时如果模板写得不够死它会认为这是参考示例而不是必须遵守的格式。修复非常简单在步骤后面加一句“以上步骤全部完成后才能输出最终报告严禁跳过任一编号步骤。”措辞越绝对模型遵守得越好。5.3 带脚本的Skills有安全风险要给脚本加白名单Skills里的脚本一旦被Agent调用就相当于有了本机执行权。如果技能是从网上直接下载的不看代码就放进目录等于把所有项目的代码目录开放给了第三方脚本。这类问题我在社区里见过不止一次。我自己的处理方式是下载的每个带scripts的Skills先通读全部代码检查有没有网络请求、文件删除、环境变量读取这些敏感操作。更稳的做法是把可能被脚本影响的范围限制在项目目录内不在SKILL.md里写“允许执行范围外的命令”这种话。5.4 技能包内容太多把上下文窗口塞满了我第一次往Skills里塞了一个巨大的前端规范PDF转成的Markdown整整两万多字。结果Agent每次激活这个技能时都把它全文端进上下文token开销夸张有时还因此截断对话。后来我改成只把规范文件中与“组件性能”相关的两个章节放进去效果反而更好。写Skills更像给实习生画重点不是给他直接扔一套百科全书。文本内容尽量控制在几百行内长文档放进references目录让Agent按需读取而不是一次性全文加载这个原则立省很多token。6. 说点圈内见闻和我现在的使用习惯6.1 关于“作者”的一些瓜标题说了文末要聊作者的瓜那我就捡能说的展开。Skills这波热度起来后最先卷起来的就是各大作者。有个人作者一个人出了十几个技能包从“代码走查”到“写周报”全都覆盖按周更新跟互联网公司发版一样勤快。另外一些大厂风格的技能仓库也开源了开发者二创的作品在网上反复被转发甚至形成了一波“Skills集市”。最搞笑的是“前任.skills”这个梗被网友玩成了各种梗。有个开发者把这个文件夹装进Claude Code然后在README里写了一段“让AI帮你分析上一段感情为什么结束”的提示词实际当然是个恶搞但他把SKILL.md的YAML结构和触发词玩得非常熟练。评论区都在说“这个技能是我第一个想装进Claude Code的”这波传播也反过来让更多人学会了Skills的目录格式。还有一桩不算瓜的瓜某些作者在技能版权声明里用词相当激进直接规定“别人不许改我的SKILL.md”。但Skills本质上就是文本在开源生态里这种限制本质上左右不了fork更多是姿态表达。社区也因此吵过一轮讨论“技能包的许可证到底该怎么定”。这都是生态早期的正常现象。6.2 我现在的使用习惯以及给新手的全套建议Skills现在融进了我每天的干活主流程开工必带“frontend-code-baseline”接手旧代码时先让Agent跑一轮摸底涉及我熟悉的性能优化流程时会手动要求激活“react-performance-review”输出固定格式的报告把公司内部常用的测试数据脱敏脚本封装成一个带scripts的Skills让Agent按指定步骤调用。给想上手的朋友三条直接建议先别下载一堆现成Skills先自己写一个对当前工作最有帮助的哪怕它只有几十行描述写完你的理解会完全不一样。严格遵循 SKILL.md 的md格式名字和yaml头不要创新工具生态还很年轻先让别人能识别再谈个性化。每次给技能升级时保留版本号把之前的SKILL.md存在子目录里方便出问题时回滚。最后透露一个小技巧检查技能是否生效的最快方式是在SKILL.md的某个步骤里故意写一句“请先输出‘技能已启用’再继续后面的步骤”。如果看到这句暗号说明链路全通了后面再调描述和结构都会更有底气。