AI Agent技能化设计：从SKILL.md到可复用技能库-平芜编程栈

之前在做 AI 编程助手落地时，我发现自己反复在“如何让 Agent 稳定地干好一件事”上浪费时间。直接对话时它经常“自由发挥”，换个人问结果又不一样；后来接触到addyosmani/agent-skills这类技能化思路之后，才意识到问题不是模型不够强，而是我们缺少一套可复用的“技能资产”。

这篇文章就围绕 AI Agent 的技能化设计展开，结合addyosmani/agent-skills的思路，讲清楚什么是 Agent Skills、技能文件如何组织、怎么写一个可以在 Claude Code、Cursor 等工具中复用的技能，以及团队落地时需要注意的坑。不管是刚开始接触 AI 编程助手的同学，还是已经在内部推广 AI 编码规范的工程师，都可以从中拿到一套可复用的方法。

1. 背景与核心概念

1.1 什么是 Agent Skills

Agent Skills 可以理解为“给 AI 助手写的标准化操作手册”。它把一类任务的处理流程、输入输出格式、判断标准、注意事项，沉淀成一个独立的目录或文件。当用户请求命中该技能的使用场景时，AI 助手会自动载入这份手册，按里面的步骤去执行，而不是完全靠临时推理。

在addyosmani/agent-skills项目中，作者把日常编码里高频出现的任务整理成了一个个技能文件，例如编写 Pull Request 描述、执行代码审查、复现 Bug、补齐测试、整理文档更新等。每个技能都有一套完整的“动作”，相当于让 Agent 从“什么都会一点”变成“特定任务非常专业”。

这里要特别注意：Skills 不是新的提示词技巧，也不是某个模型的专属功能，而是一种工程化的组织方式。它的核心价值在于把“经验”从人的脑子里、从聊天记录里，搬进项目仓库，成为可维护、可评审、可版本化的资产。

1.2 技能、提示词、插件三者有什么区别

很多读者会把 Agent Skills 和 Prompt、Plugin 混为一谈，这里用一个表格来区分：

概念	本质	典型例子	特点
Prompt	一次性指令文本	“帮我写一个二分查找”	离散、不可复用、依赖现场描述
Plugin / MCP	程序化能力扩展	文件读写、Git 操作、数据库查询	是“手脚”，负责具体动作
Agent Skills	任务操作标准	提交 PR、做 Code Review	是“脑子里的流程”，约束 Agent 怎么做

简单来说：Plugin 解决“能做什么”，Skill 解决“怎么做、做到什么程度”。一个完整的 Agent 工作流通常两者都要用——Skill 里会写清楚调用哪些工具、按什么顺序执行、输出什么格式，底层能力由 Plugin 或内置工具提供。

1.3 为什么需要技能库

我自己的体感是，AI 编码助手刚接入团队时“新鲜感很强，稳定性很差”。同一个需求，上午问和下午问，结果风格完全不同；让 Agent 改代码，它经常顺手重构了不该动的文件。根本原因是 Agent 没有一个稳定的“行为基线”。

技能库正好补上这个缺口。它的收益可以归纳为三点：

结果可预期：同一类任务走同一套流程，输出格式统一，评审成本降低。
经验可沉淀：团队踩过的坑、约定的规范，写进技能文件后，新成员也能复用。
行为可审计：技能是仓库里的明文文件，谁改了什么、为什么改，Git 历史一清二楚。

所以，addyosmani/agent-skills这类仓库的流行，本质上反映了 AI 编程从“聊天问答”走向“工程化落地”的趋势。我们不再是让 AI 猜需求，而是给它一份岗位说明书。

2. 环境准备与工具支持

2.1 支持 Skills 的主流 AI 编码工具

Agent Skills 目前没有统一的国际标准，不同工具的加载方式有差异。以 Claude Code 为代表的工具已经原生支持SKILL.md技能目录机制；Cursor 通过 Rule 体系实现类似效果；其他一些基于大模型的 IDE 插件，也都陆续支持在项目目录下放置规则文件。

因此，在开始之前，建议你先确认自己使用的工具支持哪种子目录约定。本文示例以“.claude/skills/<技能名>/SKILL.md”的形式为主，因为这套结构最接近addyosmani/agent-skills仓库的组织方式。如果你用的是其他工具，目录名或配置字段可能略有不同，但整体的设计思路完全通用。

2.2 技能目录与运行流程

一个典型的技能目录结构如下：

.claude/ └── skills/ ├── write-pr/ │ ├── SKILL.md │ └── reference/ │ └── pr-template.md ├── code-review/ │ ├── SKILL.md │ └── review-checklist.md └── reproduce-bug/ ├── SKILL.md └── scripts/ └── collect-logs.sh

Agent 的运行流程大致是这样的：

用户提出请求。
工具根据请求内容，结合每个技能的description元信息判断是否匹配。
匹配成功的技能被加载到上下文。
Agent 按照SKILL.md中的步骤执行，必要时读取同目录的参考文件、运行辅助脚本。
输出符合技能要求的结果。

这里需要提醒的是，技能并不是每次都会被强制加载，它依赖于工具的描述匹配机制。所以技能的描述字段写得越精准，命中的概率越高，这一点后面会专门讲。

2.3 版本说明

AI 编程工具的迭代速度非常快，技能目录结构和元信息字段在不同版本之间可能会调整。本文示例不绑定某个具体的软件版本，建议你在实操时查看当前所用工具的官方文档确认字段名。后面所有示例代码，只要目录位置正确、字段符合你使用的工具规范，基本可以原样复制。

3. 技能文件结构与编写规范

3.1 SKILL.md 的文件结构

SKILL.md是整个技能的核心文件，它决定了 Agent 在这个任务里“先做什么、后做什么、输出什么”。结构上通常分为三部分：

Frontmatter 元信息：技能名称、触发描述、可使用的工具等。
正文流程：分步骤的操作指令。
附录/参考：模板、命令行片段、检查清单。

下面是一个最简示例：

--- name: write-pr description: 当用户需要创建或完善 Pull Request 描述时使用。 --- # Write PR Description 1. 获取当前分支的改动文件列表。 2. 对比目标分支，总结主要变更。 3. 按模板生成 PR 标题和描述。 4. 检查是否存在破坏性变更，若有则单独说明。

这个文件看起来简单，但已经能显著提升 Agent 生成 PR 描述的一致性。实际使用时，你可以在正文中写得更加细致，甚至可以要求 Agent 在本地跑一段命令来收集信息。

3.2 Frontmatter 元信息怎么写

Frontmatter 是技能文件的“门面”，工具主要靠它来做技能匹配。常见的字段包括：

字段	作用	建议
`name`	技能的唯一标识	使用短横线命名，如`code-review`
`description`	描述技能适用的任务场景	写得具体一些，包含触发关键词和边界条件
`allowed-tools`	允许技能使用的工具白名单	根据任务需要限制，例如只允许 Git 命令

description是最容易被忽视、影响却最大的字段。不要写“用于代码审查”这种模糊描述，而应该写“当用户要求对某个 PR 或分支进行代码审查，检查设计、安全、性能、测试覆盖等问题时使用”。描述越具体，Agent 越不容易在错误的时机调用错误技能。

3.3 正文指令的编写原则

正文部分要像给新同事写操作手册一样，明确到动作级别。我总结了四条原则：

步骤可执行：每一步都要是 Agent 能直接完成或调用工具完成的操作，不要出现“分析一下”这种没有落地动作的表述。
输出有格式：明确要求输出 Markdown 列表、表格还是代码块，统一 Review 结果的呈现。
边界要写死：告诉 Agent 哪些文件不要改、哪些目录不要动，避免“顺手优化”。
失败有兜底：遇到命令执行失败、信息不足时该怎么做，也要写在技能里。

举个例子，如果技能要求 Agent 在改代码前先运行测试，就要写明“运行pytest，如果失败，停止修改并输出错误信息”。否则 Agent 可能忽略测试步骤直接改代码。

3.4 辅助脚本与参考文件

一个技能目录里不只是SKILL.md，你还可以放辅助脚本、模板文件、文档资料。这些文件的用途是减少 Agent 的“临时发挥空间”。

例如，在code-review技能目录下放一份review-checklist.md，里面列明团队关注的检查点；在write-pr技能下放一份pr-template.md，Agent 生成描述时直接套用。辅助脚本则可以封装一些 Agent 不太擅长、容易出错的命令，比如复杂的 Git 分支比较逻辑。

技能目录里的文件路径要写在SKILL.md中，告诉 Agent 什么时候去读哪个文件、执行哪个脚本。这样技能才是完整的，而不是一段孤零零的提示词。

4. 完整实战：从零编写一个 PR 描述生成技能

4.1 需求分析

先确定一个真实场景：团队规定所有 Pull Request 都必须包含变更背景、改动清单、测试说明、影响范围。直接让 Agent “帮我写 PR 描述”，它可能给你一段结构随意、信息不足的内容。

我们需要做的，是把“规范的 PR 描述”变成一项技能。目标是：当 Agent 检测到用户想创建或完善 PR 描述时，自动按标准流程收集信息并生成结构化内容。

4.2 创建目录与 SKILL.md

假设项目根目录下有.claude/skills/目录，我们新建一个write-pr技能：

.claude/skills/write-pr/ ├── SKILL.md └── reference/ └── pr-template.md

SKILL.md内容如下：

--- name: write-pr description: 当用户要求创建、完善 Pull Request 描述，或说明提交内容需要生成 PR 时使用。适用于 feature 分支合并前的 PR 文案整理。 --- # Write Pull Request Description 请严格按照以下流程生成 Pull Request 描述。 1. 确定分支信息： - 查看当前分支名称。 - 确定目标分支，通常是 main 或 master。 - 如果无法确定目标分支，请先询问用户。 2. 收集变更信息： - 使用 `git diff --stat` 查看变更文件列表。 - 使用 `git log` 获取提交记录。 - 不要修改任何代码文件。 3. 按照 `reference/pr-template.md` 模板生成内容： - 标题使用简短的行为描述格式。 - 变更背景说明为什么要做这次改动。 - 改动清单按模块整理，使用无序列表。 - 明确写出是否包含破坏性变更、是否需要数据库迁移。 4. 输出要求： - 只输出最终 PR 描述，不要输出思考过程。 - 如果信息不足以生成完整描述，列出缺失信息并询问用户。 - 不使用“优化”“修复”这类模糊词作为完整描述，必须补充具体对象。

4.3 添加模板文件

接着创建reference/pr-template.md：

## 变更背景 说明本次改动的业务背景和动机。 ## 改动清单 - 模块A：描述具体改动 - 模块B：描述具体改动 ## 测试说明 - 本地执行了哪些测试命令 - 覆盖的关键场景 ## 影响范围 - 是否有破坏性变更：是/否 - 是否需要数据库迁移：是/否 - 涉及的核心模块列表 ## 检查项 - [ ] 代码格式化已执行 - [ ] 单测已通过 - [ ] 无敏感信息提交

模板的作用是约束格式，但也不要把字段写得太死。Agent 会根据实际变更内容填充，模板只是保证结构统一。

4.4 启用与验证

不同工具启用技能的方式略有差异。以支持.claude/skills目录结构的工具为例，技能目录放在项目根目录后，工具启动时会自动扫描。

验证时，可以先切换到一个有改动的分支，然后在对话中输入：

请为当前分支生成一份 PR 描述

如果技能被正确命中，Agent 会先执行 Git 命令收集信息，再按模板输出。你可以从两个维度检查效果：

格式是否统一：每次生成的 PR 描述结构是否一致。
信息是否完整：是否包含变更背景、测试说明、影响范围。

如果输出内容偏离模板，可以检查description是否写得足够明确，或者调整正文中的步骤表述。

4.5 结果说明

一个合格的技能输出类似下面这样：

## 变更背景 订单列表页查询接口在数据量增大后响应变慢，本次将 SQL 查询改为分页查询并补充索引。 ## 改动清单 - 订单查询服务：新增分页参数 - 数据访问层：优化查询语句并添加联合索引 - 接口文档：更新分页示例 ## 测试说明 - 执行 `mvn test` 通过 - 使用 10 万条数据验证分页响应时间 ## 影响范围 - 是否有破坏性变更：否 - 是否需要数据库迁移：是，新增索引 - 涉及的核心模块：订单模块

到这里，一个最基本的 PR 描述技能就算完成了。接下来，我们再看一个更复杂的例子。

5. 进阶实战：代码审查与 Bug 复现技能

5.1 代码审查技能的设计思路

代码审查比 PR 描述复杂得多，难点在于“审查标准”很难用几句话讲清楚。所以技能设计时，要把检查点拆细、拆明确。

我的设计思路是：先定义审查范围，再定义检查维度，最后定义输出格式。审查范围解决“看哪里”，检查维度解决“看什么”，输出格式解决“怎么呈现”。

在.claude/skills/code-review/目录下，我们可以先写一个检查清单文件review-checklist.md：

# 代码审查检查清单 ## 正确性 - 是否存在空指针或未判空逻辑 - 是否存在并发问题 - 资源是否正常释放 ## 安全性 - 是否存在 SQL 注入风险 - 是否存在越权访问 - 敏感信息是否硬编码 ## 可维护性 - 命名是否清晰 - 是否存在重复代码 - 函数是否过长，是否需要拆解 ## 测试 - 核心逻辑是否有单测覆盖 - 边界条件是否被测试

然后SKILL.md负责定义流程和输出格式：

--- name: code-review description: 当用户要求审查代码、检查 PR 质量、寻找潜在 Bug 或安全风险时使用。 --- # Code Review 1. 获取审查对象： - 如果用户指定了文件，则只审查这些文件。 - 如果关联 PR，则审查当前分支与目标分支的差异。 2. 阅读代码并对照 `review-checklist.md` 逐项检查。 3. 注意事项： - 只报告问题，不直接修改代码，除非用户明确要求。 - 每个问题必须给出文件路径和行号引用。 - 按严重程度分级：严重问题、一般问题、建议。 4. 输出格式： ## 审查结论 - 通过 / 需要修改 ## 问题列表 ### 严重问题 - 文件路径:行号 问题描述 修复建议 ### 一般问题 - ... ### 建议 - ... ## 总结 对整体代码质量给出简短评价。

这个技能的输出比直接让 Agent “帮我 review 一下”要专业得多，因为它把严重程度、行号、修复建议全部结构化。团队评审时可以直接复制到评论里，沟通成本明显降低。

5.2 Bug 复现技能

另一个高频场景是“写复现步骤”。很多开发者在让 Agent 帮忙分析 Bug 时，得到的答案往往是“可能是 XX 原因”，缺少验证过程。Bug 复现技能的核心是让 Agent 在给出结论前，先还原问题现场。

SKILL.md的核心内容可以是这样的：

--- name: reproduce-bug description: 当用户报告一个缺陷、Bug、异常报错，需要定位原因或生成最小复现示例时使用。 --- # Reproduce Bug 1. 收集信息： - 获取完整的报错堆栈。 - 获取触发场景描述、输入数据、环境信息。 - 如果信息不足，向用户列出需要补充的内容，不要猜测。 2. 尝试复现： - 根据描述构造最小输入。 - 在本地运行相关测试或脚本。 - 禁止在未授权的情况下操作生产环境。 3. 定位范围： - 使用二分法缩小问题范围。 - 对比正常分支与异常分支的差异。 4. 输出要求： - 给出复现步骤。 - 给出根因分析，标注证据来源。 - 给出修复建议，但不直接修改代码（除非用户要求）。

这里特别强调“不要猜测”和“禁止操作生产环境”，是对 Agent 行为边界的重要约束。实际使用中，这条技能能明显减少“看似合理但完全跑不通”的结论。

5.3 技能的组合使用

单个技能解决单个任务，但这些技能组合起来，就能覆盖一个完整的研发闭环。比如：

开发完成，用write-pr生成 PR 描述。
PR 提交后，用code-review自查代码质量。
CI 报错，用reproduce-bug定位问题。

你可以在SKILL.md中显式声明可以引用其他技能。这样 Agent 在生成 PR 时，如果发现测试缺失，可以主动调用代码审查的检查项来补充提示。技能之间形成协作关系后，整个团队的工作流就被串起来了。

6. 常见问题与排查思路

技能用久了，难免遇到各种异常。这里整理几个高频问题及排查思路。

问题现象	常见原因	解决思路
技能没有被自动触发	`description`描述太模糊，工具无法匹配	重写描述，加入任务关键词和触发条件
技能加载后 Agent 仍然随意发挥	正文步骤不够具体，缺少边界约束	把步骤细化到可执行操作，增加“禁止”清单
输出格式不统一	没有明确输出模板，或模板文件路径未写入技能	在正文中引用模板文件，并严格要求套用
技能目录没生效	目录层级或文件名不符合工具规范	检查是否为`skills/<skill-name>/SKILL.md`结构
Agent 修改了不相关的文件	正文中未声明“只读”边界	明确写出禁止修改的文件范围，要求改动前先列计划
Frontmatter 字段报错	工具版本不支持某些字段	查看对应版本文档，删除不支持的字段

6.1 技能不触发怎么办

先确认目录位置是否正确。很多工具只扫描项目根目录下固定路径的文件夹，放错位置自然不会被加载。其次检查description，建议把任务的动词、对象、场景都写进去，例如“当用户要求审查代码、检查 PR 质量、寻找潜在 Bug 或安全风险时使用”，而不是只写“代码审查”。

6.2 Agent 不遵循技能怎么办

这种情况通常是正文写得像“建议”而不是“命令”。Agent 对模糊措辞有解释空间，建议把步骤换成祈使句，明确使用“必须”“禁止”“只输出”。同时，在技能结尾添加“执行完成前自检”的约束，例如要求 Agent 在回答中附带一份检查结果，能有效提高遵循率。

6.3 多个技能相互干扰怎么办

如果几个技能的description范围有重叠，工具可能会同时加载多个技能，导致执行混乱。解决方案是让每个技能的描述边界尽量独立，并在正文中写明“本技能不处理 XX 场景”。必要时，可以把有冲突的技能合并成一个，用分支条件区分不同子任务。

7. 最佳实践与工程建议

7.1 技能命名与描述规范

技能名使用短横线小写，例如write-pr、code-review，方便在路径中引用。描述要包含触发场景、任务对象和边界条件，这是整个技能文件里性价比最高的一行字。团队可以约定一个描述模板：

当用户<动作>，需要<目标>，或<典型场景>时使用。本技能不处理<排除场景>。

7.2 技能文件的版本管理与评审

技能文件也是代码，应当纳入 Git 管理，走评审流程。建议：

技能文件单独放一个目录，和业务代码隔离。
技能变更通过 Pull Request 提交，由团队内经验丰富的同学评审。
在CHANGELOG中记录技能的主要调整，方便回溯。

同时要注意，技能目录不要提交到每个业务仓库，维护起来会很痛苦。更推荐的做法是维护一个独立的“技能资产仓库”，通过脚本或子模块同步到各个项目。addyosmani/agent-skills的目录结构本身就是很好的参考，你可以直接借鉴它的分类方式。

7.3 安全与权限边界

技能赋予了 Agent 更强的自动化能力，也意味着更高的安全要求。以下几点必须重视：

禁止在生产环境执行变更：技能正文中明确写出“未获得授权不得操作生产环境”。
最小权限原则：技能调用的脚本、命令尽量使用只读能力；需要写入时，必须经过用户确认。
敏感信息隔离：技能模板中不要硬编码密钥、Token、账号信息。必要时使用环境变量引用。
输出审计：涉及数据库或代码变更的技能，要求 Agent 先输出待执行的操作清单，由用户确认后再执行。

7.4 从个人技能到团队技能

个人使用时，技能可以很随意；团队落地时，则需要考虑通用性。建议先从 2 到 3 个高频场景起步，比如 PR 描述、代码审查、Bug 复现，跑通后再逐步扩充。每新增一个技能，都要回答三个问题：

这个任务是否高频？是否值得沉淀？
团队成员能否按这个技能得到一致结果？
技能维护者是谁？更新节奏如何？

回答清楚了，技能库才不会变成一堆没人用的死文件。

8. 总结与学习路线

这篇文章从addyosmani/agent-skills出发，梳理了 Agent Skills 的完整落地路径。核心收获是：技能的本质不是提示词，而是把任务流程、输出标准、行为边界固化成仓库里的资产；一次投入，持续复用。

按照本文的实战案例，你现在已经可以做出三个基础技能：生成 PR 描述、执行代码审查、辅助复现 Bug。建议先从第一个开始，放在自己的项目里跑一周，感受一下 Agent 行为的变化，再逐步扩展到团队。

下一步可以继续学习的方向包括：如何把技能与 CI 流程结合实现自动代码审查、如何在多仓库场景下统一同步技能资产、如何设计基于 Agent 的自动化测试生成流程。这些内容都建立在今天讲的技能结构之上。

如果你准备动手，可以直接把文中示例复制到.claude/skills/目录里试试。如果运行中遇到技能不触发、格式不生效的问题，回到第 6 节的排查表对照处理。希望这份技能化思路能帮你把 AI 编程助手从“偶尔好用”变成“稳定可靠”。

AI Agent技能化设计：从SKILL.md到可复用技能库