agent-skills 实战：为 AI 编程助手注入项目专属技能

1. 从零认识 agent-skills它到底解决什么问题第一次看到agent-skills这个词很多人会以为它又是一个新的 AI 编程工具或者某个大模型厂商推出的新功能。实际上它更像是一套“能力描述规范”或者说“技能包管理机制”专门用来给 AI coding agents 补充它们原本不具备的领域知识和操作流程。你可以把它理解成给一个刚入职的工程师发了一本《团队内部操作手册》手册里写清楚了遇到什么任务该用什么工具、按什么步骤走、有哪些坑不能踩。我最初接触这个概念是在用 Claude Code 做项目重构的时候。当时我反复在对话里粘贴同一套代码规范、同一套目录结构说明、同一套测试命令每次新开一个会话就要重新交代一遍效率极低。后来发现 Claude Code 支持一种叫 skills 的机制可以把这些重复性的上下文固化成文件让 agent 在需要的时候自动加载。这就是 agent-skills 最朴素的价值把“每次都要说”变成“一次写好随时调用”。它适合谁呢如果你只是偶尔用 Cursor 补全几行代码可能感知不强。但如果你每天都要和 Claude Code、Cursor 这类 AI coding agents 打交道经常让它们执行多步骤任务比如“帮我新建一个符合团队规范的 React 组件并补上测试”那 agent-skills 就是把你从重复劳动里捞出来的关键工具。它解决的核心问题是agent 的通用能力和你的项目特定需求之间的鸿沟。注意agent-skills 不是模型本身的能力升级它不会让模型变聪明但它能让模型在你的项目里表现得更“懂行”。这一点想清楚后面很多设计决策就顺了。2. agent-skills 的核心设计思路拆解2.1 为什么需要“技能”这一层抽象AI coding agents 的底层模型是通用的它见过海量代码但没见过你司内部的代码规范、没跑过你们那套特殊的构建脚本、不知道你们数据库迁移必须走哪个审批流程。传统做法是把这些信息塞进系统提示词或者每次对话时手动补充但系统提示词有长度限制手动补充又容易遗漏。agent-skills 的设计思路是把这些“项目特定知识”从对话上下文中抽离出来变成独立的、可版本管理的文件。每个 skill 文件描述一件事什么时候触发、需要哪些输入、执行什么步骤、输出什么结果。Agent 在运行时根据当前任务判断该加载哪个 skill然后按照 skill 里的指示去操作。这样做的好处很明显知识可以复用、可以迭代、可以分享给团队其他人。2.2 技能文件的典型结构虽然不同工具对 skill 的具体格式要求略有差异但核心要素是相通的。一个典型的 skill 定义通常包含以下几个部分名称与描述让 agent 快速判断这个 skill 是干什么的什么场景下该用它。触发条件什么类型的用户请求应该激活这个 skill比如“当用户要求新建组件时”。执行步骤具体的操作流程可以是自然语言描述也可以包含具体的命令、代码模板。输入输出约定需要用户提供什么信息执行完产出什么。注意事项容易出错的地方、必须遵守的约束。我自己的习惯是把每个 skill 写成一个 Markdown 文件放在项目根目录的.agent/skills/下面文件名用动词开头比如create-component.md、run-migration.md。这样一眼就能看出这个 skill 是干什么的。2.3 和传统提示词工程的区别有人会问这不就是提示词工程吗区别在于触发机制和复用粒度。传统提示词是你每次都要主动粘贴或者配置在系统提示里而 agent-skills 是 agent 根据任务自动匹配和加载的。另外提示词通常是针对一次对话的而 skill 是项目级的资产可以跟着代码仓库一起版本控制。团队里一个人写好了 skill其他人 clone 下来就能用这才是它真正有意思的地方。3. 在 Claude Code 和 Cursor 中落地 agent-skills3.1 Claude Code 的 skills 安装与配置Claude Code 对 skills 的支持相对成熟。安装方式通常有两种一种是通过 skills CLI 工具从远程仓库拉取另一种是手动把 skill 文件放到指定目录。我实测下来手动放置更适合项目级定制CLI 安装更适合获取社区维护的通用技能包。手动配置的步骤大致如下在项目根目录创建.claude/skills/目录具体路径以你使用的版本为准建议查阅对应版本文档确认。把写好的 skill Markdown 文件放进去。重启 Claude Code 会话或者在会话中执行重新加载命令。用自然语言触发对应任务观察 agent 是否自动加载了 skill。这里有个细节skill 的命名和描述要足够清晰否则 agent 可能匹配不到。我试过把 skill 命名为component.md结果 agent 经常忽略它改成create-react-component.md并在描述里写清楚“当用户要求新建 React 组件时使用”命中率明显提升。3.2 Cursor 中的技能管理思路Cursor 本身对 skills 的原生支持方式和 Claude Code 不完全一样但思路可以借鉴。在 Cursor 里我通常用.cursorrules文件配合项目内的文档目录来实现类似效果。把通用的代码规范、目录结构说明放在.cursorrules里把具体的操作流程写成独立文档放在docs/agent-skills/下然后在.cursorrules里引用这些文档的路径告诉 Cursor 在特定任务时去读取对应文件。这样做的好处是 Cursor 的每次对话都能感知到项目规范同时具体的操作步骤又不会把.cursorrules撑得太大。实测在 Cursor 里处理多步骤任务时这种分层结构比把所有东西塞进一个文件要稳定得多。3.3 跨工具的技能复用策略如果你同时用 Claude Code 和 Cursor可以把 skill 文件写成工具无关的纯 Markdown放在项目根目录的agent-skills/下。然后在 Claude Code 的配置里指向这个目录在 Cursor 的.cursorrules里也引用这个目录。这样一套 skill 两边都能用维护成本减半。提示不同工具对 skill 文件的解析方式可能有差异建议先用一个简单 skill 在两个工具里分别测试确认都能正确加载后再批量迁移。4. 手把手写一个可复用的 agent-skill4.1 场景选择新建符合规范的组件假设我们团队用 React TypeScript每个新组件必须包含组件文件、样式文件、测试文件、导出索引。手动做这件事要建四个文件、写重复的模板代码、容易漏掉测试。我们写一个 skill 来让 agent 自动完成。4.2 技能文件的具体内容下面是我实际在用的一个 skill 文件内容放在.claude/skills/create-component.md--- name: create-component description: 当用户要求新建 React 组件时使用自动生成组件文件、样式、测试和导出索引 --- # 新建 React 组件 ## 触发条件 用户说“新建组件”“创建一个组件”“add a new component”等。 ## 执行步骤 1. 询问用户组件名称PascalCase和目标目录默认 src/components/。 2. 在目标目录下创建以下文件 - {ComponentName}.tsx函数式组件包含 Props 接口定义。 - {ComponentName}.module.cssCSS Module 样式文件。 - {ComponentName}.test.tsx使用 Testing Library 的基础渲染测试。 - index.ts导出组件和 Props 类型。 3. 组件模板使用团队约定的函数声明方式不使用箭头函数。 4. 测试文件必须包含一个“renders without crashing”的用例。 ## 注意事项 - 组件名必须是 PascalCase如果用户给的是 kebab-case 要转换。 - 如果目标目录已存在同名组件先询问用户是否覆盖。 - 样式文件使用 CSS Module不要用内联样式。4.3 触发效果与调整过程写完这个 skill 后我在 Claude Code 里输入“帮我新建一个 UserCard 组件”agent 自动加载了 skill依次创建了四个文件内容也符合模板要求。第一次测试时发现它把组件名写成了user-card原因是我的描述里没有强调 PascalCase 转换。在 skill 的注意事项里补上“如果用户给的是 kebab-case 要转换”之后问题解决。这个迭代过程说明skill 不是一次写完就完事的需要根据实际触发效果反复调整描述和约束。我一般会先写一个粗版跑三五个真实任务把踩到的坑补进注意事项里迭代两三轮就稳定了。5. 常见问题与排查技巧实录5.1 技能不触发怎么办这是最常见的问题。排查顺序建议如下排查项检查方法常见原因文件路径确认 skill 文件在工具要求的目录下路径写错或目录层级不对文件格式检查 frontmatter 是否完整缺少 name 或 description描述匹配看 description 是否覆盖了用户的表达方式描述太窄用户换种说法就匹配不到工具版本确认当前版本支持 skills 功能旧版本可能不支持或语法不同会话状态尝试重启会话或重新加载skill 文件修改后未重新加载我遇到最多的情况是描述太窄。比如 description 里只写了“新建组件”用户说“创建一个 React 组件”就匹配不到。解决办法是在 description 里多列几种常见表达用逗号隔开。5.2 技能执行结果不符合预期如果 skill 被触发了但结果不对通常是执行步骤写得不够具体。比如我只写了“创建测试文件”agent 可能创建一个空文件或者用错误的测试框架。后来我把测试框架、断言库、必须包含的用例都写清楚结果就稳定了。另一个技巧是在 skill 里加入“输出示例”。比如把期望生成的文件内容片段直接写在 skill 里agent 照着填的概率会高很多。这比纯文字描述有效。5.3 多个技能冲突怎么处理当项目里 skill 多了之后可能出现两个 skill 都觉得自己该触发的情况。比如“新建组件”和“新建页面”两个 skill用户说“新建一个用户页面”两个都可能被匹配。解决办法是在 description 里写清楚边界比如“新建页面”的 description 里注明“仅当用户明确说页面时使用组件请用 create-component”。另外skill 的命名也要有区分度避免语义重叠。注意skill 数量不建议一次性堆太多。我自己的经验是先从三五个高频任务开始用顺了再逐步增加。技能太多反而会让 agent 的选择变得不稳定。6. 把 agent-skills 用出复利效应6.1 团队协作中的技能沉淀一个人写 skill 是个人效率工具一个团队写 skill 就是组织资产。我们团队现在的做法是每个 sprint 结束时大家花十分钟回顾这周期里哪些重复性操作值得写成 skill然后分配给一个人去写写完提交到仓库。下个 sprint 所有人自动受益。这种沉淀方式的关键是降低写 skill 的门槛。不要追求一次写出完美 skill先写一个能用的版本后面根据实际使用反馈迭代。我们内部有个约定任何 skill 只要被触发超过五次就值得优化一次。6.2 技能版本管理与回滚Skill 文件跟代码一样需要版本管理。我建议把 skill 目录纳入 Git 跟踪每次修改写清楚 commit message比如“create-component: 增加 kebab-case 转换逻辑”。这样当某个 skill 改出问题时可以快速回滚到上一个稳定版本。另外如果团队里有人对某个 skill 做了破坏性修改其他人可能不知情。我们的做法是在 skill 文件头部加一个version字段每次修改递增并在团队频道里同步变更。虽然听起来有点重但比出了问题再排查要省事。6.3 从技能到工作流的演进当单个 skill 稳定之后可以尝试把它们串成工作流。比如“新建组件”之后自动触发“运行测试”测试通过后自动触发“提交代码”。Claude Code 支持在一个任务里连续加载多个 skill你只需要在第一个 skill 的末尾写上“完成后建议执行 run-test skill”agent 就会顺着往下走。这种工作流化的用法才是 agent-skills 真正拉开效率差距的地方。单个 skill 省的是几分钟工作流省的是整个任务的协调成本。我现在的项目里从新建文件到提交 MR 的整个流程基本只需要一句“帮我加个 XX 功能”剩下的 agent 会按 skill 链自动完成。最后分享一个我踩过的坑不要试图用 skill 去覆盖所有边缘情况。有些特殊情况就是需要人工判断硬写成 skill 反而会让 agent 在正常场景下也做出奇怪决策。我的原则是高频、步骤明确、容错率高的任务才写成 skill低频或需要复杂判断的任务留给人工。这个边界划清楚了agent-skills 用起来才顺手。