1. 从零认识 agent-skills它到底解决了什么问题第一次看到agent-skills这个词很多人会以为是某个新出的 AI 模型或者插件市场。其实不是。它更像是一套给 AI coding agent 准备的“技能包规范”——你可以把它理解成给 AI 编程助手写的“操作手册 工具集”让 Claude Code、Cursor 这类工具在特定任务上表现得更专业、更稳定。我最初接触这个概念是在用 Claude Code 做项目重构的时候。当时遇到一个很典型的问题每次让 AI 帮我写数据库迁移脚本它生成的代码风格都不一样有时候用 Alembic有时候直接手写 SQL字段命名也飘忽不定。后来我发现与其每次在对话里重复交代规则不如把这些规则固化成一个 skill让 agent 在需要的时候自动加载。这就是 agent-skills 的核心价值——把重复的指令变成可复用的能力模块。具体来说agent-skills 通常包含几个要素一个描述文件告诉 agent 这个技能是干什么的、什么时候用、若干提示词模板、可能还有配套的脚本或工具定义。当你在 Claude Code 或 Cursor 里触发某个场景时agent 会读取对应的 skill按照预定义的流程执行。这比每次手动写一大段 prompt 要高效得多也更不容易出错。适合谁来用如果你只是偶尔让 AI 帮你写个函数那可能用不上。但如果你每天都要和 AI coding agent 打交道项目里有大量重复性的编码任务——比如写测试、做代码审查、生成 API 文档、处理数据清洗——那 agent-skills 能帮你省下大量重复沟通的时间。尤其是团队协作场景把 skill 文件提交到仓库里所有人用的都是同一套规范输出质量会稳定很多。提示agent-skills 不是某个特定产品的专属功能不同工具对它的支持方式不一样。Claude Code 有自己的一套 skill 加载机制Cursor 则更多依赖 rules 和自定义指令。理解这个差异很重要后面我会详细拆解。2. agent-skills 的核心设计思路与方案选型2.1 为什么需要“技能”这层抽象在没有 skills 概念之前我们是怎么让 AI 编程助手听话的无非几种办法在对话里写长 prompt、在项目根目录放一个配置文件比如.cursorrules或CLAUDE.md、或者用系统级的自定义指令。这些方法都能用但各有各的局限。对话里写 prompt 的问题是不可复用。你今天写了一段很完美的代码审查指令明天开新对话就没了得重新写。配置文件的问题是粒度太粗所有规则堆在一起agent 每次都要全部读一遍既浪费上下文窗口又容易让模型抓不住重点。系统级指令则缺乏项目特异性没法针对不同项目做定制。agent-skills 的思路是把能力拆成独立的模块。每个 skill 有自己的触发条件、自己的提示词、自己的工具依赖。agent 在执行任务时根据当前上下文判断该加载哪个 skill。这样做的好处很明显上下文更干净、规则更聚焦、复用更方便。我打个比方。传统的配置文件就像一本厚厚的员工手册新员工入职要全部读一遍。而 skills 更像是一系列岗位操作卡——你今天是收银员就看收银操作卡明天去仓库就看仓库操作卡。每张卡只讲一件事但讲得很细。2.2 主流工具的 skill 支持现状目前对 agent-skills 支持比较完善的主要是 Claude Code。它的机制是在项目里放一个.claude/skills目录每个 skill 是一个子目录里面包含SKILL.md描述文件和可选的辅助文件。当你在对话中触发相关任务时Claude Code 会自动扫描并加载匹配的 skill。Cursor 这边的情况不太一样。Cursor 本身没有叫“skills”的功能但它有 Rules规则和 Notepads笔记两个机制可以实现类似效果。Rules 可以按文件类型或目录触发Notepads 则可以手动引用。如果你想让 Cursor 也具备“技能”能力通常的做法是把 skill 内容写成 rule 文件放在.cursor/rules目录下。工具技能机制触发方式文件位置Claude CodeSkills自动扫描 语义匹配.claude/skills/CursorRules文件匹配 手动引用.cursor/rules/VS Code 插件自定义指令手动触发因插件而异选哪个方案取决于你的主力工具。如果你主要用 Claude Code那直接上原生 skills 最省事。如果你团队里有人用 Cursor 有人用 Claude Code那可能需要维护两套配置或者写一个转换脚本。我个人的做法是先在 Claude Code 里把 skill 调通然后把核心内容同步成 Cursor 的 rule 文件虽然有点重复劳动但能保证两边行为一致。2.3 一个 skill 的典型结构不管用什么工具一个设计良好的 skill 通常包含这几部分元信息名称、描述、触发关键词。这部分告诉 agent “我是谁、什么时候该用我”。上下文说明这个 skill 适用的场景、前置条件、依赖的工具或库。操作步骤具体的执行流程可以是自然语言描述也可以是伪代码。示例输入输出的样例帮助 agent 理解预期结果。边界条件什么情况下不应该用这个 skill或者需要额外确认。我见过很多人写 skill 只写操作步骤结果 agent 经常在不该用的时候乱用。加上触发条件和边界条件之后准确率会高很多。这就像给函数写文档光写“这个函数做什么”不够还得写“什么时候调用它、什么时候别调用它”。3. 手把手搭建你的第一个 agent-skill3.1 环境准备与目录规划假设你用的是 Claude Code第一步是在项目根目录创建 skills 目录。我习惯把 skill 按功能分类比如coding、review、docs、data几个大类每个类下面放具体的 skill。mkdir -p .claude/skills/coding mkdir -p .claude/skills/review mkdir -p .claude/skills/docs目录结构大概长这样.claude/ skills/ coding/ api-endpoint/ SKILL.md templates/ controller.ts.tpl service.ts.tpl review/ security-check/ SKILL.md docs/ api-doc/ SKILL.md每个 skill 一个目录目录名就是 skill 的标识符。目录里至少有一个SKILL.md其他辅助文件按需添加。我建议把模板文件单独放在templates子目录里这样 skill 描述文件不会太长agent 读起来也轻松。注意目录名尽量用英文小写加连字符避免空格和特殊字符。有些工具对路径处理不够健壮中文目录名偶尔会出问题。3.2 编写 SKILL.md 的关键要素SKILL.md是整个 skill 的核心。我一般按这个结构来写--- name: api-endpoint description: 当需要创建新的 REST API 端点时使用此技能 triggers: - 新建接口 - 创建 API - add endpoint --- ## 适用场景 - 在现有 Controller 中添加新的路由方法 - 需要同时生成 Controller、Service、DTO 三层代码 - 项目使用 NestJS 框架 ## 前置条件 - 确认目标模块已存在 - 确认数据库实体已定义 ## 执行步骤 1. 读取 src/modules/{module}/ 下的现有文件结构 2. 按照 templates/controller.ts.tpl 生成 Controller 方法 3. 按照 templates/service.ts.tpl 生成 Service 方法 4. 在 DTO 目录下创建请求和响应类型定义 5. 更新模块的 index 文件导出 ## 示例 输入在 user 模块下创建 GET /users/:id/profile 接口 输出生成 UserController.getProfile、UserService.getProfile、ProfileResponseDto ## 边界条件 - 如果模块不存在先提示用户创建模块 - 如果接口路径已存在提示冲突并停止这里有几个细节值得展开说。description要写得具体不要写“帮助创建 API”这种模糊描述要写清楚“什么时候用”。triggers是给 agent 做语义匹配用的中英文都写上覆盖不同表达习惯。执行步骤要足够细细到 agent 不需要再做额外推断就能执行。我踩过的一个坑是一开始把步骤写得太抽象比如“生成符合项目规范的代码”。结果 agent 每次生成的“规范”都不一样。后来改成明确引用模板文件输出就稳定了。能用文件引用的地方就不要用自然语言描述这是让 skill 可靠的关键。3.3 触发条件的设计技巧触发条件设计得好不好直接决定 skill 会不会被误触发或漏触发。我的经验是分三层来设计第一层是关键词匹配。在triggers里列出最直接的表达比如“新建接口”“创建 API”“add endpoint”。这层覆盖大部分显式请求。第二层是上下文推断。在description里描述场景让 agent 根据当前对话内容判断。比如用户说“我需要一个获取用户详情的接口”虽然没有直接说“新建接口”但语义上匹配。第三层是排除条件。明确写出什么情况下不该用。比如“如果用户只是询问接口设计建议不要触发此技能”。这层最容易被忽略但恰恰最能减少误触发。我实测下来加上排除条件之后误触发率能降低一半以上。尤其是当你有多个 skill 的时候边界清晰特别重要。3.4 用 CLI 工具管理 skills如果你有多个项目都要用同一套 skills手动复制目录很麻烦。这时候可以用一些 CLI 工具来管理。社区里有几个开源的 skills 管理工具基本思路都是把 skill 仓库集中存放然后通过命令链接到各个项目。# 假设你有一个集中的 skills 仓库 skills link api-endpoint --project ./my-project skills list --project ./my-project skills unlink api-endpoint --project ./my-project这类工具的好处是版本统一。你更新了中央仓库的 skill所有链接的项目都能受益。坏处是增加了依赖如果团队里有人不熟悉这套工具可能会困惑为什么 skill 文件是软链接。我的建议是个人项目直接用目录复制就行简单直接。团队项目如果 skill 数量超过十个再考虑上 CLI 工具。不要为了工具而工具。4. 实战用 agent-skills 优化日常编码流程4.1 场景一自动化代码审查代码审查是 agent-skills 最能发挥价值的场景之一。传统做法是每次让 AI 审查代码都要写一遍审查标准什么命名规范、什么安全漏洞、什么性能问题。写成 skill 之后一句话就能触发完整审查流程。我的security-checkskill 大概长这样--- name: security-check description: 对指定代码文件进行安全审查检查常见漏洞 triggers: - 安全检查 - 审查代码 - security review --- ## 检查项 1. SQL 注入检查是否有字符串拼接 SQL 2. XSS检查用户输入是否直接渲染 3. 权限校验检查接口是否有鉴权中间件 4. 敏感信息检查是否有硬编码密钥 5. 依赖漏洞检查 package.json 中是否有已知漏洞版本 ## 输出格式 按严重程度分级Critical / High / Medium / Low 每个问题附带文件位置、行号、修复建议用的时候直接在 Claude Code 里说“对 src/modules/user 做安全检查”agent 就会加载这个 skill按检查项逐条过一遍。实测下来它能抓到不少人工审查容易漏掉的问题尤其是硬编码密钥和依赖版本这种机械性检查。实操心得审查类 skill 的输出格式一定要固定。我一开始没规定格式agent 有时候写一大段散文有时候列个简单清单读起来很累。后来强制要求按严重程度分级、附带行号和修复建议结果就整齐多了。4.2 场景二统一 API 文档生成团队里写 API 文档最头疼的就是格式不统一。有人用 Swagger 注解有人写 Markdown有人干脆不写。用 skill 把文档生成流程固化下来能省很多沟通成本。我的api-docskill 会做这几件事读取 Controller 文件、提取路由和参数、按照固定模板生成 Markdown 文档、更新文档索引。关键是模板要提前定好放在templates目录里。## 接口名称 **路径**GET /api/v1/users/:id **描述**获取指定用户的详细信息 **请求参数** | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | id | string | 是 | 用户 ID | **响应示例** json { id: 123, name: 张三, email: zhangsanexample.com }错误码错误码说明404用户不存在403无权限访问这个模板一旦定下来agent 生成的文档就完全一致了。新人接手项目时看文档的体验会好很多。 ### 4.3 场景三数据库迁移脚本生成 数据库迁移是另一个高频且容易出错的场景。字段类型选错、索引漏加、回滚脚本没写这些问题我都遇到过。用 skill 把检查清单固化下来能避免大部分低级错误。 我的 db-migration skill 包含这些步骤 1. 读取当前数据库 schema 定义 2. 根据需求生成 up 迁移脚本 3. 自动生成对应的 down 回滚脚本 4. 检查是否需要对大表做分批处理 5. 检查是否添加了必要的索引 6. 输出变更摘要供人工确认 其中第 4 步和第 5 步是关键。很多 agent 生成的迁移脚本功能上没问题但在生产环境大表上执行会锁表很久。skill 里明确要求检查表的数据量级超过阈值就提示分批处理。 python # skill 中附带的检查脚本示例 def check_table_size(table_name, threshold1000000): count get_row_count(table_name) if count threshold: return f警告{table_name} 有 {count} 行数据建议分批迁移 return None这个脚本不是必须的但加上之后 agent 会主动做这个检查而不是等你提醒。4.4 场景四跨工具同步 skill 配置前面提到过Claude Code 和 Cursor 的 skill 机制不一样。如果你两个工具都用维护两套配置很烦。我的做法是写一个简单的转换脚本把 Claude Code 的 skill 转成 Cursor 的 rule 文件。import os import re def convert_skill_to_rule(skill_path, output_dir): with open(os.path.join(skill_path, SKILL.md), r) as f: content f.read() # 提取 frontmatter match re.match(r^---\n(.*?)\n---\n(.*)$, content, re.DOTALL) if not match: return meta, body match.groups() name re.search(rname:\s*(.), meta).group(1).strip() # 生成 Cursor rule 文件 rule_content f--- description: {name} globs: alwaysApply: false --- {body} output_path os.path.join(output_dir, f{name}.mdc) with open(output_path, w) as f: f.write(rule_content)这个脚本很粗糙但够用。核心思路就是把 skill 的正文内容搬到 rule 文件里触发条件靠 Cursor 的 globs 或手动引用来实现。虽然不如 Claude Code 的自动匹配智能但至少内容是一致的。注意Cursor 的 rule 文件格式在不同版本间有过变化从.cursorrules到.cursor/rules/*.mdc。写转换脚本前先确认你用的版本支持哪种格式。5. 常见问题与排查技巧实录5.1 skill 不触发怎么办这是最常见的问题。你写好了 skill但在对话里怎么说明明匹配就是没反应。排查思路按这个顺序来第一步检查文件位置和命名。Claude Code 要求 skill 必须放在.claude/skills/目录下每个 skill 一个子目录子目录里必须有SKILL.md。文件名大小写敏感skill.md和SKILL.md不一样。第二步检查 frontmatter 格式。---必须独占一行前后不能有空格。YAML 语法要正确冒号后面要有空格。我见过有人写name:api-endpoint少了空格导致解析失败。第三步检查触发词覆盖。你用的表达方式可能在triggers里没有对应项。试着换几种说法或者直接在对话里说出 skill 的名称。第四步检查上下文长度。如果当前对话已经很长agent 可能没有足够的上下文窗口来加载 skill。开个新对话试试。第五步检查工具版本。Skills 功能是逐步开放的旧版本可能不支持。确认你的 Claude Code 是最新版。问题现象可能原因解决方法完全无反应文件位置错误确认在.claude/skills/下偶尔触发触发词覆盖不足增加中英文触发词触发但行为不对步骤描述模糊细化执行步骤引用模板文件多个 skill 冲突边界条件不清添加排除条件明确优先级5.2 skill 输出不稳定的处理即使 skill 触发了输出质量也可能飘忽不定。今天生成的代码符合规范明天又跑偏了。这个问题通常出在步骤描述上。我的经验是凡是能用文件引用的就不要用自然语言描述。比如“生成符合项目规范的 Controller”不如直接给一个controller.ts.tpl模板文件让 agent 照着填。模板文件是确定的自然语言描述是有歧义的。另一个技巧是在 skill 里加入验证步骤。比如生成代码后要求 agent 自己检查一遍命名是否符合规范、是否导入了必要的依赖、是否有遗漏的边界处理。这个自检步骤能拦住不少低级错误。还有一个容易被忽略的点是示例的质量。skill 里的示例如果写得太简单agent 会照着简单示例的风格来。示例要覆盖典型场景和边界场景让 agent 有足够的参考。5.3 多 skill 协作时的优先级问题当项目里 skill 多了之后会出现一个任务同时匹配多个 skill 的情况。比如“创建一个带权限校验的用户接口”既匹配api-endpoint又匹配security-check。这时候 agent 该用哪个Claude Code 的处理方式是全部加载然后按顺序执行。但这可能导致冲突比如api-endpoint生成的代码没有权限校验而security-check又要求加上。我的做法是在 skill 里明确声明依赖关系## 依赖 - 本 skill 依赖 security-check 中的权限校验规则 - 生成代码后自动应用 security-check 的检查项这样 agent 就知道要先执行api-endpoint再执行security-check而不是二选一。如果两个 skill 确实有冲突那就需要人工介入明确告诉 agent 用哪个。我一般会在对话里直接说“用 api-endpoint 技能不要用 security-check”这样最直接。5.4 性能与上下文窗口的平衡skill 不是越多越好。每个 skill 都会占用上下文窗口skill 太多会导致 agent 在处理任务时上下文不够用反而降低质量。我的建议是常用 skill 控制在 5 到 8 个。超过这个数量就要考虑合并或分层。比如把多个小的代码生成 skill 合并成一个大的code-genskill内部再分不同模板。另外skill 的描述文件不要写太长。SKILL.md控制在 100 行以内超出的内容放到辅助文件里让 agent 按需读取。这样既能保持 skill 的完整性又不会一次性占用太多上下文。实操心得我习惯在项目根目录放一个SKILLS.md索引文件列出所有可用 skill 及其用途。这样 agent 在不确定用哪个 skill 时可以先读索引再做选择。这个索引文件本身不算 skill但能起到导航作用。5.5 团队协作中的 skill 管理团队里用 skill最大的问题是版本不一致。有人改了 skill 没提交有人本地有未同步的修改导致同样的任务在不同人机器上表现不一样。解决办法很简单把 skill 目录纳入版本控制。.claude/skills/直接提交到 Git 仓库和代码一起管理。修改 skill 走正常的 PR 流程有人 review 之后再合并。这样能保证所有人用的都是同一套 skill。如果 skill 里有敏感信息比如内部 API 地址用环境变量替代不要把敏感信息写死在 skill 文件里。Claude Code 支持在 skill 中引用环境变量具体语法看官方文档。还有一个实践是给 skill 加版本号。在SKILL.md的 frontmatter 里加一个version字段每次修改递增。这样出问题时能快速定位是哪个版本的 skill 导致的。--- name: api-endpoint version: 1.2.0 description: 当需要创建新的 REST API 端点时使用此技能 ---版本号不用太复杂简单的主版本.次版本.修订号就够了。主版本变更表示不兼容的修改次版本表示新增功能修订号表示 bug 修复。6. 进阶玩法让 skill 更智能的几个思路6.1 动态参数与条件分支基础的 skill 是静态的每次执行同样的步骤。但实际场景中不同项目、不同模块的需求可能不一样。这时候可以在 skill 里加入条件分支。比如api-endpointskill 可以根据模块类型选择不同的模板## 执行步骤 1. 判断目标模块类型 - 如果是 user、auth 模块使用 templates/secure-controller.ts.tpl - 如果是 public、health 模块使用 templates/basic-controller.ts.tpl - 其他模块使用默认模板 2. 根据模块类型生成对应代码这样 agent 会根据实际情况做判断而不是一刀切。条件分支不要太多超过三个分支就考虑拆成独立 skill。6.2 与外部工具链集成skill 不仅可以生成代码还可以调用外部工具。比如在代码生成后自动运行 lint、自动执行测试、自动提交 Git。这些操作可以通过 skill 里的脚本调用来实现。## 后置操作 1. 运行 npm run lint -- --fix 自动修复格式问题 2. 运行 npm run test -- --findRelatedTests 执行相关测试 3. 如果测试通过执行 git add 暂存变更这样 agent 就不只是“写代码”而是完成了一个完整的开发闭环。当然自动提交这种操作要谨慎最好加上人工确认步骤。6.3 基于反馈的 skill 迭代skill 不是写完就完了需要根据实际使用效果持续迭代。我习惯在每次 skill 执行后记录一下效果哪些步骤 agent 执行得好哪些步骤经常出问题哪些边界情况没覆盖到。积累一段时间后就能看出 skill 的薄弱环节。比如我发现db-migrationskill 经常忘记生成回滚脚本就在步骤里把回滚脚本的生成提前并且加上强制检查。改完之后这个问题就没再出现过。迭代频率不用太高每个月回顾一次就够了。关键是养成记录的习惯不然用着用着就忘了哪里有问题。6.4 skill 的测试与验证skill 本身也需要测试。我一般用几个固定的测试用例来验证 skill 是否正常工作正常场景标准输入期望输出符合模板边界场景缺少前置条件期望 agent 提示错误冲突场景同时匹配多个 skill期望按优先级执行异常场景输入格式错误期望 agent 优雅处理这些测试用例可以写成文档放在 skill 目录里每次修改 skill 后手动跑一遍。虽然有点原始但比没有测试强。如果团队规模大可以考虑把 skill 测试集成到 CI 流程里自动验证 skill 文件的格式和基本逻辑。7. 我踩过的坑与最终建议说了这么多最后分享几个我实际踩过的坑希望能帮你少走弯路。第一个坑是skill 写得太泛。一开始我写了一个“代码生成”skill想覆盖所有代码生成场景。结果 agent 每次都要在大量规则里找相关的效率很低输出也不稳定。后来拆成api-endpoint、db-migration、component-gen三个独立 skill每个只专注一件事效果好多了。skill 的粒度要细一个 skill 只做一件事。第二个坑是忽略边界条件。有次我写了一个自动修复 lint 错误的 skill没写边界条件。结果 agent 在遇到无法自动修复的错误时直接删掉了相关代码。虽然只是测试环境但也吓出一身冷汗。后来在 skill 里加了明确限制无法修复时停止并报告禁止删除代码。边界条件不是可选项是必选项。第三个坑是skill 文件不纳入版本控制。有段时间我把 skill 放在本地没提交到仓库。换电脑之后发现 skill 全没了只能凭记忆重写。从那以后所有 skill 都提交到 Git和代码同等待遇。skill 是项目资产的一部分必须版本化。第四个坑是过度依赖 skill。有段时间我什么任务都想写成 skill结果维护成本很高很多 skill 用了一两次就再也没碰过。后来我定了个规矩一个任务如果重复三次以上才值得写成 skill。不要为了 skill 而 skill。如果你刚开始接触 agent-skills我的建议是从一个最简单的场景入手比如代码审查或文档生成。先跑通一个 skill感受一下工作流程再逐步扩展。不要一上来就搞一套复杂的 skill 体系那样很容易半途而废。另外多看看社区里别人写的 skill。GitHub 上有不少开源的 skill 仓库虽然质量参差不齐但能给你不少灵感。看到好的设计就借鉴看到不好的就避免这比闭门造车快得多。最后再分享一个小技巧在 skill 的description里加上“当用户说 XXX 时使用”把最常见的触发表达直接写进去。这样 agent 的匹配准确率会明显提升。我试过加上具体触发语句后skill 的命中率从大概六成提升到了九成以上。