1. 从“能跑就行”到“越用越顺手”我为什么开始折腾 Skill刚上手 Claude Code 那阵子我的用法特别朴素打开终端敲一句需求等它吐代码复制粘贴收工。能用吗能用。但用久了总觉得哪里不对劲——每次都要重新交代项目背景每次都要提醒它“这个仓库用 pnpm 不用 npm”每次让它写测试它都按自己的喜好来。我一度以为这就是 AI 编程工具的常态直到我把 Skill 这个概念真正吃透才意识到之前那些重复劳动全是白费。先说清楚 Skill 到底是什么。你可以把它理解成给 Claude Code 预置的“操作手册”或者“岗位说明书”。它不是模型本身的能力而是你在模型外面套的一层行为约束和知识注入。打个比方Claude Code 是一个刚入职的聪明新人脑子好使但不懂你们公司的规矩Skill 就是你递给他的那本《团队开发规范》里面写清楚了代码风格、目录结构、提交信息格式、测试框架选型。没有这本手册他也能干活但干出来的活你得反复返工。我前后给自己的工作流装了大概 40 个 Skill覆盖的范围从代码规范、测试生成、文档撰写到数据库迁移、API 设计审查、甚至提交信息自动生成。装完之后最大的感受不是“功能变多了”而是“我终于不用每次都当复读机了”。这篇文章就把我这段时间踩过的坑、总结出来的方法、以及哪些 Skill 真正值得装一次性讲透。如果你现在还在用最原始的方式跟 Claude Code 对话每次都要手动补上下文那这篇内容大概率能帮你省下大量重复沟通的时间。如果你已经用过几个 Skill 但觉得效果一般那问题很可能出在写法上后面我会专门拆解。2. Skill、CLAUDE.md、MCP、Agent先把这四个概念理清楚很多人一上来就急着装 Skill结果概念没搞明白装了一堆互相打架的配置最后效果还不如不装。我刚开始也是这样所以这一节先把几个最容易混淆的概念掰开讲。2.1 Skill 和 CLAUDE.md 的分工到底在哪CLAUDE.md 是项目级的全局说明文件放在仓库根目录Claude Code 每次启动都会读它。它适合放那些“整个项目通用”的信息项目是干什么的、用什么技术栈、目录结构长什么样、有哪些全局约定。你可以把它当成新人的入职须知。Skill 则更细粒度它是按需触发的。比如你有一个专门用来生成数据库迁移脚本的 Skill只有当你的需求涉及数据库变更时它才会被调用。Skill 的好处是它可以封装一套完整的操作流程包括前置检查、执行步骤、后置验证而不只是一段静态说明。我自己的做法是CLAUDE.md 放“不变的东西”Skill 放“会变的东西和流程性的东西”。比如“这个项目用 TypeScript 严格模式”放 CLAUDE.md“新增一个 API 端点时需要同步更新 OpenAPI 文档、写集成测试、更新 changelog”这种流程封装成 Skill。2.2 MCP 是另一层东西别跟 Skill 混着用MCP 全称是 Model Context Protocol它解决的是“Claude Code 怎么跟外部工具通信”的问题。比如你想让 Claude Code 直接读 Figma 的设计稿、直接操作浏览器做端到端测试、直接查数据库这些都需要通过 MCP Server 来桥接。Skill 和 MCP 的关系是Skill 定义“做什么、怎么做”MCP 提供“用什么工具做”。举个例子你有一个 Skill 叫“根据设计稿生成页面组件”这个 Skill 里会写清楚步骤先用 Figma MCP 拉取设计稿的图层信息然后按项目的组件规范生成代码最后用 Playwright MCP 跑一遍视觉回归。Skill 是流程编排MCP 是能力扩展。我见过有人把 MCP 的配置直接写进 Skill 里结果换个环境就崩了。正确的做法是 MCP 配置放在 Claude Code 的配置文件里Skill 里只引用工具名称不硬编码连接信息。2.3 Agent 和 Skill 不是一回事Agent 是一个更上层的概念它指的是一个能自主规划、自主调用工具、自主完成多步任务的智能体。Skill 是 Agent 可以调用的能力单元。你可以把 Agent 想成一个项目经理Skill 是他手下的各个专员——有人负责写代码有人负责跑测试有人负责写文档。在实际使用中你不需要自己去“创建 Agent”Claude Code 本身就是一个 Agent。你要做的是给它配置好 Skill让它在需要的时候能调用正确的“专员”。概念作用层级触发方式典型内容CLAUDE.md项目全局每次启动自动加载技术栈、目录结构、全局约定Skill任务级按需触发操作流程、检查清单、代码模板MCP工具级配置后常驻外部工具连接、API 桥接Agent编排级自动规划多步任务分解与执行理清这四个概念之后你再去装 Skill 就不会盲目了。你知道每个 Skill 应该放在哪一层跟其他配置怎么配合。3. 40 个 Skill 里真正每天都在用的是这几类装得多不等于用得好。我一开始也是看到什么装什么结果有将近一半的 Skill 一个月都用不上一次。后来我按使用频率重新梳理了一遍发现真正高频的其实就几类。下面按类别说每类挑几个代表性的讲。3.1 代码规范类让输出风格一次到位这类 Skill 解决的是“每次生成的代码风格不一致”的问题。比如你团队用 ESLint 加 Prettier但 Claude Code 默认生成的代码可能不符合你的规则。你可以写一个 Skill在里面明确要求生成代码后必须按项目根目录的 ESLint 配置自检如果有冲突以项目配置为准。我自己的代码规范 Skill 里还加了一条所有新生成的函数必须带 JSDoc 注释参数和返回值都要写清楚。这条规则写进去之后我再也没手动补过注释。具体写法上我建议把规范拆成“硬性规则”和“软性偏好”两部分。硬性规则是必须遵守的比如“不允许使用 any 类型”软性偏好是尽量遵守的比如“优先使用函数式写法”。这样 Claude Code 在执行时知道哪些不能妥协哪些可以灵活处理。3.2 测试生成类从“写完再说”到“写完即测”以前我让 Claude Code 写测试它总是按自己的理解来——有时候用 Jest有时候用 Vitestmock 的方式也每次不一样。后来我写了一个测试 Skill把测试框架、断言库、mock 策略、覆盖率要求全部固定下来。这个 Skill 里最关键的一条是生成测试之前先读一遍被测文件的导出内容确保每个导出函数都有对应的测试用例。这条规则加上之后测试覆盖率肉眼可见地提升了。还有一个细节我要求测试文件的命名必须跟被测文件对应比如userService.ts对应userService.test.ts放在同级目录的__tests__文件夹里。这种一致性看起来是小事但项目大了之后找测试文件会方便很多。3.3 文档与提交信息类把“事后补”变成“顺手做”提交信息格式不统一是我之前的另一个痛点。有时候写“fix bug”有时候写“修复了登录问题”有时候干脆空着。后来我写了一个提交信息 Skill要求每次提交必须遵循 Conventional Commits 格式并且正文里要说明变更的原因而不只是变更的内容。这个 Skill 的效果立竿见影。现在我的提交历史看起来非常规整用工具自动生成 changelog 的时候直接就能用。文档类 Skill 我主要用来生成 API 文档和 README。关键是要在 Skill 里定义好文档模板包括必须包含的章节、每个章节的写作要求、示例代码的格式。模板定好之后生成的文档质量稳定很多。3.4 数据库与迁移类危险操作加一道保险数据库相关的操作是我最谨慎的地方。我写了一个迁移 Skill里面强制要求任何 schema 变更必须先检查现有迁移文件确保没有冲突生成的迁移脚本必须包含回滚逻辑执行迁移之前必须先在测试环境跑一遍。这个 Skill 帮我避免过一次事故。有一次我让 Claude Code 加一个字段它生成的迁移脚本里没有默认值如果直接在生产环境跑会导致现有数据出问题。因为 Skill 里要求了“必须检查现有数据兼容性”它在生成脚本之前先提醒了我这个问题。提示涉及数据库、文件删除、生产环境配置的 Skill一定要加上“执行前确认”的步骤。让 Claude Code 在动手之前先把计划列出来你确认之后再执行。4. 写 Skill 的几个关键决策我踩过的坑和后来改对的写法装 Skill 容易写好 Skill 难。我前前后后重写了大概十几版才慢慢摸到门道。这一节讲几个我认为最关键的决策点。4.1 触发条件要写窄不要写宽我最早写的一个 Skill 叫“代码审查”触发条件写的是“当用户要求审查代码时”。结果这个 Skill 几乎从来不触发因为我很少直接说“审查代码”我通常说的是“帮我看看这段有没有问题”或者“这个函数写得对不对”。后来我把触发条件改成了具体的场景描述比如“当用户粘贴了一段代码并询问质量、问题、改进建议时”。这样触发率一下子就上来了。核心原则是触发条件要描述“用户在什么情境下会需要这个 Skill”而不是“这个 Skill 是干什么的”。前者是场景后者是功能。Claude Code 匹配的是场景不是功能。4.2 步骤要具体到可执行不要写空话我见过很多 Skill 写的是“确保代码质量”“遵循最佳实践”这种话。这种 Skill 装了等于没装因为 Claude Code 不知道具体要做什么。好的 Skill 步骤应该是这样的第一步读取项目根目录的.eslintrc文件第二步对生成的代码逐行检查是否符合规则第三步如果有不符合的地方自动修复并说明修改原因第四步修复后重新检查一遍确保没有遗漏。每一步都有明确的动作和对象。这样 Claude Code 执行起来才不会跑偏。4.3 给输出定格式减少后期整理如果你希望 Skill 的输出能直接被其他工具消费那就在 Skill 里定义好输出格式。比如我有一个 Skill 用来生成 API 变更记录输出格式固定为 JSON字段包括endpoint、method、changeType、description。这样我拿到输出之后可以直接喂给文档生成工具不需要手动整理。格式定义得越明确后期返工越少。我建议至少定义清楚输出的结构是段落、列表还是 JSON、必须包含的字段、字段的命名规范。4.4 版本管理Skill 也要进 Git这一点很多人会忽略。Skill 文件本身也是代码资产应该跟项目一起进版本管理。我现在的做法是在项目根目录建一个.claude/skills文件夹所有 Skill 文件放在里面跟代码一起提交。这样做的好处是团队其他人拉下代码就能用同一套 Skill不需要每个人单独配置Skill 的变更也有历史记录出问题可以回滚新成员入职的时候Skill 本身就是一份很好的操作规范文档。5. 一个完整 Skill 的拆解从需求到落地光讲原则不够直观这一节我拿一个实际在用的 Skill 来拆解把每个部分为什么这么写讲清楚。这个 Skill 的功能是“新增 API 端点时的全流程处理”。5.1 需求分析这个 Skill 要解决什么问题在我们团队新增一个 API 端点不只是写一个路由处理函数那么简单。还需要定义请求和响应的类型、写参数校验逻辑、添加路由注册、写集成测试、更新 OpenAPI 文档、在 changelog 里加一条记录。这些步骤以前全靠人记经常漏掉一两项。这个 Skill 的目标就是把这套流程固化下来让 Claude Code 在接到“新增一个 API 端点”的需求时自动按完整流程执行不遗漏任何一步。5.2 Skill 结构拆解这个 Skill 分为四个部分触发条件、前置检查、执行步骤、后置验证。触发条件写的是“当用户要求新增、添加、创建 API 端点或路由时触发。”这里用了多个近义词是为了提高匹配率。前置检查部分要求 Claude Code 先做三件事确认项目的 API 框架类型Express、Fastify、Koa 等读取现有的路由文件了解注册方式检查是否已存在同名或相似功能的端点。这三步是为了避免重复造轮子和风格不一致。执行步骤按顺序列出了七步定义 TypeScript 类型、写参数校验、实现处理函数、注册路由、写集成测试、更新 OpenAPI 文档、更新 changelog。每一步都注明了参考文件比如“参数校验参考src/validators/目录下的现有写法”。后置验证要求跑一遍测试、跑一遍 lint、确认 OpenAPI 文档能正常生成。如果任何一步失败就停下来报告问题不要继续。5.3 实际效果和迭代过程这个 Skill 上线之后新增端点的平均耗时从原来的四十多分钟降到了十几分钟而且几乎没有再出现过“忘了写测试”或者“忘了更新文档”的情况。迭代过程中我改过两次。第一次是发现它有时候会跳过前置检查直接开始写代码我在触发条件后面加了一句“必须先完成前置检查才能进入执行步骤”。第二次是发现生成的测试用例覆盖不够我在执行步骤里补充了“测试必须覆盖正常流程、参数缺失、参数类型错误三种情况”。注意Skill 不是写完就完了前几次使用一定要盯着输出发现偏差就及时调整。一般迭代两三轮之后就能稳定下来。6. 装完 40 个 Skill 之后我的工作流发生了什么变化说几个最明显的变化。第一是启动成本降低了。以前打开一个新项目我要花十几分钟跟 Claude Code 交代背景、约定规范、说明偏好。现在这些都在 CLAUDE.md 和 Skill 里了打开就能干活。第二是输出一致性提高了。同一个项目里不管我是上午写代码还是半夜写代码生成的代码风格、测试写法、提交信息格式都是一样的。这对团队协作来说价值很大。第三是我对 Claude Code 的信任度提高了。以前它生成的代码我总要逐行检查现在因为有了规范约束和自动验证我只需要关注业务逻辑对不对格式和流程性的东西基本不用操心。第四是知识沉淀下来了。以前很多“怎么做”的经验只在我脑子里新人来了要口传心授。现在这些经验都写进了 Skill 文件变成了可复用的资产。如果让我给刚接触 Claude Code 的人一个建议我会说先别急着装几十个 Skill先把最常用的三五个写好、用顺感受到效率提升之后再逐步扩展。Skill 的价值不在于数量而在于每一个都真正融入了你的工作流。7. 关于 Skill 的几个常见疑问最后集中回答几个我被问得最多的问题。Skill 会不会拖慢 Claude Code 的响应速度会有轻微影响因为每次对话它都要匹配触发条件。但实际体验下来只要 Skill 数量控制在合理范围内我目前 40 个左右延迟几乎感知不到。如果你装了几百个那确实可能变慢这时候要考虑合并或删减。Skill 之间会冲突吗会。如果两个 Skill 的触发条件重叠Claude Code 可能不知道该用哪个。我的做法是定期检查触发条件确保没有语义重复。如果确实需要两个相似的 Skill就在触发条件里写清楚区别比如一个针对前端组件一个针对后端服务。Skill 能不能跨项目复用可以。我把通用的 Skill 放在用户级配置目录里项目特有的放在项目目录里。这样通用规范不用每个项目重复写。写 Skill 需要编程基础吗不需要。Skill 本质上是结构化的自然语言描述你只要能把自己的操作流程写清楚就行。当然如果你懂一点 Markdown 和 YAML 的格式规范写起来会更顺手。Skill 和直接写 prompt 有什么区别直接写 prompt 是一次性的下次还要重新写。Skill 是持久化的写一次之后每次都能自动触发。而且 Skill 可以包含多步流程和条件判断比单次 prompt 能表达的复杂得多。怎么判断一个 Skill 该不该装我的标准是如果某个操作我一周内重复了三次以上就值得写成 Skill。如果一个月都用不到一次那就不值得。Skill 文件应该写多长没有固定标准但我建议控制在 200 到 500 字之间。太短了说不清楚太长了 Claude Code 可能抓不住重点。如果确实需要很长的流程考虑拆成多个 Skill 串联。更新 Skill 之后需要重启 Claude Code 吗大多数情况下不需要它会自动读取最新的 Skill 文件。但如果你改了配置文件层面的东西可能需要重启才能生效。团队协作时 Skill 怎么管理我建议把 Skill 文件跟代码放在同一个仓库里通过 Git 管理。指定一个人负责审核 Skill 的变更避免每个人按自己的喜好改来改去导致风格混乱。Skill 写错了会不会导致严重问题如果 Skill 里包含危险操作比如删除文件、执行数据库迁移确实有可能。所以我在所有涉及危险操作的 Skill 里都加了“执行前确认”步骤让 Claude Code 先把计划列出来我确认之后才执行。这个习惯帮我避免了好几次潜在事故。