首页 / 资讯中心 / 文章详情

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

AI Agent技能化设计:从SKILL.md到可复用技能库 ★ FEATURED ARTICLE
之前在做 AI 编程助手落地时我发现自己反复在“如何让 Agent 稳定地干好一件事”上浪费时间。直接对话时它经常“自由发挥”换个人问结果又不一样后来接触到addyosmani/agent-skills这类技能化思路之后才意识到问题不是模型不够强而是我们缺少一套可复用的“技能资产”。这篇文章就围绕 AI Agent 的技能化设计展开结合addyosmani/agent-skills的思路讲清楚什么是 Agent Skills、技能文件如何组织、怎么写一个可以在 Claude Code、Cursor 等工具中复用的技能以及团队落地时需要注意的坑。不管是刚开始接触 AI 编程助手的同学还是已经在内部推广 AI 编码规范的工程师都可以从中拿到一套可复用的方法。1. 背景与核心概念1.1 什么是 Agent SkillsAgent 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.shAgent 的运行流程大致是这样的用户提出请求。工具根据请求内容结合每个技能的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-reviewdescription描述技能适用的任务场景写得具体一些包含触发关键词和边界条件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.mdAgent 生成描述时直接套用。辅助脚本则可以封装一些 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.mdSKILL.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 编程助手从“偶尔好用”变成“稳定可靠”。
阅读完成 · 觉得有帮助?
咨询建站