Claude Code Skill 实战：40个Skill的选型、编写与避坑指南

1. 从“能用”到“好用”为什么40个Skill是分水岭我大概是在去年年底开始把 Claude Code 当作日常主力工具的。最开始那两个月我的用法特别朴素打开终端敲一句需求等它吐代码复制粘贴跑一下报错了再贴回去。能用吗能用。但用久了总觉得哪里不对劲——每次开新会话它都像失忆一样我得重新交代项目结构、代码规范、测试命令、提交格式。一天下来光“喂背景”就耗掉不少时间。后来我陆续往里面塞 Skill从最开始的三五个到现在的四十个出头。变化不是线性的是那种“过了某个点突然通了”的感觉。以前我觉得 Skill 就是个提示词模板现在回头看这个理解太浅了。Skill 真正解决的是上下文复用和行为约束这两件事。前者让 Claude Code 不用每次从零理解你的项目后者让它按你团队的规矩干活而不是按它自己的“审美”干活。这篇文章不打算写成官方文档的翻译版。我想聊的是四十个 Skill 装下来哪些是真有用的哪些是凑数的SKILL.md 到底该怎么写frontmatter 里那几个字段为什么不能乱填以及我踩过的那些坑。如果你刚开始用 Claude Code或者装了 Skill 但感觉“没啥效果”这篇应该能帮你省下不少试错时间。提示Skill 的效果高度依赖你的项目结构和团队约定。同一个 Skill在 A 项目里如鱼得水在 B 项目里可能完全跑不通。别照搬要改造。2. Skill 到底是什么拆开 SKILL.md 看本质2.1 一个 Skill 就是一份“带触发条件的说明书”很多人第一次接触 Skill会把它和 Agent 搞混。我一开始也糊涂。简单说Agent 是“谁来干活”Skill 是“活该怎么干”。Agent 决定用哪个模型、走什么流程、调什么工具Skill 则是一份静态的、可复用的知识包告诉 Claude Code 在特定场景下应该遵循什么规则、参考什么资料、输出什么格式。从文件结构上看一个 Skill 就是一个目录里面至少有一个SKILL.md。这个文件分两部分顶部的 frontmatter用---包起来的那段和下面的正文。frontmatter 是元数据决定这个 Skill 什么时候被加载、叫什么名字、能不能被自动触发正文才是真正的“说明书内容”。我见过不少人写 Skill正文写得洋洋洒洒几千字frontmatter 就随便填两行。结果就是Skill 装进去了但 Claude Code 根本不知道什么时候该用它。这就像你写了一本特别好的操作手册但封面没写书名放在书架上没人找得到。2.2 frontmatter 里那几个字段一个都不能马虎frontmatter 的字段不多但每个都有明确作用。我拿一个实际在用的 Skill 举例--- name: vue-component-review description: 审查 Vue 3 组件的 props 定义、响应式使用和模板结构适用于 .vue 文件 trigger: - review component - 检查组件 - vue review ---name是 Skill 的唯一标识建议用短横线连接的小写英文别用中文也别用空格。我试过用中文名在某些终端环境下会出现编码问题加载失败。description是最关键的字段。它不只是给人看的Claude Code 在决定是否加载某个 Skill 时会读这段描述来判断相关性。所以描述里要包含场景和对象比如“审查 Vue 3 组件”比“代码审查”精准得多。我一般会写成“动词 对象 适用条件”的结构。trigger是可选的但强烈建议加上。它是一组关键词或短语当你的输入里出现这些词时Claude Code 会优先考虑加载这个 Skill。注意trigger 不是精确匹配是语义相关的模糊匹配。所以别写太泛的词比如“代码”“帮我”这种写了等于没写还会干扰其他 Skill 的触发。还有一个字段是version我一开始觉得没用后来发现当你有四十个 Skill 的时候版本管理就很重要了。某个 Skill 改了规则导致输出格式变了你得知道是哪个版本改的。我现在的习惯是每次改动都升一个小版本号配合 git 管理回滚很方便。2.3 正文怎么写少讲道理多给例子正文部分我踩过最大的坑就是“写太多”。最开始我恨不得把团队所有的代码规范都塞进去结果 Skill 加载后Claude Code 的上下文被占掉一大块反而影响了它处理实际任务的能力。后来我学乖了正文只写这个场景下必须知道的东西通用的规范放到项目根目录的CLAUDE.md里。正文的结构我一般按这个来先一句话说明这个 Skill 的目标然后给 2 到 3 个正例和反例最后列出检查清单。正反例特别重要因为 Claude Code 对“示例”的敏感度远高于“规则描述”。你说“props 要定义类型”它可能理解得模棱两可但你给一个defineProps{ title: string }()的正例再给一个defineProps([title])的反例它立刻就明白了。还有一个技巧正文里可以用##和###做分节Claude Code 在解析时会把这些标题当作结构线索。但别用太深的层级三级标题足够了再深它容易忽略。3. 四十个 Skill 的选型逻辑我为什么装这些不装那些3.1 按“使用频率”和“出错成本”两个维度筛装到四十个的时候我其实砍掉过一批。筛选标准就两个这个场景我多久遇到一次以及如果不按规矩来返工成本有多高。高频且高成本的必装。比如“提交信息规范”这个 Skill我每天要提交七八次如果格式不对CI 会卡住还得重新改。这种 Skill 装上去收益立竿见影。低频但高成本的也装。比如“数据库迁移脚本审查”一个月可能就两三次但一旦写错回滚很麻烦。这种 Skill 平时不触发关键时刻能兜底。高频但低成本的看情况。比如“格式化 JSON”我随手就能做装个 Skill 反而增加加载开销我就没装。低频且低成本的坚决不装。纯粹是占位置。3.2 我实际在用的几类 Skill按功能分我的四十个 Skill 大概落在这么几类里代码规范类大概十二个。覆盖 Vue、React、TypeScript、Python、Go 这几个主力语言。每个语言一个主 Skill再加几个针对特定框架的。比如 Vue 有组件审查、组合式函数检查、路由配置检查三个。工作流类大概八个。包括提交信息生成、PR 描述生成、变更日志整理、分支命名检查。这类 Skill 的特点是触发词很明确基本不会误触发。文档类大概六个。比如“给函数补 JSDoc”“生成 API 文档”“更新 README 的变更记录”。这类 Skill 我一般手动触发不设自动 trigger因为文档更新时机比较讲究自动触发容易在不该改的时候改。排查类大概五个。比如“分析报错栈”“检查依赖冲突”“定位性能瓶颈”。这类 Skill 的正文里我会放一些常见的排查路径相当于把经验固化下来。领域特定类大概九个。比如数学建模的公式检查、论文引用的格式校验、数据可视化的配色规范。这类 Skill 通用性不强但在特定项目里价值很高。剩下的几个是实验性的还在观察效果可能过段时间就删了。3.3 装太多会不会拖慢速度这是我被问得最多的问题。实测下来Skill 的数量本身不会显著拖慢响应速度真正影响速度的是单个 Skill 的正文长度和触发频率。Claude Code 在加载 Skill 时是按需加载的不是一次性把所有 Skill 都塞进上下文。所以四十个 Skill 里如果大部分平时不触发对日常使用几乎没影响。但有个例外如果你的 trigger 写得太宽泛导致每次输入都触发好几个 Skill那上下文会被迅速占满响应质量会下降。我踩过这个坑有个 Skill 的 trigger 里写了“检查”结果我每次说“检查一下这个函数”它都会加载后来我把 trigger 改成了“检查依赖”“检查类型”这种更具体的短语问题就解决了。4. 手把手从零装一个 Skill 并让它真正生效4.1 目录放哪里决定了它能不能被找到Claude Code 查找 Skill 的路径是有优先级的。我一般把项目专用的 Skill 放在项目根目录的.claude/skills/下面把通用的、跨项目复用的放在用户目录的~/.claude/skills/下面。这样项目级的 Skill 不会污染全局全局的 Skill 又能在所有项目里用。目录结构大概长这样项目根目录/ ├── .claude/ │ └── skills/ │ ├── vue-component-review/ │ │ └── SKILL.md │ ├── commit-message/ │ │ └── SKILL.md │ └── api-doc-gen/ │ └── SKILL.md ├── CLAUDE.md └── src/注意每个 Skill 一个独立目录目录名和 frontmatter 里的name保持一致。我试过目录名和 name 不一致结果在某些版本里加载会出问题虽然不报错但 Skill 就是不生效排查了半天才发现是这个原因。4.2 写一个能用的 SKILL.md完整示例我拿“提交信息生成”这个 Skill 来演示。这个 Skill 我每天都在用算是打磨得比较成熟的。--- name: commit-message description: 根据 git diff 生成符合 Conventional Commits 规范的提交信息适用于任何需要提交代码的场景 trigger: - 生成提交信息 - commit message - 写 commit version: 1.3.0 ---正文部分## 目标 根据当前暂存区的变更生成一条符合 Conventional Commits 规范的提交信息。 ## 格式要求 提交信息格式为type(scope): subject type 只能是以下之一 - feat新功能 - fix修复缺陷 - refactor重构不改变外部行为 - docs文档变更 - test测试相关 - chore构建、依赖、配置等杂项 scope 为可选项用变更涉及的模块名小写不加空格。 subject 用中文不超过 50 个字结尾不加句号。 ## 正例 feat(user): 增加手机号登录入口 fix(api): 修复分页参数越界导致的 500 错误 refactor(utils): 将日期格式化逻辑抽离为独立函数 ## 反例 更新代码 fix bug feat: 增加了一个新功能这个功能可以让用户通过手机号登录系统这个 Skill 装上去之后我每次说“生成提交信息”它就会先跑git diff --staged然后按上面的规则输出。实测下来准确率在九成以上偶尔 scope 判断得不太准我手动改一下就行。4.3 验证 Skill 是否生效的三种方法装完 Skill 后别急着用先验证一下。我一般用这三种方法第一种直接问 Claude Code“你现在有哪些可用的 Skill”它会列出当前加载的 Skill 列表。如果新装的没出现说明路径或 frontmatter 有问题。第二种用 trigger 里的关键词触发一次看它的输出是否符合 Skill 里定义的格式。比如我说“生成提交信息”如果它输出的格式和 Skill 里写的不一样说明 Skill 没被加载或者加载了但被其他 Skill 覆盖了。第三种看日志。Claude Code 在加载 Skill 时会有日志输出具体位置取决于你的安装方式。我一般会在启动时加上--verbose参数能看到 Skill 的加载过程。这个方法最直接但日志比较长适合排查疑难问题。注意如果你同时装了多个 Skill且它们的 trigger 有重叠Claude Code 可能会加载多个导致输出混乱。我建议定期检查 trigger 的重叠情况把不用的 Skill 及时删掉或改 trigger。5. 那些让我拍大腿的 Skill 设计技巧5.1 用“检查清单”代替“长篇规则”我早期写的 Skill正文动辄两三千字把团队规范从头到尾抄了一遍。结果 Claude Code 加载后输出确实规范了但变得特别死板稍微超出规范的情况就不会处理了。后来我改成“检查清单”的形式只列出必须检查的条目每条一两句话剩下的交给 Claude Code 自己判断。比如“Vue 组件审查”这个 Skill我现在的正文核心就是一张清单props 是否都有类型定义是否使用了defineProps的泛型形式响应式数据是否用ref或reactive正确声明模板中是否有未使用的导入事件命名是否用 kebab-case就这五条Claude Code 每次审查都会逐条过输出很稳定。而且因为规则少它有余力去发现清单之外的问题反而比之前“死守规则”的效果好。5.2 把“反例”写进 Skill比写“正例”还重要这个技巧是我从一次失败中总结出来的。有个 Skill 我写了很多正例但 Claude Code 总是输出一些“看起来对但实际不对”的东西。后来我加了几个反例明确告诉它“这样写是错的”效果立刻好转。原因不难理解正例告诉它“往哪走”反例告诉它“别往哪走”。只有正例的时候它可能会走到正例附近的某个“看起来像”的地方有了反例边界就清晰了。我现在的习惯是每个 Skill 至少配两个反例反例要写得具体最好是从实际项目中摘出来的真实错误。5.3 用version字段做灰度发布当你有四十个 Skill 的时候改一个 Skill 可能会影响多个项目。我现在的做法是改 Skill 时先升version然后在项目里通过CLAUDE.md指定使用哪个版本。这样新版本可以先在一个项目里试没问题了再推广到其他项目。具体做法是在CLAUDE.md里写## Skill 版本锁定 - commit-message: 1.3.0 - vue-component-review: 2.1.0Claude Code 在加载 Skill 时会读这个配置如果版本不匹配就跳过。这个机制不是官方强制的但我在实际使用中发现它确实能减少“改了一个 Skill崩了三个项目”的情况。6. 常见问题与排查实录6.1 Skill 装了但不生效怎么查这是最高频的问题。我整理了一个排查顺序按这个走基本能定位到原因排查步骤检查内容常见问题1目录路径是否正确放错了层级比如放到了.claude/skill/而不是.claude/skills/2frontmatter 格式是否正确---没写全或者 YAML 缩进错误3name 是否与目录名一致不一致时部分版本会静默失败4trigger 是否被其他 Skill 覆盖多个 Skill 的 trigger 重叠导致加载了错误的那个5正文是否过长超过上下文限制时会被截断导致规则不完整我遇到最多的是第 2 和第 4。第 2 个问题特别隐蔽因为 YAML 对缩进敏感多一个空格少一个空格都可能出问题。我的建议是写完 frontmatter 后用一个 YAML 校验工具过一遍别靠肉眼。6.2 多个 Skill 冲突怎么办冲突的表现是你触发了一个 Skill但输出格式是另一个 Skill 的。原因通常是 trigger 重叠。比如“代码审查”和“Vue 组件审查”都写了“审查”这个 trigger那你说“审查这个组件”时两个都可能被加载。解决办法有两个一是把 trigger 写得更具体二是用priority字段如果你的 Claude Code 版本支持指定优先级。我一般用第一种因为更直观。把“审查”改成“审查组件”“审查函数”“审查接口”各管各的互不干扰。6.3 Skill 输出不稳定时好时坏这个问题我遇到过好几次最后发现原因通常是 Skill 正文里的规则有歧义。比如我写“函数名要简洁”什么叫简洁Claude Code 每次理解都不一样。后来我改成“函数名不超过 20 个字符用动词开头”输出立刻就稳定了。所以Skill 里的每一条规则都要可量化、可验证。形容词和模糊表述是稳定性的天敌。6.4 怎么判断一个 Skill 该不该删我每个月会做一次 Skill 清理。判断标准很简单过去一个月里这个 Skill 触发了几次如果一次都没触发而且不是因为场景没出现而是因为 trigger 写得太偏那就改 trigger如果场景本身就没出现那就删掉。四十个 Skill 听起来多但真正高频使用的其实就十来个。剩下的要么是低频兜底要么是特定项目专用。定期清理能让你对每个 Skill 的状态心里有数不至于装了一堆自己都忘了的 Skill。7. 从四十个 Skill 里挑出来的五条硬核经验第一条Skill 不是越多越好是越准越好。我见过有人装了上百个 Skill结果每次输入都触发一堆上下文被占满响应又慢又乱。四十个对我来说是个比较舒服的数字覆盖了主要场景又不至于互相干扰。第二条frontmatter 的 description 要当 SEO 标题来写。它决定了 Skill 能不能被正确检索到。我现在的写法是“动词 对象 场景”比如“审查 Vue 3 组件的 props 和响应式使用”比“Vue 审查”的命中率高很多。第三条正文里多放例子少讲道理。Claude Code 对示例的敏感度远高于规则描述。一个正例加一个反例胜过三段文字说明。第四条trigger 要具体别用泛词。“检查”“帮我”“看看”这种词写了等于没写还会干扰其他 Skill。用“检查依赖”“帮我生成提交信息”“看看这个组件的 props”这种具体短语。第五条定期清理保持精简。Skill 是有维护成本的每多一个就多一份 trigger 冲突的风险和上下文占用的可能。每个月花十分钟过一遍删掉不用的改掉不准的比装新 Skill 的收益还大。最后分享一个我最近在用的技巧把 Skill 和CLAUDE.md配合起来用。CLAUDE.md放项目级的通用规范Skill 放场景级的专项规则。这样 Skill 可以写得很薄只关注它那个场景通用的东西不用重复写。我试过把两者合并结果 Skill 变得特别臃肿加载慢不说还容易和其他 Skill 冲突。分开之后每个 Skill 都清爽了很多维护起来也轻松。