Claude Code Skill实战：40个Skill从入门到精通

1. 从“能跑就行”到“越用越顺手”我为什么开始折腾 Skill刚上手 Claude Code 那阵子我的用法特别朴素打开终端敲一句需求等它吐代码复制粘贴收工。能用吗能用。但用久了总觉得哪里不对劲——每次都要重新交代项目背景每次都要重复“别用 any”“记得写测试”“这个目录别动”像极了带一个记性不太好但能力很强的实习生。直到我把 Skill 这套机制真正用起来前后装了四十来个才意识到之前那些重复劳动本质上都是因为没把“经验”沉淀成可复用的资产。先把概念说清楚免得后面绕。Claude Code 是运行在终端里的编码智能体它能读写文件、执行命令、跑测试、查文档核心能力是“动手干活”。而Skill 是一份写给智能体的操作说明书通常是一个目录里面放一个SKILL.md用自然语言描述“什么场景下该做什么、按什么顺序做、有哪些坑要避开”。你可以把它理解成给智能体准备的“岗位 SOP”Agent 是干活的人Skill 是贴在工位上的作业指导书MCP 则是给这个人配的外部工具接口。这三者的关系我踩过坑才理清。一开始我以为 Skill 就是提示词模板写了一大堆“你是一个资深工程师”之类的角色设定结果发现效果平平。后来才明白Skill 的价值不在于“告诉它你是谁”而在于“告诉它这件事具体怎么做”。角色设定是虚的操作步骤是实的。比如“你是一个严谨的工程师”这种话模型听完该犯错还是犯错但如果你写“修改数据库 schema 前必须先检查 migrations 目录下最新的版本号并在新迁移文件里用down方法写好回滚逻辑”它就会老老实实照做。那为什么是“40 个”这个量级因为 Skill 这东西有个特点单个 Skill 越聚焦组合起来威力越大。我一开始想写一个“万能 Skill”包打天下结果那份文件写到两千字就开始互相打架——前端规范和后端规范混在一起测试策略和部署流程挤在一段里模型读到后面忘了前面。后来我改成“一个 Skill 只解决一类问题”拆成了四十来个每个平均两三百字反而稳定得多。这跟写函数是一个道理高内聚、低耦合。装完这批 Skill 之后最直观的变化是我不再需要每次开新会话都重新“调教”它了。项目背景、代码规范、常用命令、避坑清单全都固化在.claude/skills/目录里跟着仓库走。换台机器、换个同事拉下代码就自带这套“工作经验”。这才是 Skill 真正让我觉得“之前白用了”的地方——它不是让你少打几个字而是让你的项目拥有了一套可传承的作业标准。下面我会把这四十来个 Skill 按用途拆开讲包括哪些是刚需、哪些是锦上添花、哪些装了反而添乱以及怎么写一个真正管用的 Skill。如果你也在用 Claude Code或者正在搭自己的 Agent 工作流这篇应该能帮你少走不少弯路。2. Skill、MCP、Agent 到底谁管谁先把概念钉死2.1 三个词经常被混着用但职责完全不同我在社区里看到太多人把这三个概念搅在一起导致配置的时候东一榔头西一棒子。用一句话概括Agent 是执行主体Skill 是行为规范MCP 是能力外挂。Agent 是那个“会自己决定下一步做什么”的东西。你给它一个目标它会拆解、规划、调用工具、观察结果、再调整。Claude Code 本身就是一个 Agent它有自主性能根据你的指令决定读哪个文件、跑哪条命令。Skill 不带来新能力它改变的是 Agent 的“做事方式”。一个没有 Skill 的 Agent 也能写代码但可能写得不符合你的团队规范装了 Skill 之后它知道“这个项目用 pnpm 不用 npm”“提交信息要遵循 Conventional Commits”“改公共组件必须同步更新 Storybook”。Skill 是约束也是经验传递。MCP 则是实打实的能力扩展。比如 Playwright MCP 让 Agent 能操作浏览器Figma MCP 让它能读设计稿蓝湖 MCP 让它能拉取标注信息。没有 MCPAgent 就只能在你本地文件系统里打转有了 MCP它能触达外部世界。MCP 解决“能不能做”Skill 解决“做得对不对”。我见过有人试图用 Skill 去实现“访问数据库”这种需求写了半天发现根本做不到——因为 Skill 只是文本它没法凭空建立连接。这种时候该上 MCP。反过来有人用 MCP 拉了一堆数据回来但 Agent 不知道怎么处理输出乱七八糟这就是缺 Skill。2.2 一个具体例子让 Agent 帮你改一个 React 组件假设你说“把这个按钮组件的圆角改成 8px”。三种机制各司其职Agent负责理解这句话找到按钮组件文件定位到样式定义执行修改然后跑一下相关测试确认没改坏。Skill负责告诉它这个项目的样式写在*.module.css里而不是内联改完要同步更新design-tokens.json组件改动需要跑pnpm test Button而不是全量测试。MCP负责在需要时提供额外信息比如通过 Figma MCP 去核对设计稿里这个按钮的真实圆角值到底是不是 8px。三者配合才是一次完整的、靠谱的改动。缺了 Skill它可能改错文件缺了 MCP它可能凭记忆瞎猜设计值。2.3 为什么我建议先写 Skill 再考虑 MCP很多人一上来就折腾 MCP装了一堆 server结果 Agent 还是干不好活。原因很简单MCP 给的是原料Skill 给的是菜谱。你给一个不会做饭的人塞满冰箱他还是做不出一顿饭。我的建议顺序是先把项目里高频、重复、容易出错的环节写成 Skill让 Agent 在纯本地环境下就能稳定干活等到确实遇到“必须访问外部系统”的瓶颈时再引入对应的 MCP。这样每一步的收益都清晰可见也不会因为 MCP 配置复杂而卡在半路。提示Skill 是纯文本跟着 Git 走团队共享零成本MCP 往往涉及凭证、网络、进程管理维护成本高一个量级。能用 Skill 解决的别急着上 MCP。3. 四十个 Skill 的分类账哪些是刚需哪些是噪音3.1 我的分类框架按“触发时机”而不是“技术栈”分一开始我按前端、后端、测试、部署这么分结果发现不好用——很多 Skill 是跨栈的比如“提交前检查”既涉及前端也涉及后端。后来我改成按触发时机分类一下子清爽了类别触发时机典型 Skill数量入口类会话开始、任务启动项目背景加载、技术栈声明5规范类写代码过程中命名规范、目录约定、依赖管理12流程类特定操作前后提交前检查、迁移流程、发布流程10排错类遇到错误时常见报错对照、日志排查路径8工具类调用特定工具时测试命令、构建命令、调试技巧5这个分类的好处是当我想加一个新 Skill 时能立刻判断它属于哪一类、会不会和已有的冲突。比如“提交前检查”和“发布流程”都涉及 Git 操作但触发时机不同可以共存而两个都叫“代码规范”的 Skill 就会打架必须合并。3.2 真正每天都在用的那八个四十个里其实有八个是我几乎每个会话都会触发的剩下的属于“用到才想起”。这八个是项目背景加载会话开始时自动读取CLAUDE.md和README把技术栈、目录结构、关键约定注入上下文。依赖管理规范明确用哪个包管理器、锁文件怎么处理、加依赖前要先查什么。提交前检查跑 lint、类型检查、相关测试全绿才允许提交。测试命令速查单测、集成测试、E2E 分别怎么跑怎么只跑改动相关的。数据库迁移流程改 schema 的标准步骤含回滚写法。常见报错对照把项目里反复出现的报错和对应解法列成表。目录约定新文件该放哪什么能放utils什么不能。调试技巧日志打在哪、怎么复现、怎么缩小范围。这八个覆盖了日常开发八成的重复沟通。装完之后我开新会话基本只需要说“帮我做 X”不用再补一堆背景。3.3 那些装了反而添乱的 Skill不是越多越好。我踩过的坑包括过度细碎的规范写了个“变量命名必须用完整单词不许缩写”的 Skill结果 Agent 每次命名都纠结半天还经常和现有代码风格冲突。后来删了改成“遵循文件内已有命名风格”。互相矛盾的 Skill一个说“测试文件放同级目录”另一个说“测试统一放__tests__”Agent 每次都要猜输出不稳定。这种必须合并成一个。太长的 Skill有个 Skill 我写了八百多字结果模型读到后面就忘了前面。后来拆成三个短的效果立刻好转。单个 Skill 控制在 300 字以内是我实测下来最舒服的长度。和 MCP 功能重叠的 Skill比如写了个“如何查 API 文档”的 Skill但项目已经配了对应的 MCP纯属多余。删掉这些之后四十个精简到三十出头反而更好用。所以数量不是目标覆盖度和清晰度才是。4. 手把手写一个能打的 Skill从结构到措辞4.1 SKILL.md 的骨架长什么样一个 Skill 就是一个目录核心是SKILL.md。最小可用结构是这样--- name: pre-commit-check description: 提交代码前的标准检查流程确保 lint、类型、测试全部通过 --- # 提交前检查 ## 何时使用 当用户要求提交代码、创建 commit、或说帮我提交时触发。 ## 执行步骤 1. 运行 pnpm lint若有错误先修复再继续 2. 运行 pnpm typecheck类型错误必须清零 3. 运行 pnpm test --changed只跑改动相关的测试 4. 全部通过后用 Conventional Commits 格式生成提交信息 5. 执行 git add 和 git commit ## 注意事项 - 不要用 git commit -am会漏掉未跟踪的新文件 - 提交信息里不要出现AI 生成字样 - 如果测试失败先报告失败原因不要强行提交name和description是给 Agent 看的索引它靠这两项判断“当前场景该不该加载这个 Skill”。description 要写清楚触发条件而不是功能描述。写“提交前检查流程”不如写“当用户要求提交代码时使用”。4.2 措辞的三个原则具体、可执行、有边界我改过很多版 Skill总结出三条措辞原则第一动词要具体。“优化代码”是废话“把重复超过三次的逻辑抽成函数”才是指令。Agent 需要的是可执行的动作不是抽象的目标。第二给判断依据不给结论。与其写“不要用 any”不如写“遇到类型不确定时优先用unknown配合类型守卫实在无法确定再考虑any并加注释说明原因”。前者是死规矩后者是决策逻辑后者在边界情况下更靠谱。第三明确边界。写清楚“这个 Skill 不管什么”。比如提交前检查的 Skill 里要注明“不负责解决冲突遇到冲突先停下来问用户”。边界不清的 Skill 会让 Agent 越权操作。4.3 一个真实的反面教材我最早写的“代码规范”Skill 是这样的请写出高质量、可维护、符合最佳实践的代码注意命名规范、 代码风格、错误处理、性能优化、安全性等各个方面。这份 Skill 的问题在于它说的每句话都对但每句话都没用。什么叫“高质量”什么叫“最佳实践”Agent 只能靠猜猜出来的结果每次都不一样。后来我改成## 命名 - 组件用 PascalCase文件名与组件名一致 - hooks 用 use 开头返回对象而非数组 - 常量用 SCREAMING_SNAKE_CASE集中在 constants.ts ## 错误处理 - 异步操作必须 try/catchcatch 里不能只 console.log - 用户可见的错误要转成友好文案技术细节写日志 - 不要吞掉错误要么处理要么往上抛改完之后Agent 的输出立刻稳定了。Skill 的质量不取决于你懂多少而取决于你能把懂的东西拆得多细。5. 让 Skill 真正生效加载机制与调试方法5.1 Skill 是怎么被“看见”的Claude Code 启动时会扫描.claude/skills/目录读取每个 Skill 的name和description形成一个索引。当你的指令和某个 description 匹配时它才会把完整的SKILL.md内容加载进上下文。这个机制叫渐进式披露好处是不用把所有 Skill 全文塞进上下文省 token。理解这一点很关键如果 Skill 没被触发八成是 description 写得不够“像触发条件”。我有个“数据库迁移”的 Skilldescription 原本写的是“数据库 schema 变更规范”结果我每次说“加个字段”它都不触发。改成“当需要修改数据库表结构、添加或删除字段、创建新表时使用”之后立刻就灵了。5.2 怎么确认 Skill 到底加载了没有调试 Skill 最直接的办法是看 Agent 的行为。如果它按你写的步骤走了说明加载了如果还是老样子说明没触发。我常用的几个排查手段故意在 Skill 里写一个显眼的动作比如“第一步先输出[pre-commit-check 已加载]”看它有没有打出来。用/context之类的命令查看当前上下文确认 Skill 内容是否在里面。临时把 description 改得极端具体比如直接写“当用户说‘提交’两个字时触发”测试触发链路是否通。确认链路通了之后再把 description 调回正常措辞。5.3 多个 Skill 同时触发时的优先级一个指令可能同时匹配多个 Skill比如“提交代码”既匹配“提交前检查”又匹配“Git 操作规范”。这时候 Agent 会自己判断但判断结果不一定符合你的预期。我的做法是在 Skill 里显式声明依赖关系## 依赖 本 Skill 执行前应先加载 git-conventions Skill 了解提交信息格式。或者在“提交前检查”里直接内联 Git 规范的关键点避免跨 Skill 依赖。能内联的就别依赖跨 Skill 调用是出错的重灾区。6. 踩坑实录那些让我返工的配置问题6.1 Skill 目录放错位置怎么都不生效我一开始把 Skill 放在项目根目录的skills/下折腾半天不触发。后来才知道默认扫描路径是.claude/skills/。这个坑很典型——Claude Code 的配置目录是.claude/不是项目根目录。放对位置之后立刻就好了。如果你想让某些 Skill 全局生效所有项目都能用可以放在用户主目录的~/.claude/skills/下。我的做法是通用规范放全局项目特定规范放仓库。比如“提交信息格式”这种放全局“这个项目的测试命令”放仓库。6.2 description 写得太“文艺”触发率极低我有个 Skill 的 description 写的是“守护代码质量的最后一道防线”自我感觉良好结果从来没被触发过。Agent 匹配的是关键词和场景不是意境。改成“当用户要求提交代码或创建 commit 时使用”之后触发率立刻上来了。description 是给机器看的不是给人看的。它需要包含用户可能说的原话关键词。我现在的习惯是写完 description 后自己念一遍“如果我是用户我会怎么说这句话”把那些说法里的关键词塞进去。6.3 Skill 之间打架Agent 开始“精神分裂”前面提过测试目录的矛盾这里展开说。我有两个 Skill一个来自前端模板一个来自后端模板对测试文件位置的规定不同。Agent 每次写测试都要在两个规则之间摇摆有时候放这有时候放那代码库越来越乱。排查这种问题的方法是把当前会话加载的所有 Skill 列出来逐个检查有没有规则冲突。发现冲突后要么合并成一个统一规则要么在更具体的 Skill 里显式覆盖通用规则。我现在的做法是同一类规则只允许存在一个 Skill需要区分场景就在 Skill 内部用条件分支写清楚。6.4 把“一次性任务”写成了 Skill有段时间我接了个临时的数据迁移任务顺手写了个 Skill 记录步骤。任务做完之后这个 Skill 还留着结果后来每次涉及数据处理Agent 都会去加载它套用那套只适用于一次性任务的逻辑反而添乱。Skill 是给重复性工作准备的。一次性的操作写在对话里就行别沉淀成 Skill。判断标准很简单这件事未来三个月还会做吗会就写不会就别写。7. 从四十个到一套体系我的组织与维护心得7.1 用命名前缀做分组Skill 多了之后光靠目录不好找。我用命名前缀做了分组proj-开头项目特定规范如proj-structure、proj-depsflow-开头流程类如flow-commit、flow-migratefix-开头排错类如fix-common-errors、fix-logstool-开头工具用法如tool-test、tool-build这样在目录里一眼就能看出每个 Skill 的定位也方便批量管理。命名前缀比子目录更好用因为 Skill 扫描是平铺的子目录反而增加层级。7.2 定期清理比持续添加更重要我现在每个月会花半小时过一遍 Skill 列表问三个问题这个 Skill 过去一个月触发过吗没触发过是不是 description 有问题还是根本不需要这个 Skill 的内容和项目现状还一致吗技术栈升级了、目录调整了Skill 有没有同步更新有没有两个 Skill 可以合并规则重叠的合并成一个更清晰。Skill 库和代码库一样会腐化。不定期清理半年后就是一堆过时规则的垃圾场Agent 加载了反而被误导。7.3 把 Skill 纳入代码评审我们团队现在把.claude/skills/目录纳入 PR 评审范围。改 Skill 和改代码一样要说明为什么改、影响哪些场景。这样能避免个人随手加规则导致团队规范分裂。Skill 是团队资产不是个人笔记这个定位很重要。8. 关于 Skill 的几个常见误解8.1 “Skill 写得越多Agent 越聪明”不对。Skill 不提升模型能力它只是把已知信息喂给模型。写得再多模型该不会的还是不会。Skill 的上限是“把你已经会的东西稳定复现”不是“让模型学会新东西”。指望靠堆 Skill 让 Agent 变强方向就错了。8.2 “有了 Skill 就不需要 CLAUDE.md 了”两者定位不同。CLAUDE.md是会话级的全局背景每次都会加载Skill 是按需加载的专项说明。项目概述、技术栈这种“每次都需要”的信息放CLAUDE.md具体操作流程放 Skill。我见过把所有内容都塞进 Skill 的结果每次会话都要触发一堆 Skill 才能凑齐背景信息效率反而低。8.3 “Skill 必须写得很正式”完全不用。我有些 Skill 就是大白话“这个项目别用 npm用 pnpm锁文件是 pnpm-lock.yaml别提交 package-lock.json。”效果一样好。Agent 理解自然语言的能力很强你写得越像跟同事交代事情它执行得越准。刻意写成文档腔反而容易产生歧义。8.4 “Skill 和 Agent 是一回事”不是。Agent 是执行者Skill 是执行者手里的手册。你可以有多个 Agent 共用一套 Skill也可以一个 Agent 在不同场景加载不同 Skill。把 Skill 理解成“可插拔的经验包”这个心智模型最准。9. 我个人的几条实操建议折腾这四十个 Skill 的过程踩的坑比省的时间还多但沉淀下来之后确实回不去了。最后分享几条我自己的体会都是真金白银换来的。先写三个用一周再决定要不要加。别一上来就规划四十个那是纸上谈兵。先挑最高频的三个场景写成 Skill用一周看效果确认机制跑通了、收益明显了再逐步扩展。我第一批写的三个是“提交前检查”“测试命令”“目录约定”用了一周就离不开了。Skill 里的每条规则都要能回答“为什么”。写“不要用 any”不如写“不要用 any因为项目开了 strict 模式any 会绕过类型检查导致运行时错误”。带上原因的规则Agent 在边界情况下能自己判断不带原因的规则它只会死板执行遇到例外就卡住。description 用用户的原话不用专业术语。用户说“帮我提交”不会说“执行版本控制提交操作”。description 里要包含前者。我现在的习惯是把用户可能说的三五种说法都塞进 description触发率明显提升。定期删别舍不得。写 Skill 有沉没成本删的时候会心疼。但过时的 Skill 比没有 Skill 更糟因为它会主动误导 Agent。我现在删 Skill 毫不手软反正 Git 里有历史需要的时候能翻出来。把 Skill 当成团队文档来维护。一个人写的 Skill 只有一个人受益团队共享的 Skill 才是资产。我们现在的做法是新人入职第一件事就是读一遍.claude/skills/目录比读传统文档快得多因为 Skill 是“怎么做”而不是“是什么”。这套东西说到底核心就一句话把重复的沟通沉淀成可复用的文本让 Agent 每次都能站在你之前的经验上干活。四十个不是目标让每一个都真正被用起来才是。