Agent Skills 实战：编写 SKILL.md 打造可复用的 AI 编程助手技能包

最近关注 AI 编程工具落地时被 GitHub 上addyosmani/agent-skills这个仓库刷了屏。这个仓库之所以有代表性不是因为它堆了多少炫技代码而是它把“Agent Skills智能体技能”从单点技巧变成了一套可沉淀、可复用、可共享的工程实践。很多开发者看完之后的反应是原来我们每天都在让 AI 重复踩坑却没有把这些经验固化成技能文件。这篇文章就围绕 Agent Skills 这个主题展开从概念、目录结构、标准格式讲起再带大家从零手写一个可用的技能包并接入常见 AI 编程助手。无论你是前端、后端还是测试同学只要日常会借助 Claude Code、Cursor、GitHub Copilot 或类 ChatGPT 工具写代码、审查代码、处理重复事务这套思路都值得掌握。读完之后你会知道Agent Skills 和普通 prompt 有什么区别SKILL.md到底怎么写技能放到哪里才能被 Agent 自动发现以及团队如何维护一套长期有效的技能库。1. Agent Skills 是什么1.1 从“临时对话”到“可复用技能”先看一个非常常见的场景你每天都要让 AI 助手帮你做代码审查于是每次都要重复输入“请帮我检查这个前端项目重点关注组件拆分是否合理、是否存在不必要的重渲染、有无明显的安全风险……”一次两次还行时间一长你就发现每次输入的内容大同小异但 AI 的输出质量却飘忽不定。有时候它会认真按照你给的要求逐项检查有时候又会泛泛而谈。Agent Skills 要解决的就是让这个“每次都靠临场交代”的过程变成“预先打包好的能力包”。一个技能文件里可以包含这个技能什么时候该被调用调用后 Agent 应遵循哪些步骤应该参考哪些模板、规范或示例最终输出应该是什么格式。简单说普通 prompt 是一次性指令而 Skill 是长期有效的“操作手册”。1.2 Agent Skills 在 Agent 体系中的位置在 Anthropic 提出并推广的 Claude Skills 概念中技能被设计成一种特殊的指令文件。官方给出的常见结构是一个文件夹内部包含一个SKILL.md文件以及可选的脚本、参考文档、资源文件。my-skill/ ├── SKILL.md ├── scripts/ ├── reference/ └── assets/SKILL.md是核心它使用 Markdown 写成顶部有 YAML 格式的元信息描述技能的名称和用途。Agent 在收到用户任务时会先读取当前工作区里有哪些可用技能然后根据任务描述判断应该调用哪个技能再加载对应文件最后按技能里的指令完成任务。这个机制和“把 prompt 写在系统提示词里”不一样。系统提示词是全局的Agent 每次对话都要携带会占用大量上下文而 Skill 是按需加载的只有任务匹配到技能描述时才会被读取效率更高也更灵活。1.3 Skills、Plugins、MCP、Prompt 有什么区别很多同学初次接触 Agent Skills 时会把技能、插件、MCP 协议、普通提示词混在一起。这里做一个简单的对比概念核心作用典型载体是否需要网络请求Prompt给 AI 的一次性指令或背景信息文本否Agent Skill可复用的任务操作手册SKILL.md 附件不一定Plugin面向宿主应用的扩展能力配置文件 / 插件包通常需要MCPModel Context Protocol标准化 AI 与外部工具/数据源的通信协议JSON-RPC 接口是本地或远程从层级来看Prompt 是基础单位Skill 是把多个 Prompt、步骤、示例组装成任务流的“上层封装”MCP 解决的是 Agent 如何调用外部能力比如读取数据库、调用 API、操作浏览器Plugin 更偏向应用商店体系比如浏览器插件或 IDE 插件。Agent Skills 并不取代 MCP 和 Plugin它提供的是“任务执行的认知层”。你可以把它理解为技能告诉 AI“按什么思路做这件事”而 MCP 和插件告诉 AI“用什么工具做这件事”。1.4 典型应用场景Agent Skills 适合解决重复度高、规则明确、依赖专业经验的任务。我在社区仓库和自己项目里看到的典型场景包括代码审查按团队规范检查 Pull Request输出问题列表、严重级别和修复建议前端性能分析让 Agent 读取 Lighthouse 报告给出可落地的优化方案自动化测试针对某个业务模块自动生成符合规范的单元测试用例数据清洗对 CSV 文件执行统一的数据质量检查和清洗流程文档生成根据代码变更自动更新 README 和接口文档安全审计对登录、鉴权、SQL 拼接等高风险代码做专项检查。本质上“凡是你能整理成工作流清单的事情都能沉淀为 Agent Skill”。2. 环境准备与前置知识2.1 使用 Agent Skills 的最小环境如果你只是想阅读和借鉴社区里的技能文件只需要一个能浏览 Markdown 的工具比如 VS Code 或 GitHub 网页端。如果你希望让技能真正被 AI Agent 调用就需要一个支持 Skills 机制的客户端。目前比较主流的是 Claude Code、Claude Desktop、Cursor、GitHub Copilot 等 AI 编程助手。不同工具对技能的目录约定和加载方式可能有差异但核心都是让 Agent 能在特定目录下发现SKILL.md文件。在开始之前建议先把本地的 Node.js、Git、以及你常用的 AI 编程助手安装好。这不是硬性要求但后面做技能测试时会用到。2.2 推荐目录结构如果只是个人使用社区里最常用的目录结构是~/.claude/ └── skills/ ├── code-review/ │ └── SKILL.md └── web-performance/ └── SKILL.md如果是项目级使用可以把技能放在仓库中的约定目录例如your-project/ ├── .claude/ │ └── skills/ │ ├── code-review/ │ │ └── SKILL.md │ └── unit-test/ │ └── SKILL.md ├── src/ └── README.md需要说明的是不同 AI 编程助手对技能目录的默认查找路径并不完全相同而且版本迭代较快。上面给出的目录结构是当前社区常见的约定实际使用时请以你所使用工具的最新官方文档为准。2.3 版本与兼容性提示Agent Skills 还处于快速演进阶段。网络上很多文章会给出具体的路径和 API但很可能过一段时间就变了。我的建议是不要把“某个版本的目录路径”当作永恒标准优先关注SKILL.md的编写规范和设计思路每次升级 AI 编程助手后重新检查技能是否正常加载如果团队需要长期沉淀技能给每个 SKILL.md 文件加上日期和适用工具版本减少维护困惑。3. SKILL.md 核心结构拆解3.1 元信息让 Agent 知道“什么时候用我”一个标准的SKILL.md开头是 YAML 格式的 frontmatter--- name: frontend-code-review description: 用于对前端项目进行代码审查重点关注组件设计、渲染性能、可访问性和安全隐患。当用户要求审查 React/Vue 组件或提出代码优化需求时使用。 ---其中name是技能名必须简短、能体现技能职责description是最关键的部分Agent 就是通过阅读 description 来判断当前任务是否匹配该技能。写 description 时有几个技巧明确说明“什么时候该使用”明确说明“什么时候不该使用”避免误触发使用任务相关的关键词比如组件审查、性能优化、安全检查描述尽量开口具体减少模糊表达。例如description: 仅当用户要求审查 React 组件时使用。不适用于后端接口审查、数据库设计和文档编写。3.2 正文指令告诉 Agent“按什么流程做”frontmatter 下方是正文通常以 Markdown 语法写成。它负责描述任务的执行步骤、输出格式、注意事项。下面是一段示例# 前端代码审查流程 当执行本技能时请严格遵循以下步骤 1. 先阅读项目中的 package.json确认技术栈版本。 2. 遍历 src/components 目录下的核心组件。 3. 对每个组件检查以下维度 - 组件拆分的粒度是否合理。 - 是否存在不必要的 useEffect 或 setState。 - 列表渲染是否有稳定的 key是否缺少 memo。 - 事件处理是否有内存泄漏风险。 4. 输出审查报告时按以下格式组织 - 问题描述 - 问题位置 - 严重程度严重 / 中等 / 建议 - 修改建议 5. 所有建议必须以可落地的代码片段形式给出禁止只说“需要优化”而不给方案。正文的编写思路是把专家经验转化成 Agent 可以逐步执行的操作步骤。写得越具体输出越稳定。3.3 参考示例给 Agent 提供“高质量样本”大模型擅长模仿模式所以在技能文件里附上优秀示例通常会明显提升输出质量。你可以在技能目录中增加reference/文件夹存放示例代码或历史优秀输出。比如frontend-code-review/ ├── SKILL.md └── reference/ ├── good-review-example.md └── bad-review-example.mdgood-review-example.md里可以放一份高质量评审报告样本让 Agent 在生成报告时参考。这比在正文中反复强调“要写清楚”更有效。3.4 可执行脚本让技能具备“动手能力”有些技能不只是“给建议”还需要直接跑脚本、分析文件或生成代码。此时可以在技能目录下放scripts/文件夹并让 Agent 在需要时调用。例如一个页面性能分析技能可以包含# scripts/analyze_metrics.py import json import sys def main(): report_path sys.argv[1] with open(report_path, r, encodingutf-8) as f: data json.load(f) print(fLCP: {data.get(lcp)}ms) print(fCLS: {data.get(cls)}) print(fINP: {data.get(inp)}ms) if __name__ __main__: main()然后在SKILL.md中写清楚分析性能数据时运行python scripts/analyze_metrics.py 报告路径这里需要注意的是允许 Agent 执行脚本本质上等同于授权它运行你本地的代码。因此脚本必须经过人工审查并且遵循最小权限原则。4. 项目实战为自己团队制作一个前端代码评审技能4.1 需求分析假设团队目前面临这些问题每次人工评审代码标准不统一不同人关注的维度不一样AI 助手生成的审查意见太泛比如“建议优化性能”这种无法落地的废话新人加入团队后很难快速掌握组件评审的关注点。我们希望做一个 Agent Skill让 AI 按照统一的清单进行前端代码审查最终输出结构化的问题报告每条问题都带有严重级别和修改建议最好能直接粘贴到 PR 评论里。4.2 创建技能目录先创建一个干净的目录用来存放技能文件。mkdir -p ~/.claude/skills/frontend-code-review/reference mkdir -p ~/.claude/skills/frontend-code-review/scripts cd ~/.claude/skills/frontend-code-review如果你想先放在项目仓库里测试也可以创建项目级目录mkdir -p .claude/skills/frontend-code-review/reference mkdir -p .claude/skills/frontend-code-review/scripts4.3 编写 SKILL.md下面是一份完整的SKILL.md示例--- name: frontend-code-review description: 对前端项目进行代码审查重点关注组件设计、渲染性能、状态管理、可访问性和安全风险。当用户要求检查 React、Vue 组件或分析前端代码质量时使用。不适用于后端接口、数据库结构或系统架构审查。 --- # Frontend Code Review 你是一名资深前端工程师现在需要按照团队规范对代码进行审查。 ## 审查步骤 ### 1. 项目背景识别 - 读取 package.json确认框架版本React/Vue和关键依赖。 - 如果存在 README 中的规范说明先读取。 ### 2. 组件设计审查 - 组件是否满足单一职责原则。 - 组件体积过大时建议拆分子组件。 - props 设计是否合理是否存在 boolean 泛滥问题。 ### 3. 渲染性能审查 - 是否存在不必要的 setState。 - 长列表是否使用虚拟滚动。 - 函数组件是否缺少 memo 或 useCallback。 - 是否存在频繁创建新对象导致子组件重渲染的问题。 ### 4. 状态管理审查 - 本地产出临时内容是否存放在框架状态中。 - 跨组件共享数据是否避免多层 props 透传。 - 状态更新是否存在异步时序问题。 ### 5. 可访问性审查 - 图片是否包含 alt。 - 按钮是否存在无文本触发的问题。 - 交互元素是否可以通过键盘操作。 ### 6. 安全审查 - 是否使用 dangerouslySetInnerHTML 或 v-html。 - URL 跳转是否正确处理。 - 登录态、权限相关逻辑是否避免暴露敏感信息。 ## 输出格式 必须按 Markdown 表格输出 | 序号 | 文件位置 | 问题描述 | 严重程度 | 修改建议 | | --- | --- | --- | --- | --- | 严重程度仅允许严重、中等、建议。 每条建议必须附带代码片段代码片段应当是可执行的修改方案。 ## 注意事项 - 不要输出无关的性能理论。 - 不要泛泛而谈必须给出具体文件和行号。 - 如果某个维度没有发现问题不需要单独输出。4.4 提供参考输出样例为了让 Agent 的输出风格更稳定我们可以在reference/目录下放一份高质量输出样例。# 示例审查输出 | 序号 | 文件位置 | 问题描述 | 严重程度 | 修改建议 | | --- | --- | --- | --- | --- | | 1 | src/components/UserList.tsx:42 | 列表项未使用稳定 key直接使用 index | 中等 | 使用 uid 代替 index避免删除项后状态错乱 | | 2 | src/components/UserList.tsx:89 | 每次渲染时创建匿名函数子组件被 memo 后仍频繁重渲染 | 建议 | 提取为 useCallback | 修改示例 tsx // 修改前 {users.map((user, index) ( UserItem key{index} user{user} onClick{() handleSelect(user.id)} / ))} // 修改后 {users.map((user) ( UserItem key{user.uid} user{user} onClick{handleSelect} / ))}这份样例让 Agent 能学习到“具体文件位置 严重级别 可执行修改建议”的呈现方式。 ### 4.5 运行验证 接入技能之后我们先用一个临时测试项目验证效果。 准备一个简单的 React 组件 tsx // src/components/ProductCard.tsx import React, { useState } from react; export default function ProductCard({ product, onSelect }) { const [count, setCount] useState(0); return ( div classNamecard onClick{() onSelect(product.id)} img src{product.image} / h3{product.name}/h3 p价格{product.price}/p button onClick{() setCount(count 1)}加入购物车 {count}/button /div ); }把项目目录切换到技能所在的工作区然后在 AI 编程助手中输入请用 frontend-code-review 技能审查 src/components/ProductCard.tsx如果 Agent 正确加载了技能它应该会输出包含表格的审查报告而不是简单给几句建议。比如可能会指出img缺少alt属性按钮点击事件没有阻止事件冒泡count状态只用于展示如果组件被 memo 包裹会导致局部刷新问题组件名和职责不够清晰ProductCard中包含了购物车交互建议拆分为展示组件和容器组件。这就是技能生效的标志AI 不再是“自由发挥”而是按照你的清单逐项检查。5. 常见问题与排查思路5.1 常见问题速查表问题现象常见原因解决思路Agent 完全不调用技能技能目录未被识别或 description 与任务描述不匹配检查技能目录路径改写 description加入更明确的关键词技能被调用但输出很泛SKILL.md 正文步骤写得不够具体在技能正文中明确要求“输出表格”“给出文件行号”等强制性约束输出的代码无法运行参考示例过少Agent 自行发挥了不存在的 API在 reference 中放入更多可运行示例并在正文中限定技术栈版本技能目录存在但 Agent 报找不到文件配置文件未刷新或路径权限问题重启 AI 编程助手检查目录权限查看后端日志确认技能加载状态多个技能同时被触发不同技能的 description 有重叠在 description 中增加“不适用”场景限制技能执行脚本不安全技能目录被加入不受信任的脚本对脚本进行人工审查优先使用只读操作禁止自动执行高风险命令5.2 技能不生效的排查清单如果你发现 Agent 没有按照预期使用技能可以按下面的顺序排查确认技能目录位置是否放在当前 AI 编程助手可扫描的范围内。检查SKILL.md文件名和大小写必须严格命名为SKILL.md。检查 frontmatter 格式冒号后面是否有空格name 是否合法。检查 description 描述是否与你的任务请求有语义重叠。查看客户端日志多数 AI 编程助手会输出技能加载日志能直接看到“Skill loaded”或“Skill not found”提示。清理并重新启动配置变更后很多工具不会热加载技能目录。如果以上都排查了还是不行最稳妥的办法是去对应工具的官方文档查询最新版本对技能目录和格式的支持情况。这个领域变化很快网上过时教程非常多。6. 最佳实践与工程建议6.1 技能粒度宁愿多拆几个也不要一把梭一个技能只做一件事把粒度控制好。比如“前端代码审查”和“后端安全审计”不要放在同一个 SKILL.md 里否则 Agent 在匹配时容易犹豫输出的风格也会不一致。更合理的做法是拆成多个小技能skills/ ├── react-code-review/ ├── vue-code-review/ ├── security-audit/ └── unit-test-generator/每个技能描述都清晰Agent 在匹配时也能更精准地选择。6.2 版本管理与变更记录技能文件也是代码资产建议纳入 Git 管理。每次修改 SKILL.md都应该在 commit message 里写清楚变更原因。一个常用的做法是在技能目录中添加CHANGELOG.md# Changelog ## [2025-01-10] - 新增可访问性审查维度。 - 修改输出格式从普通列表改为 Markdown 表格。 - 增加 React 19 的依赖检查说明。这样团队花费大量精力沉淀出来的技能规范才能变成真正的资产而不是散落在某台电脑里的临时文本。6.3 安全边界技能文件里的脚本要实现最小权限原则默认只读不自动修改文件需要写入时必须向用户明确提示禁止在技能中写死任何密钥、Token、密码外部来源的技能文件使用前必须人工审查如果要访问网络 API必须通过环境变量注入密钥不允许硬编码。例如在脚本中获取环境变量import os token os.getenv(INTERNAL_API_TOKEN) if not token: raise RuntimeError(缺少 INTERNAL_API_TOKEN 环境变量)这样既能满足自动化需求又不会被误提交流水线。6.4 团队协作建立技能评审机制团队如果想长期维护技能库建议参考代码评审的方式任何人提交技能变更时都提 Pull Request技能合并前至少由另一位同事实际测试一遍定期清理不再使用的技能避免技能数量膨胀后互相干扰在 README 中维护一份技能索引表说明每个技能的用途、维护人和适用场景。6.5 让技能具备“自解释能力”一份好的技能文件即使没有 AI Agent人也应该能读懂。也就是说SKILL.md本身就是一份 SOP标准作业程序。这样做有两个好处如果未来更换 AI 工具技能文件可以直接迁移新人可以通过阅读技能文件快速了解团队在某个任务上的规范。因此不要在SKILL.md里写太多只有模型才能看懂的暗号尽量用自然语言写成一份任何人都能执行的流程文档。7. 总结与进阶方向Agent Skills 本质上是一种“经验工程化”的实践。它把人们反复叮嘱 AI 的内容从聊天记录里抽离出来整理成结构化的操作手册让 AI Agent 在合适的时机自动加载并执行。addyosmani/agent-skills这类仓库之所以受欢迎正是因为它展示了一个方向AI 时代的前端开发者和后端工程师不仅要会写代码还要学会把隐性经验整理成显性的技能资产。通过这篇文章你已经掌握了 Agent Skills 的核心概念、SKILL.md的标准结构并且亲手创建了一个可供 AI 编程助手使用的前端代码评审技能。接下来可以继续实践的方向包括研究你所使用 AI 编程助手对技能目录和格式的最新支持尝试把团队规范、常见错误清单逐步“技能化”学习 MCP 协议为技能接入外部工具和数据源关注社区中关于 Claude Skills、Agent Skills 的最佳实践和模板仓库。技术的具体实现方式会不断变化但“把经验沉淀为可复用技能”的思路会是长期趋势。建议你从手头重复度最高的任务开始先沉淀一个小技能跑通一次完整流程再逐步扩充到团队的更多场景。用起来这套方法论才算真正落地。