如果你已经用 Claude Code 写过一两周代码大概率会熟悉这个场景每天早上打开终端先噼里啪啦复制一大段“项目背景”给它交代完目录结构、测试框架、改动范围然后才敢把任务抛出去。代码评审要交代一遍写单元测试要交代一遍生成数据库迁移脚本还要交代一遍。这种重复不只是浪费时间更隐蔽的问题是每次交代的上下文很难完全一致漏一个约束答案就从“能用”变成“要改”。这篇文章要聊的“自动技能库”就是用来解决这件事的。它把那些你每次都要重复交代的工作流程固化成一个一个技能文件放到 Claude Code 能识别的目录里让它在恰当的时机自动激活把你从反复手打上下文的泥潭里拉出来。全文会从原理讲到实操用 15 分钟带你接入一整套自动技能激活。适合已经用 Claude Code 但觉得“对话式调教”成本太高的人也适合想在团队里统一 AI 协作动作的人。1. 自动技能库是什么先理解它的激活逻辑技能在这个体系里不是一个魔法插件而是一个有固定结构的文件夹。文件夹里最主要的文件通常叫 SKILL.md用 YAML 头描述触发条件用正文定义执行流程和输出规范。当你在 Claude Code 的对话里提出一个需求它会在当前可用的技能列表里做一次语义匹配匹配到某个技能时就把这个技能里的规则当作后续的行为规范。“自动激活”是这里面最容易误解的概念。它不是定时任务也不是快捷键更不是在面板里手动勾选开关而是模型基于对话内容自己做出的决策。你不需要输一条斜杠命令来启用一个技能只要你的表达命中了技能的触发条件模型就会把技能内容加载进来并按技能内部定义的步骤走。我习惯用一个类比给团队讲这件事技能是菜谱自动激活是厨师根据客人点菜自动选菜谱。客人说“来份辣的、带汤的”厨师不会反问“菜谱第 7 页是什么”他会自己去翻适配的菜谱。Claude Code 的技能就是这个逻辑——你描述意图它负责找流程。1.1 技能和普通提示词到底差在哪很多人一开始觉得技能就是把常用的提示词存下来。这话只对了一半。普通提示词是一段文字靠你复制粘贴进会话里技能是一个带元数据的结构化文件靠模型根据条件自己调用。两者的本质差异不在于文字多少而在于“谁来决定何时使用”。维度普通对话提示词技能库存放位置散落在历史记录、笔记文档里固定目录下的 SKILL.md调用方式手动复制粘贴模型按 description 自动调用一致性每次依赖人肉把关天然复用同一份规范可维护性改一处要同步改所有副本只改技能文件全局生效可分享性复制聊天记录直接把技能文件夹丢给团队这也是为什么技能对团队协作的价值更大。一个人手动复制提示词十个人就有十种写法技能库只要维护一份所有人都落到同一套操作标准上差异被压缩到最小。1.2 自动激活的触发机制关键在一个字段自动激活的开关全在 SKILL.md 头部那个 description 字段里。你写的 description 是什么模型就靠它判断什么时候该激活这个技能。这里有一个新手常踩的坑把 description 当成给人看的摘要写得很抽象。比如你写“对代码质量进行分析和评估”这种描述模型确实会在某些时候关联起来但触发率波动极大。因为“代码质量”可能出现在任意对话里它很难精确判断。更稳的写法是把触发时机、常见说法、适用范围、负面排除条件全部塞进 description。第 3 章我会给一个可以直接抄的版本。2. 动手前准备15 分钟倒计时开始前的三件事别急着建文件夹先花两三分钟把环境确认一遍。很多“接入失败”的案例其实第一步就歪了。2.1 确认官方 CLI 可用并且完成过一次会话Claude Code 的载体是命令行工具你得先保证在终端里能正常跑起来并且已经用账号完成过一次认证。判断标准很简单在任意一个空目录下执行这条命令能正常进入对话界面。claude如果能跑起来并且你发一句“你好”它正常回应说明环境就绪。如果连这一步都不稳后面聊再多技能接入也没意义。另外顺手确认一下版本太老的内核会对技能自动匹配的准确率有影响。claude --version版本确认这件事我建议写进团队的新人上手文档里。很多时候大家用的是同一套技能库但反馈结果五花八门最后查下来只是个别成员本地版本落后太多。2.2 决定技能装哪用户级还是项目级技能有两个常见存放位置理解它们的区别是接入的前提。用户级技能目录对所有项目生效适合通用性极强、和具体项目无关的技能比如通用代码评审、提交信息规范。项目级技能目录只对当前项目生效适合和项目技术栈强绑定的技能比如“本项目的数据库迁移流程”“本项目的接口调试规范”。用户级路径一般是~/.claude/skills/项目级路径是你的项目根目录/.claude/skills/我建议的新手策略是宁可在项目级多放也不要在用户级堆一堆全局技能。全局技能多了会有两个问题第一它会在所有项目里都可能被自动激活互相干扰概率变大第二团队协作时你自己机器上的全局技能别人根本没有结果不一致。项目级技能能跟着代码仓库走天然具备可共享性。2.3 先规划三个技能别一上来建几十个技能的粒度会直接影响自动激活准确率。如果你把“帮我写需求文档”和“帮我写接口文档”塞成同一个技能模型每次触发后还要猜你想要哪个效果自然打折。我的建议是起步阶段只做三个身边频率最高、边界最清晰的技能比如代码评审 code-review单元测试生成 unit-test-gen数据库迁移脚本 db-migration这三个覆盖了日常开发里最常重复交代的三类任务。等跑通一遍流程后再逐步扩大技能库的覆盖面。我见过不少人第一步就建了二十多个技能后来一大半都没触发过因为 description 边界糊成一团模型根本不知道该什么时候调用它们。3. 15 分钟接入自动技能激活完整实操下面这 15 分钟我按时间切成几段。你照着做做完基本就能在真实项目里体会到自动激活的效果。3.1 第 1-3 分钟建目录、定命名先进入你的模拟项目根目录建议单独建一个试验文件夹别拿正式项目折腾。然后执行mkdir -p .claude/skills/code-review mkdir -p .claude/skills/unit-test-gen mkdir -p .claude/skills/db-migration技能文件夹的命名规则用小写中划线语义清晰。别用中文别用空格否则在命令行和 Markdown 引用里会有很多额外麻烦。文件夹名尽量不要重名因为技能的使用靠 name 字段作为唯一标识重名会让模型在判断时发生混淆。然后给每个目录初始化一个 SKILL.md 空文件touch .claude/skills/code-review/SKILL.md touch .claude/skills/unit-test-gen/SKILL.md touch .claude/skills/db-migration/SKILL.md到这里三分钟足够。你不用急着想内容下一步才是关键。3.2 第 4-8 分钟写第一份能自动激活的 SKILL.md打开 code-review 的 SKILL.md填入下面的内容。这个版本是“最小可用版”先把自动激活的效果跑出来再做优化。--- name: code_review description: 当用户需要对代码变更进行审查包括提到“代码评审”“帮我看下改动”“review 一下”“检查这个 PR / 分支”等场景时使用该技能。仅适用于代码审查不适用于文档审阅或需求评审。 --- # 代码审查技能 ## 执行步骤 1. 先获取当前分支与目标分支的差异明确本次变更范围。 2. 按变更文件列表逐个审查优先处理公共方法、核心模块和涉及数据操作的文件。 3. 对每个文件做四类检查逻辑正确性、安全性风险、性能隐患、可读性与命名。 4. 汇总为分级问题清单按严重程度从高到低输出。 ## 输出格式 - 致命问题必须修复 - 建议修改重要 - 优化建议非必须 ## 禁止事项 - 不要在没有拿到 diff 的情况下直接给结论。 - 不要一次性输出超过 20 条问题优先聚焦前 10 条。这个文件里最关键的部分就是头部两行 YAML。name 是技能的唯一标识description 是自动激活的判断依据。正文部分我建议用“执行步骤 输出格式 禁止事项”的结构。模型读到这种结构后只要激活该技能就会严格按步骤走而不是天马行空自由发挥。3.3 第 9-12 分钟把 description 优化到能稳定触发如果你只用上面的版本大概率能触发但偶尔也会沉默。想要更稳就得把 description 写成“给模型看的精确触发器”。我给自己总结过一个公式description 触发时机 适用场景 负面排除拆开讲触发时机是用户可能怎么问把常见说法全列进去适用场景是这个技能在什么情况下生效负面排除是明确什么时候不激活它避免误触。下面这版我优化过参考价值比上一版高很多--- name: code_review description: 当用户要求审查程序代码、评估代码质量、检查分支或合并请求中的变更时使用。常见说法包括“代码评审”“帮我看下改动”“review 一下”“检查这个 PR”“这个分支有没有问题”。仅用于代码审查不用于文档审查、需求评审、架构方案评审。 ---注意这里塞了很多看似重复的说法因为不同人的口语习惯不一样。你说“review 一下”、他说“帮我看下”、还有人说“检查 PR”这些都应该映射到同一个技能。“仅用于 / 不用于”这两句极其重要等于给模型划了边界能明显降低误触发率。3.4 第 13-15 分钟验证自动激活是否生效现在做最关键的一步实测。在项目目录下启动 Claude Code然后故意用一句口语化的表达去触发帮我 review 一下当前分支的改动我准备合并了。如果技能自动激活了你会看到回复节奏明显变化。它不会一上来就泛泛而谈而是先执行第一步“获取差异”再按“输出格式”组织结果。比如它会先确认目标分支或者直接说“我先看看变更范围”之后才会给审查意见。如果没有触发也别灰心。这时可以在会话里直接追问一句你为什么没有使用 code-review 技能这是一个非常有价值的调试手段。Claude Code 的对话式调试能力很强它会告诉你它认为哪个技能更匹配或者直接说没找到匹配项。根据它的回答再去调整 description 就好。我调试技能时七八成的修改方向都来自这种直接追问。3.5 顺手再做第二个技能单元测试生成一个技能没法覆盖完整工作流。这个阶段再补一个常用的 unit-test-gen 技能你会更快理解技能之间的差异化设计。--- name: unit_test_gen description: 当用户要求为函数、模块或服务生成单元测试提到“写单测”“补测试”“单元测试”“测试覆盖不够”时使用该技能。仅用于单元测试代码生成不用于端到端测试或手动测试计划。 --- # 单元测试生成技能 ## 前置步骤 1. 获取目标函数或模块的输入输出逻辑。 2. 确认当前测试框架和目录规范。 3. 划分测试用例核心路径、边界条件、异常分支。 ## 输出要求 - 为每个测试用例写明场景说明。 - 测试命名与项目现有风格保持一致。 - 不修改被测代码的行为逻辑。这个技能和 code-review 的不同点在于它的产出是“新代码”而不是“结论”。所以正文里的重心落在前置输入和输出要求上。你可以试试在同一段对话里先问代码评审再问补单测观察它是否分别激活对应技能。3.6 日常维护自动激活的几个小习惯跑通 15 分钟后你还要养成几个习惯否则技能库很快会“长草”。第一个习惯是把每次“应该触发但没触发”的对话记录下来反向修改 description。我会建一个简单的记录清单每周花十分钟过一遍把漏掉的用户说法补进触发列表。第二个习惯是在新场景里刻意做自然表达测试。不要每次都用“开始代码评审”这种标准说法去试要模拟真人口语比如“这堆改动看起来有点乱你给看看”。这类表达才是自动激活真正要面对的主战场。第三个习惯是定期检查技能正文里有没有过时信息。比如项目换了测试框架unit-test-gen 里还在写旧框架的目录结构技能照样激活但产出的东西已经不合时宜。4. 把技能库做成可复用体系结构设计、资源与版本控制很多人在做完一个技能后就不再扩展等真正要扩大技能库时才发现之前的结构一团乱。我建议前期花点时间把结构理清晰。4.1 三类典型技能及核心写法技能之间没有强制分类但我建议你在设计时区分三类因为它们的写法差别很大。类型典型技能核心写法诊断型代码评审、缺陷分析、日志排查先收集信息再检查最后输出分级问题生成型单测生成、API 客户端生成、脚手架生成先定输入再定模板最后输出代码文件规范型提交信息规范、文档结构、代码风格明确“必须 / 禁止”给出正反例诊断型技能的关键是“先看后判断”生成型技能的关键是“模板先行”规范型技能的关键是“负面清单”。你把技能写成对应形态激活后的表现就会自然得多。反例我也见过不少一个生成型技能里全是分析思路没有输出模板结果每次生成的东西格式都飘。4.2 多技能之间的边界与优先级技能多了以后最头疼的是互相干扰。比如你既有一个 code-review 技能又有一个 security-check 技能用户说“帮我检查一下这段代码”两个技能可能都觉得自己该上场。我处理这个问题的原则有两个。第一个原则每个技能的 description 都必须写“不适用哪些场景”这是硬约束第二个原则真的无法避免重叠时在更垂直的那个技能里写明“当用户提到某关键词时优先使用本技能”。实际效果是模型读到描述时的判断空间变小了激活率的稳定性反而变高。边界写得越清楚模型越不容易二选一。4.3 资源文件与模板的组织方式SKILL.md 不一定只能孤零零一个文件。技能目录里可以放模板、参考代码、检查清单。比如 unit-test-gen 技能完全可以在同目录放一个 test-template.js在 SKILL.md 正文里写“生成测试时优先参考 test-template.js”。.claude/skills/unit-test-gen/ ├── SKILL.md ├── test-template.js └── examples/ └── example.test.js这样做的收益是技能正文保持精简复杂细节塞进资源文件。模型激活技能时它读入口文件就能了解该在什么时候翻哪个参考整体效率会好很多。如果你把模板全部堆在 SKILL.md 里技能一长模型反而抓不住重点。4.4 用版本库管理技能变更技能不是一次性产物它会随着项目演进不断被修改。我把技能库当作代码来管理每个技能的改动都相当于一次小的需求变更值得留下记录。对项目级技能直接提交进项目仓库常规代码评审流程即可覆盖对用户级技能我放在一个独立的配置仓库里统一管理换电脑时拉下来就能恢复。这样做的最大好处是可以追踪某次修改背后的原因。比如某个 description 里突然多了一句触发词下次看到 diff 时你就知道是为了覆盖哪次漏触发而加的。5. 避坑记录自动技能激活的典型故障与排查这个部分是我踩坑最多的地方直接给你一张按症状排查的地图。5.1 技能完全没有触发按顺序查三个点第一眼看到技能没生效别急着重写 description先检查位置。技能必须放在.claude/skills/目录下如果你用的是用户级技能要放进~/.claude/skills/如果是项目级技能得放项目根目录的.claude/skills/。位置错了它根本不会被发现再好的内容也没有意义。第二查 frontmatter 是否合法。YAML 头必须严格用---包裹字段名写 name 和 description别手滑拼错。我犯过一个很简单的错把 description 写成 desc结果整个技能静默失效排查了十分钟才发现是键名不对。第三查描述质量。如果前面两项都没问题那大概率是描述内容太抽象没有覆盖用户可能的表达方式。按第 3 章的公式重写一遍补上常见说法和负面排除通常都能救回来。5.2 技能触发了但输出完全不合预期技能触发却不按套路出牌问题多半出在正文。最常见的情况有三种正文只有一句话比如“对代码进行审查”这种没有分步流程模型只能自由发挥步骤写得含糊比如只写“检查质量问题”但质量的定义、检查哪几类完全没说还有缺少输出格式模型不知道该用哪种结构交作业。解决方案就是给正文补上“执行步骤 输出格式 禁止事项”三件套。禁止事项尤其容易被忽略但它决定了约束力。比如在 code-review 里写明“不要在没有拿到 diff 的情况下直接给结论”模型就真的会先拿 diff 再说话。5.3 多个技能同时被判定可匹配时怎么办技能互相干扰的表现不是系统弹窗让你选而是模型自己二选一但它选的未必是你期望的那个。我曾经在一个项目里同时维护“接口客户端生成”和“接口测试生成”两个技能描述里都提到了“接口”结果用户说“帮我把这个接口调通”时模型选择了一个生成了一堆客户端代码但用户真正想要的是测试。我的解法还是把边界写透。在一个技能的 description 里明确加一句“生成调用接口的客户端代码测试接口功能、编写接口测试用例请使用另一个技能”。这句看似是给人看的注释实际是对模型的强指引能把冲突场景直接指向正确技能避免互相抢活。5.4 团队协作里技能不一致的坑团队用技能最大的坑是每个人把自己调试好的技能放在用户级目录但项目仓库里什么都没有。结果是团队里某一个人的机器上技能好端端的另一个人打开同一个项目却完全找不到技能。解决规则很简单凡是和项目相关的技能一律放进项目级.claude/skills/并提交进版本库用户级技能只放那种无论做什么项目都想保持同样习惯的通用规则而且数量要严格控制。我把自己的用户级技能常年控制在三个以内其余全部放到项目里管理这样不同机器、不同成员之间的表现才稳定。5.5 会话上下文也会影响激活判断还有一个容易被忽视的因素会话前面的聊天内容。如果一段对话一直在聊文档结构、需求描述这类纯文本话题突然插入一句“检查下这段代码”模型可能会因为上下文惯性而忽略技能触发或者直到你再次强调才反应过来。处理办法有两个一是重要任务在会话开始时就提出不要夹在一堆无关内容中间二是如果发现没触发直接说技能名让模型强制对齐。我把“直接说技能名”当成杀手锏它不算手动禁用自动激活而是作为一种人工兜底机制。6. 进阶玩法从单技能激活到轻量自动工作流最后说点更进阶的也是我把技能库用出价值的关键动作。6.1 让技能之间互相衔接一条流水线就出来了技能正文里不只能规定自己的流程还能把任务导向其他技能。比如我在 code-review 技能里写了一条“如果发现异常处理缺失调用 security-check 技能做深入分析。”这样模型在做代码评审时中途发现安全问题就会自动加载 security-check按那个技能的标准补一轮专项审查。实际效果是一个技能激活后可能跟上另一个技能形成一条轻量工作流整个过程不需要额外操作。我在处理数据迁移任务时也用了这个技巧让 db-migration 技能在写完脚本后自动交给 code-review 技能做二次审查等于把一个人工环节压缩了。6.2 CLAUDE.md 和技能的关系别搞重复如果你已经在用 CLAUDE.md 存项目规范请记住一个原则CLAUDE.md 管项目常量技能管动作流程。数据库连接方式、目录结构、第三方服务的账号约定这些放 CLAUDE.md如何做一次评审、如何生成迁移脚本这些放技能。我见过有人把技能里的步骤复制到 CLAUDE.md结果模型激活技能后反而出现两套指令打架。技能一旦激活它应该是该任务的操作规范不需要再在项目说明文件里出现一份平行版本。重复的信息不仅浪费上下文还会制造矛盾源。6.3 我实际维护的技能库分层结构分享一个我目前在用的划分方式供你参考。层级内容用户级提交信息规范、通用代码评审、版本号变更规则项目 A 级单测生成、数据库迁移、API 契约检查项目 B 级数据管道调试、文档生成、依赖升级检查这个结构的好处是通用规则在个人所有项目里保持一致项目特有规则不会泄露到其他项目。切项目时自动激活表现一直很稳定很少出现“上个项目的技能跑出来管这个项目的事”这种状况。最后再说几句个人体会。技能库这个东西最容易被低估的是 description 的打磨成本。我刚开始接入时以为写完 SKILL.md 就结束了结果用了两周几乎每周都在改某个技能的 description因为总会碰到一种它没覆盖到的表达方式。后来我学乖了不再凭感觉写而是把实际对话里那些触发成功的、没触发成功的句子都攒下来反向修 description。这个笨办法比任何通用模板都管用。自动激活的体验是要养出来的。它不是装一次就能一劳永逸但只要你愿意花几次调试让它真正咬合住自己的工作习惯后面每次打开终端都会顺畅很多。先跑通 15 分钟的最小闭环再慢慢迭代比一开始就规划一个巨大技能库靠谱得多。
