如果你把 Claude Code 当成一个能聊天的代码编辑器那 Skills 这个概念很容易被忽略但如果你已经用它写了一阵子代码大概率会遇到那个让人抓狂的悖论它很聪明却总记不住你的规矩。你告诉过它禁止怎么命名、测试必须覆盖哪些场景、提交信息要按照什么格式写结果新开一个会话它又变成了一无所知的通用助手。Claude Code Skills 就是为了解决这个重复教育问题而生的它把一类任务的判断标准、执行步骤、输出格式、禁忌事项打包成一个可以被按需加载的技能模块让 AI 编程助手真正成为你的专属专家。这篇文章我会从文件结构、触发逻辑、实测踩坑、团队化维护几个角度把 Skills 怎么用、怎么写顺手讲透。1. 为什么通用聪明不够用从会话式约束到可复用技能1.1 默认 Claude Code 的项目盲区一个开箱即用的 Claude Code 拥有海量通用编程知识但它在面对你的仓库时本质上是个懂理论、没经验的新员工。它可以写出结构正确的函数却不知道你们的模块边界为什么要这样切它可以补全测试用例却搞不清楚哪些边界条件在你们业务里是致命的。它可以照葫芦画瓢生成注释却不理解代码里那些故意不处理的历史包袱。这里的关键差异在于通用能力来自模型训练阶段而项目专属约束来自运行时。训练阶段积累的是大多数项目的写法不是你这个项目的写法。如果不在每次会话里把这些约束及时提供给模型它就会自动滑回统计意义上的大多数产出最平庸、最缺少项目灵魂的代码。我见过不少朋友抱怨明明刚讲过要按团队规范来过一会儿又忘了——这不是模型笨而是你给的信息根本不在它的持久记忆里。硬靠在对话里补规则是脆弱的会话一长早期指令的权重会快速下降新开会话一切清零多个人共用同一个项目时每个人都得重新教一遍。这些重复劳动本身就是信号这些规则应该被固化下来而不是靠每次输入去唤起。1.2 CLAUDE.md 不是万能筐很多人第一反应是那我把规则都写进 CLAUDE.md 不就行了吗CLAUDE.md 确实是 Claude Code 里最常见的项目上下文文件但它适合放的是始终生效、信息密度高的内容项目简介、技术栈、常用命令、关键架构约束。换句话说它是常驻于模型上下文里的底稿是每一次对话都会看到的东西。问题在于如果你把代码审查标准、提交信息模板、错误码规范、测试步骤、重构注意事项、日志命名全部塞进同一个文件上下文会被大量低频信息占据。模型每次处理任务都要在一堆大多数时候用不到的规则里反复筛选结果反而稀释了真正重要的高频约束甚至可能出现规则之间互相矛盾的情况。它就像一个把所有工具都挂在腰带上的人走两步就要被绊倒一次。所以 CLAUDE.md 和 Skills 的分工应该是常驻文件管你是谁、你的项目长什么样按需技能管遇到什么任务时执行什么流程。后者只在相关任务出现时才被加载不会长时间占用宝贵上下文。这一点就是 Skills 在设计上最值钱的地方。1.3 Skills 的出现把套路变成可装载的模块Skills 的核心思路用一句话就能说清把一类任务的完整套路——触发条件、执行步骤、检查点、输出模板、禁止事项——封装成一个独立模块让模型在遇到匹配任务时再读取并执行。它的本质是程序化的专家经验而不是更多的聊天背景。用一个生活类比你请了一位很懂行的顾问但他每次来都要重新问一遍你的公司规矩。Skills 相当于提前给他一本工作手册他只在遇到相关业务时翻开对应章节。顾问还是那个顾问但手册决定了他到了你的地盘之后到底按照什么标准干活能产出什么样规格的东西。对个人开发者来说Skills 最直接的收益是一次编写多次复用对团队来说它把隐性知识显性化——新成员接手的不是一个充满口头约定的代码库而是一套可以被 AI 自动遵循的技能库。后面我会用一个具体的代码审查 Skill带你一步步从零把它建起来。2. Skill 长什么样目录结构、SKILL.md 与自动触发逻辑2.1 一份 Skill 的最小文件布局我建议把 Skills 当成小项目来管理而不是随手写一个 txt 就完事。常见的实践是在项目根目录下建一个隐藏目录里面每个技能占据一个独立子目录结构大致这样.claude/ └── skills/ ├── code-review/ │ ├── SKILL.md │ └── examples/ │ └── review-output.md ├── commit-message/ │ └── SKILL.md └── security-check/ └── SKILL.md每个技能目录里至少要有一个 SKILL.md这也是 Claude Code 识别技能的关键文件。技能名我建议用短横线连接的小写单词一眼能看出职责范围例如 code-review、commit-message、security-check。examples 这类辅助目录不是强制的但当技能涉及复杂输出格式时放一两份示例文件会显著提高模型模仿的准确度。我在一个内部项目里加入 examples 之后输出格式的稳定性肉眼可见地上升了一个台阶这个细节后面还会专门讲。2.2 frontmatter 里的召唤咒语SKILL.md 的开头通常会有一段元信息我最常用也最看重的是 name 和 description 两个字段。name 是技能的内部标识description 则是决定模型要不要召唤这个技能的核心依据。可以把它理解成一个抽屉上的标签标签写得足够清楚模型才知道什么情况下该拉开这个抽屉标签写得太含糊它就永远不知道该不该用。不同版本的 Claude Code 对字段名的敏感度可能有细微差异但描述必须精确这一点是通用的。我的写法是把描述拆成四要素什么任务、什么场景、要覆盖哪些维度、以什么形式输出。举个例子当用户要求审查代码、检查改动、评估合并请求时使用。按团队规范完成安全检查、可读性检查、测试覆盖检查和性能隐患检查输出结构化问题清单。 这比只写代码审查用要详细得多触发成功率也高得多。2.3 正文组织让 AI 有章可循而不是自由发挥description 负责让技能被找到正文负责让技能被正确执行。我见过很多低质量技能文件正文只有一句话请认真审查代码并给出建议。 这基本等于没写模型只能靠通用理解开展工作和你临时在对话框里说一句审查一下没区别。一份能真正约束行为的 SKILL.md 正文至少应该包含四块使用时机、执行步骤、质量红线、输出模板。使用时机写明哪些话术会触发你执行步骤是一份有序的操作清单让模型从第一步到最后一步不跳步质量红线是绝对不能做的事输出模板则规定最终交付物的结构。正文用 Markdown 的列表和表格来写模型对这种结构化信息的消化速度远快于散文长段。同时一定要控制篇幅一个技能聚焦一件事任务混合太多、文件过长加载后反而让模型顾此失彼。2.4 自动触发的边界描述越窄越容易被正确命中Skills 是按需加载而不是全部常驻这意味着模型在每次任务开始时扮演的角色是一个识别器——它根据用户当前请求和已有描述做匹配。这里最核心的经验是描述里出现的关键词越贴近用户实际会说的话命中率越高覆盖面越广误触发越多。我早期写过一个大而全的工程规范技能描述里放了代码、测试、提交、重构、架构一大堆词。结果用户只是让 Claude 解释一段代码它也会把整个技能加载出来回答里塞进一堆规范说教又啰嗦又跑偏。后来我把这个技能拆成五个小技能每个描述只覆盖一到两类任务误触发率明显下降。别贪多一个技能只回答一个问题才是容易被模型正确调度的核心心法。3. 手写第一个 Skill把代码审查流程固化成标准操作3.1 一个真实的场景设定我用最常见的需求来演示代码审查。假设你在维护一个模拟项目X团队有一套既定的审查标准必须核对安全问题、函数长度是否失控、命名是否自解释、新逻辑有没有对应的边界测试、有没有隐藏的性能隐患输出必须按严重程度分级每条反馈都要带修改建议不允许只说这里不太优雅这种空话。在没有 Skill 的时候每新开一次会话你都得把这些标准重新打字进去。运气好能坚持到对话结束运气差被上下文一冲审查质量就开始飘忽不定。现在我们把这套标准写进一个 code-review 技能里让审查变成一个可复现的固定动作而不是一场每次都要重新布置的即兴演出。3.2 目录与 SKILL.md 落地先建目录再写文件。如果你希望这个技能只作用于当前项目就放在项目内的 .claude/skills 下如果想让个人所有项目都能复用可以放到用户级别的全局技能目录。目录建好之后创建 SKILL.md开头部分我通常写成这样--- name: code-review description: 当用户要求审查代码、review、检查改动、评估合并请求或验收改动质量时激活。按团队规范执行安全检查、可读性检查、测试覆盖检查和性能隐患检查输出分级问题清单及修改建议。 --- # 代码审查技能 ## 使用时机 - 用户说帮我看看这段代码 - 用户要求review 一下改动 - 用户问这个改动能不能合入 ## 执行步骤 1. 先向用户确认审查范围如果已给出具体文件则跳过。 2. 依次执行安全检查、可读性检查、测试覆盖检查、性能隐患检查。 3. 对每个问题判断严重级别并给出可落地的修改建议禁止只指出问题不给方案。 4. 按下方输出模板整理结果。这里描述部分写的触发词我都尽量覆盖用户实际会说的话包括 review、检查改动、验收改动。别小看这一步很多人做出来的技能触发不了八成就是描述和用户真实口吻对不上。3.3 审查清单与输出格式接下来是让这次审查区别于通用 review 的关键——把团队的具体检查项写进去。安全方面重点看输入校验、路径拼接、危险函数的调用点可读性方面检查命名、函数长度、注释是否解释了为什么测试方面确认新增逻辑是否有边界测试性能方面留意循环内的重复查询、不必要的大对象复制。这些条目用列表一条条列清楚模型就会照着执行不会凭印象自由发挥。输出模板我建议固定成统一格式按 P0、P1、P2 三级划分严重程度每条问题包含位置、问题描述、触发场景、修改建议最后附一段未发现问题的说明。固定格式最大的好处是AI 审查结果可以直接粘贴到合并请求评论里不需要人工重排。另外我强烈建议在技能文件里放一个极简示例。模型的模式学习能力很强给它一张足够优秀的答卷它就会照着类似的格式稳定输出。3.4 测试触发与收敛描述写完之后不要急着投入正式项目先做一个最便宜的验证新建一个会话丢一句帮我 review 一下这段代码进去观察它有没有按照技能里的步骤走。如果完全没反应多半是描述里的触发词和你的话术对不上或者文件路径有问题如果技能加载了但输出格式不对那是正文里的模板写得还不够具体需要补充更细致的示例。我平时常用的调法是把用户和团队真实会说的话原样抄进描述里。比如有位同事习惯说看下这段有没有雷那描述里最好就包含看下有没有雷这类话术。description 不是写给搜索引擎看的是写给模型做意图匹配的它需要的是你们团队最自然的表达方式。跑上两三次实测把失配套路一点点填进去一个技能基本就养成了。4. 从个人技能到团队技能库拆分、共享与维护4.1 哪些规则值得固化成 Skill不是所有规范都值得做成技能。我判断的标准很朴素这件事在过去一个月里是否重复出现三次以上规则是否足够稳定是否能被写成清单或有序步骤。如果三项都是肯定的答案就值得技能化如果这件事半年才遇到一次或者判断标准高度依赖人情世故那么写进技能只会让模型左右为难产出一些两头不靠的答案。适合技能化的候选通常集中在这些领域提交信息规范、分支命名规则、测试补齐流程、依赖升级检查、日志标准、错误码登记、安全审计、数据库变更评审。这些规则生命周期长、可判断性强一旦固化成技能AI 输出的稳定性会远超靠临时对话叮嘱。反过来那些天天在变、连团队自己都拿不准的标准不要急着做成技能等规则先稳定下来再动手。4.2 常用技能拆分清单我建议按照职责单一的原则拆分宁可多写几个小技能也别写一个大杂烩。下面是我在某跨平台系统项目里实际保留过的一组技能供参考技能名触发场景核心输出code-review审查代码、验收改动分级问题清单与修改建议commit-message生成或规范提交信息符合团队模板的提交说明test-first新功能补测试计划测试用例清单与边界条件security-check检查敏感信息、危险调用风险点报告refactor-safe重构、调整结构影响面分析与分步计划changelog发布前整理变更日志按模块归类的变更条目这些技能各有侧重但完全可能被同一个大任务连续触发。比如一次重构可能先加载 refactor-safe 做影响面分析再加载 test-first 补测试最后用 commit-message 收尾。它们是流水线上的工位而不是一把什么都能干的万能钥匙。4.3 全局技能与项目技能的放置策略技能放置的位置决定了适用范围。放在当前项目 .claude/skills 下的技能跟仓库走适合项目专属规则比如这个模块的目录约定、这个服务的错误码规范、这堆业务代码的特殊命名惯例。放在用户级全局目录下的技能则对你个人所有项目生效适合通用偏好比如提交信息必须用同一种模板风格、单一函数不能超过 50 行这类放之四海都能用的规则。在团队协作时我强烈建议把项目级技能直接提交进代码仓库。只要放进仓库每个克隆这个项目的人就自动拥有同一套技能库不需要互相发文档不需要新人对着 wiki 抄规则AI 的输出口径也自然统一。唯一要注意的是技能变更要有记录别让某次悄悄修改影响了所有人的 AI 行为那会带来非常隐蔽的回归问题。4.4 Skill 库的版本管理与迭代Skill 本质上也是代码所以也应该纳入版本管理。我见过有团队把技能文件散落在各自的本地路径里一旦某个人调整了格式其他人根本不知道什么时候变的等到出问题时各说各话。把技能库纳入版本管理之后每次改动都有历史记录谁改的、为什么改查看历史记录就能一清二楚。迭代节奏上我的经验是技能在被 AI 误用的时候才是它最佳修改时机。比如发现 code-review 技能总是漏掉某个安全检查就回到 SKILL.md 把这条插进清单发现 commit-message 技能生成的描述和团队习惯不符就调整输出模板。让技能库像代码库一样拥有版本记录它会慢慢积累成团队最值钱的一层隐性文档。5. 实战中的坑Skill 不触发、多技能打架、指令被覆盖的排查链路5.1 Skill 完全没反应先查路径和解析最让人沮丧的情况是技能文件写好了但 Claude Code 跟没看见一样。遇到这种情况我从来不先怀疑模型而是先按排查链路走一遍文件是否真的放在了被扫描的目录下目录名与技能名是否一致文件名是否严格叫 SKILL.md文件首行的 frontmatter 是否被当作普通正文了。我自己就踩过一次坑把文件命名成了 skill.md 而不是 SKILL.md目录扫描规则没匹配上于是静默失败完全没有任何报错。所以排查的第一步永远是核对路径和文件名这是成本最低也最容易忽略的环节。如果路径没问题再看 frontmatter 里是否有格式错误比如冒号后缺空格、字段名写错YAML 解析一旦出问题整个文件都会被跳过。这类问题没有运行时错误提示只能靠核对规范来发现这也是我一直坚持用统一模板生成技能文件的原因。5.2 描述错位导致召之不来路径和格式都没问题技能还是偶尔不被加载那问题大概率出在 description 的文本匹配上。模型靠描述判断是否激活技能如果用户真实说法和描述里的词汇相差太远语义上虽然接近文本匹配仍然可能失败。比如描述里写的是审查代码用户却说看看这段写得怎么样两者语义相近但文字差异很大模型的触发就会不稳定。对策很简单把团队里真实出现的口语化请求原样收进描述。看看这段写得怎么样、这个能不能合入、检查一下最近的改动这类句子看起来不够正式但作为触发词非常有效。我开始系统性地收集这些真实请求并写进描述之后技能的命中率从大约六成一下子提到了接近全覆盖。5.3 多个 Skill 同时抢任务拆分过细的副作用是同一个请求可能同时命中多个技能。比如用户说帮我改一下这段代码并看看测试code-review、test-first、commit-message 可能都被加载进来结果模型在几个规范之间来回摇摆输出反而拧巴。这种情况我的处理方式是在技能定义里加上责任边界。明确写清楚当用户的主要诉求是 X 时本技能不参与或者当本技能与其他技能同时加载时按顺序执行而非并行处理。这相当于给技能之间画了清晰跑道避免它们互相干扰。另一种思路是在描述里加一个区分型短语比如专门负责测试的技能就写仅在用户明确要求补测试或写测试计划时使用把自己和兄弟技能的语义空间隔开。5.4 Skill 规范与用户临场指令冲突怎么办用户临时说这次不用走流程直接给我结果的时候技能如果还强制按严格规则执行反而会引起反感。模型通常会把当前用户的指令视为更高优先级输入但如果你在技能正文里写了很多必须这样、必须那样两者冲突起来它要么僵住要么机械式地把流程重复一遍。我的建议是把高标准写成默认动作同时留一个让步条款。比如这样写除非用户明确要求简化流程否则按以下步骤执行如果用户已要求简化则只保留最关键的安全检查然后直接输出结果。 这种写法既保住了团队规范的默认约束力也给了临场变通的正当口子。实测下来模型在这种二选一的指令结构下表现干净很多不会反复横跳。5.5 通过内部标记和回读验证加载效果很多技能问题没法靠肉眼从最终输出里判断尤其是技能到底有没有被加载这件事。我的习惯是在技能正文的最开始写一个内部标记例如本次回答基于 code-review 技能然后观察实际输出里有没有这句话。没有说明技能没被加载有但执行跑偏说明正文指令写得还不够硬需要继续收敛。还有一个笨办法是在输出模板里加一项让 Claude 在回答末尾附带本次执行遵循的规则来源。虽然它有时会省略但配合上面的内部标记技巧已经足够排查大部分加载问题。当技能数量多起来之后这种可观测性设计会变得格外重要——你没法调试一个完全看不见的流程。6. 把 Skill 玩出深度本地脚本联动与个人沉淀6.1 让 Skill 调用本地工具半自动化执行Skill 的正文不只能约束模型的对话行为还可以指示它调用本地命令或工具脚本。比如代码审查技能里可以写如果检测到项目存在静态检查工具的配置先运行对应校验命令再把工具的报错输出与实际代码一起做综合分析提交信息技能则可以写先读取最近若干条提交记录总结本次改动的关键词再按团队模板生成新的提交说明。这个能力的价值在于把模型的理解力和工具的确定性结合起来模型擅长理解上下文和意图静态工具擅长捕获硬性规则两者互为补充。但要注意权限边界——技能里指示的命令尽量是只读的、低风险的避免模型在无人确认的情况下执行任何破坏性操作。我自己给技能定了一条纪律凡是会改动文件或执行命令的步骤正文里必须注明先向用户确认再运行。6.2 针对团队协作的 Skill 组合当团队规模变大一套组合拳式的技能编排会非常顺手。我见过一套比较成熟的用法新成员加入项目时只需要克隆仓库并打开 Claude Code就能让 AI 按照已有规范生成提交信息、做代码自检、补充测试、整理变更日志。新人不用背规则手册AI 也不会因为每个人的记忆差异而给出风格完全不同的输出。这套打法的前提是技能库本身质量过硬。所以一般我都会指定一个维护责任人定期过一遍技能库删除过期规则、更新示例、检查描述里的触发词是否还贴合团队最近的表达习惯。技能同样会腐化如果长期不维护它反映的不会是当下的团队标准而是三个月前的旧规矩这时候 AI 反而会成为一个用旧标准约束新代码的阻力。6.3 我的实操体会与建议路径最后说一点真实经验。刚开始接触 Skills 的时候我也犯过一口吃成胖子的毛病第一天就试图把十几种规范全部做成技能结果绝大多数技能写出来之后的一次都没被触发过反而给模型增加了很多选择负担。后来我调整策略从最痛的一个场景切入一个技能写完先用两周观察它在真实任务里的表现确认没问题之后再考虑发展第二个。这个节奏看起来慢实际上反而快。用两三周沉淀出五六个高频技能之后AI 在项目里的表现会有一个质的跃升——它终于不再是那个每次都要重新教育的聪明助手而是真正理解了你们团队工作节奏的一个成员。写 Skills 这件事本身没有太高的门槛难点只在于你想清楚哪条规矩值得让它记住。我的建议是下次你再发现自己对着 Claude 重复同一段话就停下来把那段话变成你的第一个 SKILL.md。