1. 为什么装技能这件事值得单独写一篇指南Skills 这个概念在 2025 年下半年开始密集出现在开发者视野里但很多人第一次接触它的时候是懵的——它跟 Prompt 有什么区别跟 MCP 是什么关系为什么有人说它是给 Agent 装外挂有人又说它只是结构化的提示词我自己从最早在 Claude Code 里手动往~/.claude/skills目录丢文件夹到后来在 Cursor 里配置项目级技能中间踩过的坑不算少。最典型的一次是我写了一个自认为很完美的 SKILL.md结果 Agent 死活不触发排查了两个小时才发现是 frontmatter 里的description写得太抽象模型判断当前任务跟这个技能无关。所以这篇东西不是概念科普而是一份实战导向的接入指南。我会先讲清楚 Skills 到底解决了什么问题、它的运行机制是什么然后给出 8 类我认为真正值得装的技能每一类都会说明适用场景和选择理由最后把 Cursor 和 Claude Code 两条接入路径的完整流程拆开讲包括目录结构、SKILL.md 的写法、触发条件调试、以及几个我实际踩过的坑。适合谁看已经在用 Cursor 或 Claude Code、但还没系统用过 Skills 的开发者想给自己团队沉淀一套可复用 Agent 能力的 Tech Lead以及那些看到Agent Skills这个词但一直没搞明白它跟普通 Prompt 差异的人。前置知识要求不高会基本的命令行操作、能看懂 YAML 和 Markdown 就够了。但如果你完全没用过任何 AI 编程工具建议先去把 Cursor 或 Claude Code 跑起来再回来看这篇。2. Skills 的运行机制它到底和 Prompt、MCP 差在哪2.1 一句话说清楚 Skills 的本质Skills 的本质是按需加载的结构化指令包。它不是一个常驻在上下文里的系统提示词而是躺在磁盘上、等 Agent 判断当前任务需要它时才被读进来的一个 Markdown 文件外加可选的脚本和资源。这个按需是关键。你想想如果一个项目里有 30 个技能全部塞进 system prompt那上下文早就爆了而且模型注意力会被稀释反而什么都做不好。Skills 的设计思路是元数据常驻正文按需加载。具体来说Agent 启动时会扫描所有技能目录只读取每个 SKILL.md 的 frontmatter也就是name和description这两个字段把它们拼成一个轻量的技能清单放进上下文。当你的请求进来模型先看这个清单判断哪个技能的描述跟当前任务匹配匹配上了才去读那个技能的完整正文。这就像你办公室里有一排工具箱墙上贴着每个箱子的标签。你不需要记住每个箱子里有什么只需要看标签需要的时候再打开对应的箱子。2.2 Skills 和 Prompt、MCP 的分工很多人把这三个东西混为一谈我用一个表格把它们的分工讲清楚维度PromptMCPSkills本质一次性指令外部工具/数据源协议可复用的结构化指令包加载方式每次对话手动输入常驻连接工具列表进上下文元数据常驻正文按需加载解决的问题单次任务描述让 Agent 能调用外部能力让 Agent 掌握特定领域的做事方法典型场景帮我重构这个函数连接数据库、调用 API按我们团队的规范写 React 组件复用性低每次重写高配置一次长期用高写一次多项目复用打个比方MCP 是给 Agent 装了一双手让它能去够到外部世界Skills 是给 Agent 装了一本操作手册告诉它遇到某类活儿该怎么干Prompt 则是你当场口头交代的一句话。三者不冲突反而经常配合使用。比如一个数据库迁移技能它的正文里可能会指导 Agent 去调用某个 MCP 工具来执行 SQL同时按照技能里定义的检查清单逐步验证。2.3 SKILL.md 的目录结构长什么样一个标准的技能就是一个文件夹里面至少有一个SKILL.md其他文件都是可选的my-skill/ ├── SKILL.md # 必需技能主体 ├── scripts/ # 可选可执行脚本 │ └── validate.py ├── references/ # 可选参考文档 │ └── api-spec.md └── assets/ # 可选模板、图片等资源 └── template.tsxSKILL.md本身分两部分frontmatter 和正文。--- name: react-component-generator description: 按照团队规范生成 React 函数组件包含 TypeScript 类型、样式方案和测试文件。当用户要求创建新的 React 组件时使用。 --- # React 组件生成规范 ## 组件结构 每个组件必须包含以下部分 1. 类型定义Props interface 2. 组件函数本体 3. 默认导出 ## 命名约定 - 组件文件使用 PascalCase - 样式文件使用 kebab-case ...frontmatter 里的description是整个技能最重要的字段因为它决定了 Agent 会不会在正确的时机加载这个技能。写得太宽泛比如帮助写代码会导致误触发写得太窄比如生成带 useMemo 的表格组件会导致该触发时不触发。我的经验是description里要同时包含能力描述和触发场景用当……时使用这样的句式明确边界。上面那个例子里按照团队规范生成 React 函数组件是能力当用户要求创建新的 React 组件时使用是触发条件两者缺一不可。2.4 技能是怎么被选中的理解触发机制对调试非常关键。整个流程大致是这样Agent 启动扫描技能目录把所有技能的namedescription拼成清单放进上下文用户发出请求模型基于请求内容和技能清单判断是否有技能匹配匹配成功则读取该技能的完整 SKILL.md 正文模型按照正文里的指令执行任务第 3 步是黑盒但你可以通过观察 Agent 的行为来反推。如果技能没被触发八成是description的问题如果触发了但执行结果不对那是正文写得不够具体。提示调试技能触发时可以在请求里显式提到技能名比如用 react-component-generator 技能帮我创建一个 Button 组件。如果这样能触发说明技能本身没问题是description的匹配度不够。3. 8 类真正值得装的技能以及每类的选择逻辑市面上的技能五花八门但真正能长期留在你工具箱里的其实不多。我按使用频率 × 价值密度筛出了 8 类每一类都会说清楚它解决什么问题、为什么值得装、以及挑选时该看什么。3.1 代码规范类把团队约定固化下来这是优先级最高的一类。每个团队都有自己的代码规范但规范文档写在那里没人看Code Review 时又反复提同样的问题。把它做成技能Agent 每次生成代码时自动遵守省下的沟通成本非常可观。典型技能包括特定框架的组件生成规范React、Vue、Svelte 各一套API 接口定义规范RESTful 命名、错误码约定、响应结构数据库 Schema 设计规范字段命名、索引策略、迁移文件格式Git commit message 规范Conventional Commits 的团队变体挑选这类技能时重点看它的规范是否具体到可执行。一个合格的规范技能应该告诉你变量名用 camelCase常量用 UPPER_SNAKE_CASE布尔值以 is/has/can 开头而不是泛泛地说遵循良好的命名习惯。3.2 文档生成类让 Agent 替你写那些不想写的文档写文档是开发者的普遍痛点但 Agent 写文档又容易写成流水账。文档生成类技能的价值在于它把好文档长什么样这个隐性知识显性化了。我常用的几个README 生成器按固定结构输出项目简介、快速开始、API 说明、贡献指南避免每次结构都不一样API 文档生成器从代码注释或类型定义提取信息输出 OpenAPI 或 Markdown 格式变更日志生成器读取 git log按 Keep a Changelog 格式归类整理架构决策记录ADR生成器把一次技术选型的背景、选项、决策、后果结构化记录下来这类技能的关键是模板要固定。如果每次生成的文档结构都不同那还不如自己写。所以技能正文里应该包含一个明确的模板骨架Agent 只负责填充内容。3.3 测试编写类覆盖率和可维护性兼顾测试代码的质量往往被忽视但它直接决定了重构时你敢不敢动手。测试编写类技能要做的是让 Agent 生成的测试既覆盖到位又不会因为过度 mock 而变得脆弱。值得装的单元测试生成器针对特定测试框架Jest、Vitest、Pytest按 AAA 模式Arrange-Act-Assert组织集成测试生成器处理数据库、外部服务的测试隔离测试数据工厂生成符合业务约束的测试数据避免硬编码边界条件检查清单提醒 Agent 覆盖空值、极值、并发等容易漏掉的场景这类技能里我最看重的是边界条件清单。因为 Agent 默认生成的测试往往只覆盖 happy path把必须测试空数组、必须测试超长字符串、必须测试并发调用这些写进技能能显著提升测试质量。3.4 重构与迁移类处理那些想想就头疼的活儿重构和迁移是典型的高价值、高重复、易出错的任务特别适合做成技能。框架升级助手比如 React 17 升 18、Vue 2 升 3把破坏性变更和迁移步骤写清楚依赖替换助手比如从 Moment.js 迁到 Day.js从 Axios 迁到 Fetch代码风格迁移比如从 Class 组件迁到 Hooks从 Options API 迁到 Composition API死代码清理识别未使用的导出、未引用的文件这类技能的价值在于步骤化。迁移不是一步到位的需要分阶段验证。技能正文里应该包含明确的阶段划分和每阶段的验证方法而不是让 Agent 一把梭。3.5 调试排查类把排查思路沉淀成清单调试是经验密集型工作老手和新手的差距往往在于知道该往哪看。把排查思路做成技能相当于给 Agent 装了一个老手的直觉。性能问题排查从前端到后端的完整排查链路网络、渲染、内存、CPU、数据库内存泄漏排查针对 Node.js 或浏览器的具体排查步骤构建失败排查常见构建错误的诊断树线上问题应急从告警到定位到止血的标准流程这类技能要写成决策树的形式如果 A 现象检查 B如果 B 正常检查 C。而不是罗列一堆可能的原因让 Agent 自己猜。3.6 数据处理类让 Agent 处理那些琐碎的数据活儿日常开发中总有一些数据处理的小活儿写脚本嫌麻烦手动做又费时间。CSV/JSON 转换器处理格式转换、字段映射、数据清洗SQL 查询生成器按业务需求生成查询包含索引提示数据迁移脚本生成器生成可回滚的数据迁移脚本日志分析助手从日志中提取模式、统计频次、定位异常这类技能的关键是输入输出格式明确。技能正文里要写清楚输入是什么格式、输出是什么格式、中间做了哪些转换避免 Agent 自由发挥。3.7 项目脚手架类新项目不再从零开始每次开新项目都要重复配置一堆东西脚手架类技能能把这个过程压缩到几分钟。项目初始化器按技术栈生成完整的项目骨架目录结构、配置文件、基础依赖CI/CD 配置生成器生成 GitHub Actions、GitLab CI 的配置文件Docker 配置生成器生成 Dockerfile 和 docker-compose.yml环境变量模板生成器根据代码中的引用生成 .env.example这类技能要包含可选项和默认值。比如项目初始化器应该问清楚要不要 TypeScript、要不要 ESLint、要不要测试框架然后按选择生成不同的骨架。3.8 领域知识类把业务规则喂给 Agent这类技能最容易被忽视但价值可能最高。每个项目都有一些只有老员工才知道的业务规则把这些写进技能Agent 就不会再犯那些低级错误。业务术语表解释项目里的领域概念避免 Agent 用错词状态机说明描述业务对象的状态流转规则权限模型说明说清楚角色、权限、资源的对应关系第三方服务集成说明记录对接外部服务时的注意事项和坑这类技能不需要多复杂但一定要准确。业务规则写错了Agent 会一本正经地执行错误逻辑比不写还糟糕。4. 在 Claude Code 里接入 Skills 的完整流程4.1 技能目录的层级与优先级Claude Code 支持多个层级的技能目录优先级从高到低层级路径适用场景项目级project/.claude/skills/项目专属技能随代码库共享用户级~/.claude/skills/个人通用技能跨项目复用插件级通过插件市场安装第三方提供的技能包项目级优先级最高意味着如果同名技能同时存在于项目级和用户级项目级的会覆盖用户级。这个设计很合理项目专属的规范应该压过个人偏好。我的建议是通用技能放用户级项目专属技能放项目级。比如React 组件生成规范如果每个项目都一样就放用户级如果这个项目有特殊的目录结构约定就放项目级。4.2 手动安装一个技能从 GitHub 上拿到一个技能包后安装步骤其实很简单# 假设技能包在 ~/Downloads/my-skill 目录 # 安装到用户级 mkdir -p ~/.claude/skills cp -r ~/Downloads/my-skill ~/.claude/skills/ # 或者安装到项目级 mkdir -p .claude/skills cp -r ~/Downloads/my-skill .claude/skills/复制完之后验证一下目录结构ls -la ~/.claude/skills/my-skill/ # 应该能看到 SKILL.md然后重启 Claude Code或者重新加载会话技能就会被扫描到。注意有些技能包在 GitHub 上是压缩包形式解压后可能多一层目录。确保SKILL.md直接位于技能文件夹的根目录下而不是嵌套在子目录里。我见过有人解压后变成my-skill/my-skill-main/SKILL.md这样是扫描不到的。4.3 验证技能是否被正确加载Claude Code 里没有直接的列出所有技能命令但你可以通过一个技巧验证在对话里问你现在有哪些可用的技能模型会基于上下文里的技能清单回答。如果技能没出现在列表里按这个顺序排查目录路径对不对确认是.claude/skills/而不是.claude/skill/少个 s 是常见错误SKILL.md 位置对不对确认在技能文件夹根目录不是嵌套的frontmatter 格式对不对name和description必须存在YAML 语法不能有错有没有重启技能是启动时扫描的改完要重启4.4 触发测试与调试技能加载成功不代表能正确触发。测试方法是构造一个应该触发该技能的任务看 Agent 的行为是否符合技能里的指令。比如你装了一个API 文档生成器就发一个帮我给这个 controller 生成 API 文档的请求观察 Agent 是否按照技能里定义的模板输出。如果没触发按这个思路调显式点名在请求里直接说用 xxx 技能来做如果这样能触发说明是description匹配度问题改 description把触发场景写得更具体加入用户可能用的关键词检查冲突如果有多个技能描述相似模型可能选错需要把各自的边界写清楚我踩过的一个坑是两个技能都涉及生成测试description都写了生成测试代码结果模型经常选错。后来我把一个改成生成单元测试针对单个函数或类另一个改成生成集成测试针对多个模块的协作问题就解决了。5. 在 Cursor 里接入 Skills 的完整流程5.1 Cursor 对 Skills 的支持方式Cursor 对 Skills 的支持跟 Claude Code 略有不同。它主要通过.cursor/rules/目录来管理类似的能力但新版本也开始支持.cursor/skills/目录来兼容 SKILL.md 格式。如果你用的是较新版本的 Cursor可以直接把 Claude Code 的技能包复制到.cursor/skills/下格式是兼容的。如果版本较老可能需要转换成 Cursor Rules 的格式.mdc文件。两者的核心差异维度Claude Code SkillsCursor Rules文件格式SKILL.md.mdc加载方式按需加载可配置为常驻或按需触发机制基于 description 匹配基于 glob 模式或描述目录位置.claude/skills/.cursor/rules/5.2 项目级技能的配置步骤在 Cursor 里配置项目级技能# 创建技能目录 mkdir -p .cursor/skills # 复制技能包 cp -r ~/Downloads/my-skill .cursor/skills/如果 Cursor 版本不支持 skills 目录就转成 rules 格式。一个.mdc文件长这样--- description: 按照团队规范生成 React 函数组件 globs: [src/components/**/*.tsx] alwaysApply: false --- # React 组件生成规范 正文内容跟 SKILL.md 一样globs字段指定了规则生效的文件范围alwaysApply控制是否常驻。对于代码规范类技能我建议用globs限定范围 alwaysApply: false这样只在编辑相关文件时才加载节省上下文。5.3 用户级技能的配置Cursor 的用户级规则放在~/.cursor/rules/下对所有项目生效。适合放那些跨项目通用的规范比如个人偏好的代码风格、常用的调试思路等。配置方式跟项目级一样只是路径不同mkdir -p ~/.cursor/rules cp my-rule.mdc ~/.cursor/rules/5.4 Cursor 里调试技能触发Cursor 的调试比 Claude Code 稍微直观一些因为它会在侧边栏显示当前激活的规则。如果规则没生效检查globs 是否匹配当前文件比如规则限定src/components/**/*.tsx但你在编辑src/utils/helper.ts那规则不会生效alwaysApply 设置如果设为 false 且 globs 没匹配上规则就不会加载规则冲突多条规则同时匹配时Cursor 会全部加载可能产生冲突提示Cursor 的规则调试可以在设置里打开Show Rules in Context这样每次请求时能看到实际加载了哪些规则对排查非常有用。6. 写一个高质量 SKILL.md 的实战要点6.1 description 的写法决定触发率的关键description是技能的门面它要同时回答两个问题这个技能能做什么、什么时候该用它。我总结了一个模板[能力描述][具体产出]。当[触发场景1]、[触发场景2]时使用。举个例子生成符合团队规范的 React 函数组件包含 TypeScript 类型定义、样式文件和单元测试。当用户要求创建新的 React 组件、重构现有组件、或需要组件模板时使用。对比一下反例帮助写 React 代码。后者的问题很明显太宽泛任何跟 React 相关的任务都可能触发导致误加载同时帮助写代码没有说明产出是什么模型无法判断是否匹配。6.2 正文结构从能看懂到能执行正文的目标是让 Agent 读完就知道具体怎么做。我习惯用这个结构概述一两句话说明这个技能的核心目标前置条件执行前需要确认什么比如确认项目使用 TypeScript执行步骤分步骤写清楚每步都有明确的输入输出检查清单完成后要验证哪些点示例给一个完整的输入输出示例其中检查清单是最容易被忽略但最有价值的部分。Agent 执行完任务后会按照检查清单逐项验证能显著降低出错率。6.3 脚本和资源的引用方式如果技能需要执行脚本在正文里明确写出调用方式## 验证步骤 执行以下命令验证生成的组件 bash python scripts/validate.py --component src/components/Button.tsx脚本会检查Props 类型是否完整是否有默认导出测试文件是否存在引用参考文档时用相对路径 markdown 详细的 API 规范见 [references/api-spec.md](references/api-spec.md)。Agent 会按需读取这些文件不需要你手动加载。6.4 我踩过的三个坑坑一description 里用了太多同义词。我一开始写生成/创建/新建 React 组件以为覆盖更多关键词能提高触发率结果反而让模型困惑。后来精简成创建新的 React 组件触发反而更准。坑二正文写成了教程。我第一版 SKILL.md 写了 2000 多字从 React 基础讲到 Hooks 原理。结果 Agent 读完抓不住重点。后来压缩到 500 字以内只保留做什么、怎么做、怎么验证效果好很多。坑三忘了写边界条件。技能里没说明如果项目没用 TypeScript 怎么办Agent 遇到这种情况就自由发挥了。后来我在前置条件里加了一句如果项目未使用 TypeScript先生成 JavaScript 版本并提示用户问题解决。7. 技能组合与进阶玩法7.1 技能之间的协作单个技能的能力有限但多个技能组合起来能完成复杂任务。比如新功能开发这个场景可能涉及project-scaffold技能生成目录结构api-design技能定义接口react-component-generator技能生成前端组件test-generator技能生成测试doc-generator技能生成文档这些技能不需要显式编排Agent 会根据任务进展自动切换。但前提是每个技能的description边界清晰不会互相干扰。7.2 技能的版本管理技能是代码资产应该纳入版本管理。我的做法是项目级技能跟项目代码一起提交到 Git用户级技能单独建一个仓库管理每个技能文件夹里放一个CHANGELOG.md记录变更这样团队协作时技能能随代码库同步更新不会出现你用的技能跟我用的不一样的问题。7.3 从社区获取技能的注意事项社区上的技能包质量参差不齐安装前建议检查SKILL.md 是否完整有没有 frontmatter正文是否具体有没有脚本如果有脚本读一遍确认没有危险操作更新频率长期不更新的技能可能已经过时来源可信度优先选择有明确作者和维护记录的项目注意安装第三方技能前务必通读 SKILL.md 和所有脚本。技能本质上是给 Agent 的指令恶意技能可能诱导 Agent 执行危险操作。这不是危言耸听社区里已经出现过类似案例。7.4 技能的效果评估装了技能之后怎么知道它有没有用我的评估方法是触发率在应该触发的任务里实际触发了几次准确率触发后产出是否符合预期节省时间相比手动做节省了多少时间维护成本技能本身需要多久更新一次如果某个技能触发率低、维护成本高就该考虑删掉或者重写。技能不是越多越好能稳定用起来的才是好技能。8. 一些实战中的零散经验最后分享几个我在实际使用中攒下来的零散经验不成体系但都挺实用。关于目录命名技能文件夹名建议用 kebab-case跟name字段保持一致。我见过有人文件夹叫MySkillname写my-skill虽然能用但容易混淆。关于中文技能SKILL.md 完全可以用中文写Agent 理解没问题。但如果技能要分享给国际团队建议用英文或者中英双语。关于技能粒度一个技能只做一件事。我一开始把生成组件 生成测试 生成文档塞进一个技能结果 Agent 经常只做第一步就停了。拆成三个技能后每个都能完整执行。关于调试日志Claude Code 和 Cursor 都有日志功能调试技能触发问题时打开日志能看到模型实际加载了哪些技能、为什么选择某个技能。这比盲猜高效得多。关于技能更新技能不是写完就完事了。项目规范变了、框架升级了、团队约定调整了技能都要跟着更新。我建议每个季度 review 一次所有技能把过时的删掉或重写。关于分享如果你写了一个好用的技能不妨分享出来。社区里的优质技能越多大家的效率都越高。分享时记得写清楚适用场景和依赖条件方便别人判断是否适合自己。技能这个东西本质上是在把隐性知识显性化。你脑子里那些遇到这种情况应该这么办的经验写成 SKILL.md 之后就变成了 Agent 能复用的能力。这个过程本身也是对自己经验的一次梳理写技能的过程中经常会有原来我是这么想的这种顿悟。从最简单的代码规范技能开始先跑通一个感受一下 Agent 按你的规范干活是什么体验。跑通之后你自然会知道下一个该写什么技能。 Agent Skills 实战指南：从运行机制到 Cursor 与 Claude Code 接入
1. 为什么装技能这件事值得单独写一篇指南Skills 这个概念在 2025 年下半年开始密集出现在开发者视野里但很多人第一次接触它的时候是懵的——它跟 Prompt 有什么区别跟 MCP 是什么关系为什么有人说它是给 Agent 装外挂有人又说它只是结构化的提示词我自己从最早在 Claude Code 里手动往~/.claude/skills目录丢文件夹到后来在 Cursor 里配置项目级技能中间踩过的坑不算少。最典型的一次是我写了一个自认为很完美的 SKILL.md结果 Agent 死活不触发排查了两个小时才发现是 frontmatter 里的description写得太抽象模型判断当前任务跟这个技能无关。所以这篇东西不是概念科普而是一份实战导向的接入指南。我会先讲清楚 Skills 到底解决了什么问题、它的运行机制是什么然后给出 8 类我认为真正值得装的技能每一类都会说明适用场景和选择理由最后把 Cursor 和 Claude Code 两条接入路径的完整流程拆开讲包括目录结构、SKILL.md 的写法、触发条件调试、以及几个我实际踩过的坑。适合谁看已经在用 Cursor 或 Claude Code、但还没系统用过 Skills 的开发者想给自己团队沉淀一套可复用 Agent 能力的 Tech Lead以及那些看到Agent Skills这个词但一直没搞明白它跟普通 Prompt 差异的人。前置知识要求不高会基本的命令行操作、能看懂 YAML 和 Markdown 就够了。但如果你完全没用过任何 AI 编程工具建议先去把 Cursor 或 Claude Code 跑起来再回来看这篇。2. Skills 的运行机制它到底和 Prompt、MCP 差在哪2.1 一句话说清楚 Skills 的本质Skills 的本质是按需加载的结构化指令包。它不是一个常驻在上下文里的系统提示词而是躺在磁盘上、等 Agent 判断当前任务需要它时才被读进来的一个 Markdown 文件外加可选的脚本和资源。这个按需是关键。你想想如果一个项目里有 30 个技能全部塞进 system prompt那上下文早就爆了而且模型注意力会被稀释反而什么都做不好。Skills 的设计思路是元数据常驻正文按需加载。具体来说Agent 启动时会扫描所有技能目录只读取每个 SKILL.md 的 frontmatter也就是name和description这两个字段把它们拼成一个轻量的技能清单放进上下文。当你的请求进来模型先看这个清单判断哪个技能的描述跟当前任务匹配匹配上了才去读那个技能的完整正文。这就像你办公室里有一排工具箱墙上贴着每个箱子的标签。你不需要记住每个箱子里有什么只需要看标签需要的时候再打开对应的箱子。2.2 Skills 和 Prompt、MCP 的分工很多人把这三个东西混为一谈我用一个表格把它们的分工讲清楚维度PromptMCPSkills本质一次性指令外部工具/数据源协议可复用的结构化指令包加载方式每次对话手动输入常驻连接工具列表进上下文元数据常驻正文按需加载解决的问题单次任务描述让 Agent 能调用外部能力让 Agent 掌握特定领域的做事方法典型场景帮我重构这个函数连接数据库、调用 API按我们团队的规范写 React 组件复用性低每次重写高配置一次长期用高写一次多项目复用打个比方MCP 是给 Agent 装了一双手让它能去够到外部世界Skills 是给 Agent 装了一本操作手册告诉它遇到某类活儿该怎么干Prompt 则是你当场口头交代的一句话。三者不冲突反而经常配合使用。比如一个数据库迁移技能它的正文里可能会指导 Agent 去调用某个 MCP 工具来执行 SQL同时按照技能里定义的检查清单逐步验证。2.3 SKILL.md 的目录结构长什么样一个标准的技能就是一个文件夹里面至少有一个SKILL.md其他文件都是可选的my-skill/ ├── SKILL.md # 必需技能主体 ├── scripts/ # 可选可执行脚本 │ └── validate.py ├── references/ # 可选参考文档 │ └── api-spec.md └── assets/ # 可选模板、图片等资源 └── template.tsxSKILL.md本身分两部分frontmatter 和正文。--- name: react-component-generator description: 按照团队规范生成 React 函数组件包含 TypeScript 类型、样式方案和测试文件。当用户要求创建新的 React 组件时使用。 --- # React 组件生成规范 ## 组件结构 每个组件必须包含以下部分 1. 类型定义Props interface 2. 组件函数本体 3. 默认导出 ## 命名约定 - 组件文件使用 PascalCase - 样式文件使用 kebab-case ...frontmatter 里的description是整个技能最重要的字段因为它决定了 Agent 会不会在正确的时机加载这个技能。写得太宽泛比如帮助写代码会导致误触发写得太窄比如生成带 useMemo 的表格组件会导致该触发时不触发。我的经验是description里要同时包含能力描述和触发场景用当……时使用这样的句式明确边界。上面那个例子里按照团队规范生成 React 函数组件是能力当用户要求创建新的 React 组件时使用是触发条件两者缺一不可。2.4 技能是怎么被选中的理解触发机制对调试非常关键。整个流程大致是这样Agent 启动扫描技能目录把所有技能的namedescription拼成清单放进上下文用户发出请求模型基于请求内容和技能清单判断是否有技能匹配匹配成功则读取该技能的完整 SKILL.md 正文模型按照正文里的指令执行任务第 3 步是黑盒但你可以通过观察 Agent 的行为来反推。如果技能没被触发八成是description的问题如果触发了但执行结果不对那是正文写得不够具体。提示调试技能触发时可以在请求里显式提到技能名比如用 react-component-generator 技能帮我创建一个 Button 组件。如果这样能触发说明技能本身没问题是description的匹配度不够。3. 8 类真正值得装的技能以及每类的选择逻辑市面上的技能五花八门但真正能长期留在你工具箱里的其实不多。我按使用频率 × 价值密度筛出了 8 类每一类都会说清楚它解决什么问题、为什么值得装、以及挑选时该看什么。3.1 代码规范类把团队约定固化下来这是优先级最高的一类。每个团队都有自己的代码规范但规范文档写在那里没人看Code Review 时又反复提同样的问题。把它做成技能Agent 每次生成代码时自动遵守省下的沟通成本非常可观。典型技能包括特定框架的组件生成规范React、Vue、Svelte 各一套API 接口定义规范RESTful 命名、错误码约定、响应结构数据库 Schema 设计规范字段命名、索引策略、迁移文件格式Git commit message 规范Conventional Commits 的团队变体挑选这类技能时重点看它的规范是否具体到可执行。一个合格的规范技能应该告诉你变量名用 camelCase常量用 UPPER_SNAKE_CASE布尔值以 is/has/can 开头而不是泛泛地说遵循良好的命名习惯。3.2 文档生成类让 Agent 替你写那些不想写的文档写文档是开发者的普遍痛点但 Agent 写文档又容易写成流水账。文档生成类技能的价值在于它把好文档长什么样这个隐性知识显性化了。我常用的几个README 生成器按固定结构输出项目简介、快速开始、API 说明、贡献指南避免每次结构都不一样API 文档生成器从代码注释或类型定义提取信息输出 OpenAPI 或 Markdown 格式变更日志生成器读取 git log按 Keep a Changelog 格式归类整理架构决策记录ADR生成器把一次技术选型的背景、选项、决策、后果结构化记录下来这类技能的关键是模板要固定。如果每次生成的文档结构都不同那还不如自己写。所以技能正文里应该包含一个明确的模板骨架Agent 只负责填充内容。3.3 测试编写类覆盖率和可维护性兼顾测试代码的质量往往被忽视但它直接决定了重构时你敢不敢动手。测试编写类技能要做的是让 Agent 生成的测试既覆盖到位又不会因为过度 mock 而变得脆弱。值得装的单元测试生成器针对特定测试框架Jest、Vitest、Pytest按 AAA 模式Arrange-Act-Assert组织集成测试生成器处理数据库、外部服务的测试隔离测试数据工厂生成符合业务约束的测试数据避免硬编码边界条件检查清单提醒 Agent 覆盖空值、极值、并发等容易漏掉的场景这类技能里我最看重的是边界条件清单。因为 Agent 默认生成的测试往往只覆盖 happy path把必须测试空数组、必须测试超长字符串、必须测试并发调用这些写进技能能显著提升测试质量。3.4 重构与迁移类处理那些想想就头疼的活儿重构和迁移是典型的高价值、高重复、易出错的任务特别适合做成技能。框架升级助手比如 React 17 升 18、Vue 2 升 3把破坏性变更和迁移步骤写清楚依赖替换助手比如从 Moment.js 迁到 Day.js从 Axios 迁到 Fetch代码风格迁移比如从 Class 组件迁到 Hooks从 Options API 迁到 Composition API死代码清理识别未使用的导出、未引用的文件这类技能的价值在于步骤化。迁移不是一步到位的需要分阶段验证。技能正文里应该包含明确的阶段划分和每阶段的验证方法而不是让 Agent 一把梭。3.5 调试排查类把排查思路沉淀成清单调试是经验密集型工作老手和新手的差距往往在于知道该往哪看。把排查思路做成技能相当于给 Agent 装了一个老手的直觉。性能问题排查从前端到后端的完整排查链路网络、渲染、内存、CPU、数据库内存泄漏排查针对 Node.js 或浏览器的具体排查步骤构建失败排查常见构建错误的诊断树线上问题应急从告警到定位到止血的标准流程这类技能要写成决策树的形式如果 A 现象检查 B如果 B 正常检查 C。而不是罗列一堆可能的原因让 Agent 自己猜。3.6 数据处理类让 Agent 处理那些琐碎的数据活儿日常开发中总有一些数据处理的小活儿写脚本嫌麻烦手动做又费时间。CSV/JSON 转换器处理格式转换、字段映射、数据清洗SQL 查询生成器按业务需求生成查询包含索引提示数据迁移脚本生成器生成可回滚的数据迁移脚本日志分析助手从日志中提取模式、统计频次、定位异常这类技能的关键是输入输出格式明确。技能正文里要写清楚输入是什么格式、输出是什么格式、中间做了哪些转换避免 Agent 自由发挥。3.7 项目脚手架类新项目不再从零开始每次开新项目都要重复配置一堆东西脚手架类技能能把这个过程压缩到几分钟。项目初始化器按技术栈生成完整的项目骨架目录结构、配置文件、基础依赖CI/CD 配置生成器生成 GitHub Actions、GitLab CI 的配置文件Docker 配置生成器生成 Dockerfile 和 docker-compose.yml环境变量模板生成器根据代码中的引用生成 .env.example这类技能要包含可选项和默认值。比如项目初始化器应该问清楚要不要 TypeScript、要不要 ESLint、要不要测试框架然后按选择生成不同的骨架。3.8 领域知识类把业务规则喂给 Agent这类技能最容易被忽视但价值可能最高。每个项目都有一些只有老员工才知道的业务规则把这些写进技能Agent 就不会再犯那些低级错误。业务术语表解释项目里的领域概念避免 Agent 用错词状态机说明描述业务对象的状态流转规则权限模型说明说清楚角色、权限、资源的对应关系第三方服务集成说明记录对接外部服务时的注意事项和坑这类技能不需要多复杂但一定要准确。业务规则写错了Agent 会一本正经地执行错误逻辑比不写还糟糕。4. 在 Claude Code 里接入 Skills 的完整流程4.1 技能目录的层级与优先级Claude Code 支持多个层级的技能目录优先级从高到低层级路径适用场景项目级project/.claude/skills/项目专属技能随代码库共享用户级~/.claude/skills/个人通用技能跨项目复用插件级通过插件市场安装第三方提供的技能包项目级优先级最高意味着如果同名技能同时存在于项目级和用户级项目级的会覆盖用户级。这个设计很合理项目专属的规范应该压过个人偏好。我的建议是通用技能放用户级项目专属技能放项目级。比如React 组件生成规范如果每个项目都一样就放用户级如果这个项目有特殊的目录结构约定就放项目级。4.2 手动安装一个技能从 GitHub 上拿到一个技能包后安装步骤其实很简单# 假设技能包在 ~/Downloads/my-skill 目录 # 安装到用户级 mkdir -p ~/.claude/skills cp -r ~/Downloads/my-skill ~/.claude/skills/ # 或者安装到项目级 mkdir -p .claude/skills cp -r ~/Downloads/my-skill .claude/skills/复制完之后验证一下目录结构ls -la ~/.claude/skills/my-skill/ # 应该能看到 SKILL.md然后重启 Claude Code或者重新加载会话技能就会被扫描到。注意有些技能包在 GitHub 上是压缩包形式解压后可能多一层目录。确保SKILL.md直接位于技能文件夹的根目录下而不是嵌套在子目录里。我见过有人解压后变成my-skill/my-skill-main/SKILL.md这样是扫描不到的。4.3 验证技能是否被正确加载Claude Code 里没有直接的列出所有技能命令但你可以通过一个技巧验证在对话里问你现在有哪些可用的技能模型会基于上下文里的技能清单回答。如果技能没出现在列表里按这个顺序排查目录路径对不对确认是.claude/skills/而不是.claude/skill/少个 s 是常见错误SKILL.md 位置对不对确认在技能文件夹根目录不是嵌套的frontmatter 格式对不对name和description必须存在YAML 语法不能有错有没有重启技能是启动时扫描的改完要重启4.4 触发测试与调试技能加载成功不代表能正确触发。测试方法是构造一个应该触发该技能的任务看 Agent 的行为是否符合技能里的指令。比如你装了一个API 文档生成器就发一个帮我给这个 controller 生成 API 文档的请求观察 Agent 是否按照技能里定义的模板输出。如果没触发按这个思路调显式点名在请求里直接说用 xxx 技能来做如果这样能触发说明是description匹配度问题改 description把触发场景写得更具体加入用户可能用的关键词检查冲突如果有多个技能描述相似模型可能选错需要把各自的边界写清楚我踩过的一个坑是两个技能都涉及生成测试description都写了生成测试代码结果模型经常选错。后来我把一个改成生成单元测试针对单个函数或类另一个改成生成集成测试针对多个模块的协作问题就解决了。5. 在 Cursor 里接入 Skills 的完整流程5.1 Cursor 对 Skills 的支持方式Cursor 对 Skills 的支持跟 Claude Code 略有不同。它主要通过.cursor/rules/目录来管理类似的能力但新版本也开始支持.cursor/skills/目录来兼容 SKILL.md 格式。如果你用的是较新版本的 Cursor可以直接把 Claude Code 的技能包复制到.cursor/skills/下格式是兼容的。如果版本较老可能需要转换成 Cursor Rules 的格式.mdc文件。两者的核心差异维度Claude Code SkillsCursor Rules文件格式SKILL.md.mdc加载方式按需加载可配置为常驻或按需触发机制基于 description 匹配基于 glob 模式或描述目录位置.claude/skills/.cursor/rules/5.2 项目级技能的配置步骤在 Cursor 里配置项目级技能# 创建技能目录 mkdir -p .cursor/skills # 复制技能包 cp -r ~/Downloads/my-skill .cursor/skills/如果 Cursor 版本不支持 skills 目录就转成 rules 格式。一个.mdc文件长这样--- description: 按照团队规范生成 React 函数组件 globs: [src/components/**/*.tsx] alwaysApply: false --- # React 组件生成规范 正文内容跟 SKILL.md 一样globs字段指定了规则生效的文件范围alwaysApply控制是否常驻。对于代码规范类技能我建议用globs限定范围 alwaysApply: false这样只在编辑相关文件时才加载节省上下文。5.3 用户级技能的配置Cursor 的用户级规则放在~/.cursor/rules/下对所有项目生效。适合放那些跨项目通用的规范比如个人偏好的代码风格、常用的调试思路等。配置方式跟项目级一样只是路径不同mkdir -p ~/.cursor/rules cp my-rule.mdc ~/.cursor/rules/5.4 Cursor 里调试技能触发Cursor 的调试比 Claude Code 稍微直观一些因为它会在侧边栏显示当前激活的规则。如果规则没生效检查globs 是否匹配当前文件比如规则限定src/components/**/*.tsx但你在编辑src/utils/helper.ts那规则不会生效alwaysApply 设置如果设为 false 且 globs 没匹配上规则就不会加载规则冲突多条规则同时匹配时Cursor 会全部加载可能产生冲突提示Cursor 的规则调试可以在设置里打开Show Rules in Context这样每次请求时能看到实际加载了哪些规则对排查非常有用。6. 写一个高质量 SKILL.md 的实战要点6.1 description 的写法决定触发率的关键description是技能的门面它要同时回答两个问题这个技能能做什么、什么时候该用它。我总结了一个模板[能力描述][具体产出]。当[触发场景1]、[触发场景2]时使用。举个例子生成符合团队规范的 React 函数组件包含 TypeScript 类型定义、样式文件和单元测试。当用户要求创建新的 React 组件、重构现有组件、或需要组件模板时使用。对比一下反例帮助写 React 代码。后者的问题很明显太宽泛任何跟 React 相关的任务都可能触发导致误加载同时帮助写代码没有说明产出是什么模型无法判断是否匹配。6.2 正文结构从能看懂到能执行正文的目标是让 Agent 读完就知道具体怎么做。我习惯用这个结构概述一两句话说明这个技能的核心目标前置条件执行前需要确认什么比如确认项目使用 TypeScript执行步骤分步骤写清楚每步都有明确的输入输出检查清单完成后要验证哪些点示例给一个完整的输入输出示例其中检查清单是最容易被忽略但最有价值的部分。Agent 执行完任务后会按照检查清单逐项验证能显著降低出错率。6.3 脚本和资源的引用方式如果技能需要执行脚本在正文里明确写出调用方式## 验证步骤 执行以下命令验证生成的组件 bash python scripts/validate.py --component src/components/Button.tsx脚本会检查Props 类型是否完整是否有默认导出测试文件是否存在引用参考文档时用相对路径 markdown 详细的 API 规范见 [references/api-spec.md](references/api-spec.md)。Agent 会按需读取这些文件不需要你手动加载。6.4 我踩过的三个坑坑一description 里用了太多同义词。我一开始写生成/创建/新建 React 组件以为覆盖更多关键词能提高触发率结果反而让模型困惑。后来精简成创建新的 React 组件触发反而更准。坑二正文写成了教程。我第一版 SKILL.md 写了 2000 多字从 React 基础讲到 Hooks 原理。结果 Agent 读完抓不住重点。后来压缩到 500 字以内只保留做什么、怎么做、怎么验证效果好很多。坑三忘了写边界条件。技能里没说明如果项目没用 TypeScript 怎么办Agent 遇到这种情况就自由发挥了。后来我在前置条件里加了一句如果项目未使用 TypeScript先生成 JavaScript 版本并提示用户问题解决。7. 技能组合与进阶玩法7.1 技能之间的协作单个技能的能力有限但多个技能组合起来能完成复杂任务。比如新功能开发这个场景可能涉及project-scaffold技能生成目录结构api-design技能定义接口react-component-generator技能生成前端组件test-generator技能生成测试doc-generator技能生成文档这些技能不需要显式编排Agent 会根据任务进展自动切换。但前提是每个技能的description边界清晰不会互相干扰。7.2 技能的版本管理技能是代码资产应该纳入版本管理。我的做法是项目级技能跟项目代码一起提交到 Git用户级技能单独建一个仓库管理每个技能文件夹里放一个CHANGELOG.md记录变更这样团队协作时技能能随代码库同步更新不会出现你用的技能跟我用的不一样的问题。7.3 从社区获取技能的注意事项社区上的技能包质量参差不齐安装前建议检查SKILL.md 是否完整有没有 frontmatter正文是否具体有没有脚本如果有脚本读一遍确认没有危险操作更新频率长期不更新的技能可能已经过时来源可信度优先选择有明确作者和维护记录的项目注意安装第三方技能前务必通读 SKILL.md 和所有脚本。技能本质上是给 Agent 的指令恶意技能可能诱导 Agent 执行危险操作。这不是危言耸听社区里已经出现过类似案例。7.4 技能的效果评估装了技能之后怎么知道它有没有用我的评估方法是触发率在应该触发的任务里实际触发了几次准确率触发后产出是否符合预期节省时间相比手动做节省了多少时间维护成本技能本身需要多久更新一次如果某个技能触发率低、维护成本高就该考虑删掉或者重写。技能不是越多越好能稳定用起来的才是好技能。8. 一些实战中的零散经验最后分享几个我在实际使用中攒下来的零散经验不成体系但都挺实用。关于目录命名技能文件夹名建议用 kebab-case跟name字段保持一致。我见过有人文件夹叫MySkillname写my-skill虽然能用但容易混淆。关于中文技能SKILL.md 完全可以用中文写Agent 理解没问题。但如果技能要分享给国际团队建议用英文或者中英双语。关于技能粒度一个技能只做一件事。我一开始把生成组件 生成测试 生成文档塞进一个技能结果 Agent 经常只做第一步就停了。拆成三个技能后每个都能完整执行。关于调试日志Claude Code 和 Cursor 都有日志功能调试技能触发问题时打开日志能看到模型实际加载了哪些技能、为什么选择某个技能。这比盲猜高效得多。关于技能更新技能不是写完就完事了。项目规范变了、框架升级了、团队约定调整了技能都要跟着更新。我建议每个季度 review 一次所有技能把过时的删掉或重写。关于分享如果你写了一个好用的技能不妨分享出来。社区里的优质技能越多大家的效率都越高。分享时记得写清楚适用场景和依赖条件方便别人判断是否适合自己。技能这个东西本质上是在把隐性知识显性化。你脑子里那些遇到这种情况应该这么办的经验写成 SKILL.md 之后就变成了 Agent 能复用的能力。这个过程本身也是对自己经验的一次梳理写技能的过程中经常会有原来我是这么想的这种顿悟。从最简单的代码规范技能开始先跑通一个感受一下 Agent 按你的规范干活是什么体验。跑通之后你自然会知道下一个该写什么技能。