Claude Code Skills设计指南：从CLAUDE.md到自动化工作流

我在日常使用 Claude Code 时最头疼的事情就是同一个项目反复交代类似的规则。今天让 AI 按团队风格写提交信息明天提醒它别动测试文件后天又得教它怎么跑本地构建。CLAUDE.md 越写越长提示词越堆越重但换个项目、换台机器或者想把这些“经验”分享给同事时全都得从头再来。后来我把这些内容沉淀成了 Skills工作方式立刻就不一样了。简单说Skills 就是给 Claude Code 安装的一套“专业技能包”一个 Skill 对应一类具体任务里面有清晰的触发条件、操作流程、判断标准和可复用的资源文件。它让 AI 在“该出手时自动出手”而且不需要你每次把背景知识重新讲一遍。官方在文档里专门给过一整套最佳实践总结出来其实可以浓缩成一句话设计 Skill 的核心不是“写一份说明书”而是“设计一套能在合适时机自动触发、且稳定产出好结果的工作流”。这篇文章主要面向已经在用 Claude Code、想把重复劳动沉淀成资产的开发者。不管你是想让 AI 更懂某个框架的代码风格还是想让团队共享统一的审查规范看完你都能按一套可落地的步骤去设计自己的 Skill。1. 先想清楚Skills 到底解决什么问题1.1 从“反复解释”到“一次封装”先说个我自己的例子。早前我维护一个前端仓库每次让 Claude 改样式都得费半天劲先告诉它项目用什么 CSS 方案再说是 BEM 命名习惯接着强调禁止内联样式最后还得叮嘱它提交前跑 lint。这些指令每次都一样每次都得重新敲一遍或者从旧对话里翻出来粘贴。后来我把这些整理成两个 Skill一个负责“按项目规范生成样式代码”另一个负责“提交前检查代码风格”。从那以后Claude 读代码上下文时就会自动判断该不该启用这些技能整个过程我几乎不用额外说什么。官方给 Skills 的定位其实就是“让 Claude 在恰当的时候自动调用你预先封装好的知识或流程”。它和普通提示词最大的区别在于“自动触发”和“结构化”——你不需要在每次对话里明确说“请使用某某技能”只要描述写得好Claude 会在需要时自己找上门来。这个机制带来的直接好处是人的注意力被释放了AI 的行为变得稳定可预期团队协作时经验也能直接复用。1.2 Skills 与 CLAUDE.md、MCP 的分工很多新手会混淆这三者的关系我做一个简单但重要的区分CLAUDE.md 是“全局背景知识”告诉 Claude 项目是什么、技术栈是什么、常用命令、代码风格。它回答“你是谁、你在哪儿、有什么规矩”。Skills 是“专项工作能力”解决“遇到某类任务时如何高质量完成”。它回答“这件事具体怎么做、按什么步骤做、达到什么标准才算好”。MCP 是“外部工具接入”让 Claude 能访问数据库、浏览器、第三方 API。它回答“还能调用什么资源”。用生活里的话来讲CLAUDE.md 像入职手册Skills 像岗位 SOPMCP 像办公系统接口。入职手册告诉你公司情况但具体怎么处理客诉、怎么写周报靠的是 SOP要查客户资料、发邮件则要打开对应系统。常见的误区是把所有东西都塞进 CLAUDE.md。一旦内容超过几十行模型的注意力会被稀释真正重要的规矩反而容易被忽略。这时候就该考虑把“业务规则”留在 CLAUDE.md把“任务执行方法”挪到 Skill 里。我见过不少团队把几百行的规范全部塞进 CLAUDE.md结果模型在长上下文中丢失重点该守的规矩反而守不住。2. 官方最佳实践第一课结构设计决定成败2.1 目录放哪用户级、项目级还是插件级Skills 按作用范围分成几层很多人在第一步就放错了位置位置作用范围适用场景用户级~/.claude/skills/所有项目个人通用技能如代码审查、提交信息规范项目级.claude/skills/单个仓库项目专属规则如某框架的代码生成习惯插件级插件包内 skills 目录随插件分发团队共享通过插件分发到不同机器按照官方最佳实践的组织方式单个 Skill 就是一个独立目录目录名就是 Skill 名用短横线连接的小写单词比如fix-lint-errors、write-rust-tests。目录内至少要有一份SKILL.md这是入口文件其余可以放脚本模板、示例代码等。我建议普通用户按这个顺序试验先在项目级放一两个最常用的跑通了再沉淀到用户级。不要一上来就建一大堆全局技能维护成本高不说还容易在不同项目里互相干扰。一个很实际的例子某前端项目的“禁止使用内联样式”规则放到另一个用 CSS-in-JS 的项目里就完全没意义如果放在用户级反而会给那个项目添乱。2.2 前言 YAML这部分是“触发器”不是“名片”SKILL.md顶部有一小段 YAML 前言很多人的前言写得像论文摘要结果导致技能完全不触发。前言里最关键的不是name而是description。官方最佳实践明确强调description 要写“何时使用这个技能”而不是“这个技能是什么”。举个例子假设你想写一个“修复 lint 错误”的技能。错误的 description 是这个技能用于修复 JavaScript 代码中的 lint 错误。正确的 description 应该是当代码中存在 lint 错误或用户要求检查代码风格、修复 eslint 报错时使用。尤其适合在提交前、CI 失败后或代码审查阶段调用。区别在于前者只能靠用户提到“lint 错误”时才会被想起后者则把各种可能触发的情境都覆盖到了。Claude 会不会用你的技能很大程度上取决于它从 description 里能不能联想到“现在就是该用这个技能的时刻”。我自己的经验是写 description 时多列几个“用户可能怎么说、什么场景下会用到”越具体越好。测试时如果技能没触发八成不是正文写得不好而是 description 写得不够“招人”。描述不是写给人看的是写给模型做场景匹配用的这个思维转变很关键。2.3 正文三层结构渐进式披露是核心原则官方最佳实践反复强调“渐进式披露”这个原则说白了就是“别让 AI 一口气读完全部细节”。SKILL.md的正文建议按三层组织概述层一段话说清楚这个技能是做什么的、什么时候用、最终达到什么效果。流程层用步骤列表列出核心工作流程每个步骤一句话让 Claude 先建立全貌。细节层把每个步骤的细节、判断标准、注意事项放在后文或者在需要时引导 Claude 去查看子文件。为什么这么做因为 Claude 每轮对话的上下文窗口是有限的。如果你在一个 Skill 里堆了 5000 字的细节即使它能在某些情况下全部读完也会占用大量上下文空间挤占真正的代码内容。三层结构让 Claude 只需要读概述就能判断用不用决定用了再按需深入省下大量 token 不说响应质量也更稳定。我见过不少写得特别详细的 Skill事无巨细列了上百条规则结果模型反而抓不住重点。克制一点反而更可靠。这不是懒是设计。最理想的状态是概述层一两段能读完流程层五六个步骤能扫完细节则完全按需展开。2.4 别忘了版本管理Skill 也是代码既然 Skills 是“沉淀下来的资产”就应该像代码一样管理。我自己会把整个.claude/skills/目录放进 Git 仓库每次修改都有记录方便回滚。这个习惯救过我一次有一次我优化某个技能的正文结构改完后发现它在某个场景下反而不触发了靠着 Git 历史直接 diff 定位到是 description 的改动导致场景匹配变了马上回退前后不到五分钟。如果团队协作我还会在仓库里加一个简单的README.md说明每个 Skill 的用途、维护人和更新历史。配合依赖管理工具做插件分发时这种规范尤其重要。技能包不像普通代码它不会在编译期报错出问题都是运行时才暴露所以变更记录和回滚手段比你想的更值钱。3. 亲手写一个技能包代码审查 Skill 实战3.1 场景设定与目录规划下面我用一个真实用过的场景——“代码审查”——来完整演示怎么写。目标让 Claude Code 在收到审查请求时不是东一榔头西一棒子地随便看而是按照统一规范输出结构化审查结果。先建目录结构.claude/skills/code-review/ ├── SKILL.md ├── checklists/ │ ├── frontend.md │ └── backend.md └── templates/ └── review-report.md目录名叫code-review小写加短横线。SKILL.md是总入口checklists放不同技术栈的检查清单templates放输出报告模板。为什么要把 checklists 拆成前端和后端因为一个仓库里通常只有一种主要技术栈如果我把两套检查项都写进主文件Claude 审查前端代码时也会读到后端的检查项这些无关信息会干扰判断。拆开之后它按需读取干净利落。3.2 SKILL.md 完整示范与逐段拆解下面是一个简化但完整的SKILL.md--- name: code-review description: 当用户要求帮我看看代码是否有问题、做一次代码审查、Review一下这个PR或提交变更前希望检查潜在Bug和安全隐患时使用。适用于前端、后端、脚本等各类代码。 --- # 代码审查 这个技能用于执行一次结构化的代码审查输出按严重程度分类的问题清单并附上可执行的修复建议。适用于合并请求提交前、代码交付前的自检阶段。 ## 执行流程 1. 确认范围如果用户没有明确指定先找出最近的变更文件git diff 或用户提供的文件列表明确审查边界。 2. 逐文件审查按下述审查维度逐项检查每个变更文件记录问题。 3. 风险分级把每个问题标记为阻塞级、建议级或风格级。 4. 生成报告使用 review-report.md 模板输出包含问题清单、严重程度、定位行号和修复建议。 5. 复查验证再次确认所有阻塞级问题均已列出没有遗漏。 ## 审查维度 - 正确性空值、边界条件、异步时序、异常处理是否完整。 - 安全性输入校验、鉴权判断、危险函数使用是否安全。 - 性能是否有明显不必要的循环、重复查询、无记忆化计算。 - 可维护性命名、函数长度、模块拆分是否符合常规范式。 详细的分技术栈检查项参考 checklists/ 目录下对应文件如果涉及前端仓库阅读 frontend.md涉及后端阅读 backend.md。 ## 输出格式 严格按 templates/review-report.md 组织不要遗漏严重程度列。如果某个维度没有发现任何问题也要写未发现异常避免阅读者误以为检查跳过。你把描述部分写得特别长是因为它是整个技能能否触发的关键。前面已经讲过 description 的设计原则这里再强调一句让 Claude 自己推理何时用这个技能比给它一些花哨的关键词更有用。流程部分拆成 5 步每步都是可执行动作而不是抽象建议。官方特别强调要用“行动导向”的语言比如“执行流程”里写“找出最近的变更文件”而不是“确保审查范围清晰”。前者是可操作步骤后者像个口号模型执行起来没抓手。还有一个小细节我在“审查维度”里没有把所有规则铺开而是写道“详细检查项见 checklists 目录”。这就是渐进式披露的实际操作——把容易膨胀的细节拆到子文件让主文件保持在易读的范围。这样当 Claude 遇到前端代码时它会主动去读frontend.md遇到后端代码时读backend.md避免无关文件的信息干扰。3.3 渐进式披露与子文件checklists 到底怎么放checklists/frontend.md里我一般放这类内容组件拆分是否合理、状态管理是否有明显反模式、样式是否遵循项目约定、有无遗留的 console 和调试代码、事件监听有没有清理。backend.md则关注接口有无鉴权、SQL 是否存在 N1 查询、异常有没有被吞掉、敏感信息有没有硬编码。每个子文件不需要写成非常正式的文档用列表就足够。关键是条目要具体、可检查。一个可靠的 checklist 条目是“检查所有catch块是否存在空 catch 导致错误被静默吞掉”而不是“妥善处理异常”。前者是一个可以执行、可以判断通过与否的动作后者是一句正确的废话。在子文件的设计里我还习惯给每个条目加一个“严重级别建议”因为不同团队对同一问题的容忍度不一样。比如“缺少输入校验”在内部工具里可能是建议级在对外 API 里就必须是阻塞级。这样 Claude 在生成报告时就有了分级依据而不是自己拍脑袋。我建议你在自己的子文件里也尝试这个思路让规则更贴合团队实际情况。3.4 验收清单与迭代流程Skill 不是写完就完事最好按下面的清单过一遍检查项通过标准触发验证在 3 种不同表述的对话里Claude 均能自动启用该技能上下文占用主文件读完后约占用不超过 1000 个 token可通过对话日志估算结果一致性同一份代码连续审查 3 次问题清单差异不大可运维性子文件中的检查项能被团队成员独立修改不影响主流程我建议把“触发验证”做成一个小脚本把几种典型用户提问记下来反复测试。这样每次改完 description几分钟就能回归一遍。有一次我就是靠这个习惯发现了新改的 description 反而让技能在某个场景下不再触发了赶紧回退。触发问题不是“改了就完事”而是要持续回归尤其是在技能逐渐变多之后。迭代的时候记住一个顺序如果 Skill 没有被触发优先检查 description 的场景枚举如果触发了但结果不达标再回来优化正文流程。这个“先调触发器、再调执行器”的顺序我踩过不少坑才总结出来。很多人一上来就改正文改了半小时发现问题根本不在这里白白浪费时间。4. 常见问题与排查经验4.1 技能总是不触发怎么办不触发是最常见的问题90% 的情况出在 description。可以按这个顺序排查是不是 description 只写了“是什么”没写“何时用”补上具体场景。是不是场景描述太窄比如你只写了“修复 eslint 错误”但用户可能说的是“帮我把这行缩进调一下”。是不是项目级和用户级放混了确认技能确实在当前项目可访问的路径下。是不是正文第一步就让 Claude 犹豫了有些技能正文开头要求用户先提供信息但如果上下文里已经有这些信息Claude 可能判断“还缺东西”而放弃调用。测试时有一种取巧的办法直接在对话里说“请使用 code-review 技能”如果这样它都不读SKILL.md那多半是文件本身放错位置或格式错误如果能读但不会主动用问题就在 description。这个二分法能帮你快速缩小排查范围不用瞎猜。4.2 技能被触发后结果全是套话这种情况通常是正文写得“太原则”缺少强制性的输出约束。解决思路是加几条硬性规则比如规定报告必须包含定位行号、问题必须按三级分类、每条建议必须给出可直接落地的代码片段。我之前写过一份审查技能的早期版本流程写得挺全但输出格式没约束结果 Claude 经常给出一堆“建议加强代码健壮性”之类的废话。后来我把输出模板改成表格并且规定“没有行号的问题一律不接受”质量立刻上来了。模板不是形式主义它是一种很好的“强制格式校验”。框架性约束越多模型的自由度越低反而越稳定。4.3 多技能互相抢任务行为不稳定当你有多个 Skill 时可能出现“两个技能都想接管同一类任务”的情况这时 Claude 的行为会变得不稳定。我的处理办法是给每个 Skill 划清边界在 description 里明确写“如果涉及部署操作请改用 deploy-check 技能”或者反过来写“本技能只处理前端代码不处理后端”。另一种办法是刻意让技能粒度更小。官方也建议单个技能聚焦一类任务而不是做成一个“全能工具箱”。一个技能搞定所有事情听起来省事实际维护时会让你怀疑人生——因为它太多分支、太多特例逐步变得不可预测。拆分到每个技能对应一个明确场景行为反而更可控。我见过最典型的反面教材是一个“项目助手”技能里面既有代码规范又有部署流程还有数据库操作建议结果什么都做什么都不精。4.4 实战排查速查表现象可能原因处理办法完全不触发description 场景不足或放错目录扩充场景枚举检查目录层级触发率时好时坏多个技能 description 描述重叠在描述中标明边界收敛场景输出不符合预期正文缺少流程与验收标准补流程步骤、输出模板、质量标准上下文大量浪费正文太详细、未做渐进式披露细节下沉到子文件主文件保持概览结果不稳定规则过多且互相冲突精简规则突出 3~5 条核心硬性约束我个人还有一个习惯每星期抽时间看看 Claude 和 Skill 的交互记录挑一两条它没做好或者执行得反常的记录反推是哪一句话让它跑偏了。这比起凭空重写整个文件要高效得多。排查技能问题时别光靠“感觉”尽量从实际日志和对话记录里找证据这样定位问题的速度会快非常多。根据自己的几个项目经验最值得投入的 Skills 是那种“你会反复做、且每次做完都感觉像第一次做”的任务。把这些任务沉淀成技能包省下来的不只是敲提示词的时间更是一种“团队经验显性化”的过程。新同事拿到项目仓库跑一次代码审查技能基本就能摸清团队对代码的期待比读半年文档都管用。最后再分享一个小技巧如果你实在不知道从哪个 Skill 开始写就盯着自己最近十次让 AI 改代码的对话把重复出现的那些要求挑出来——比如“记得跑测试”“用项目现有的工具函数”“不要动公共接口”。把这几句话整理成一个最小的 Skill立刻就能感受到差距。别追求一次写完美先交付一个“70 分的能用版本”在真实使用中迭代到 90 分远比关起门来打磨大而全的方案要靠谱得多。