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 是基础单位，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.md

good-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", encoding="utf-8") as f: data = json.load(f) print(f"LCP: {data.get('lcp')}ms") print(f"CLS: {data.get('cls')}") print(f"INP: {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/scripts

4.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 className="card" 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 常见问题速查表

5.2 技能不生效的排查清单

如果你发现 Agent 没有按照预期使用技能，可以按下面的顺序排查：

1. 确认技能目录位置：是否放在当前 AI 编程助手可扫描的范围内。
2. 检查SKILL.md文件名和大小写：必须严格命名为SKILL.md。
3. 检查 frontmatter 格式：冒号后面是否有空格，name 是否合法。
4. 检查 description 描述：是否与你的任务请求有语义重叠。
5. 查看客户端日志：多数 AI 编程助手会输出技能加载日志，能直接看到“Skill loaded”或“Skill not found”提示。
6. 清理并重新启动：配置变更后，很多工具不会热加载技能目录。

如果以上都排查了还是不行，最稳妥的办法是去对应工具的官方文档，查询最新版本对技能目录和格式的支持情况。这个领域变化很快，网上过时教程非常多。

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 的最佳实践和模板仓库。

技术的具体实现方式会不断变化，但“把经验沉淀为可复用技能”的思路会是长期趋势。建议你从手头重复度最高的任务开始，先沉淀一个小技能，跑通一次完整流程，再逐步扩充到团队的更多场景。用起来，这套方法论才算真正落地。