1. 从50个Skill里爬出来的血泪账前阵子我给自己定了个目标把手上重复性高的活儿全部封装成 Claude Code Skill。写文档、做代码审查、生成测试用例、整理会议纪要、甚至帮我把零散的笔记转成结构化知识库能自动化的全自动化。吭哧吭哧写了50个回头一复盘发现前30个基本等于白写——不是不能用而是用起来别扭、维护成本高、复用率低最后大部分都被我删了重写。这篇文章就是把这50个Skill的踩坑过程摊开讲。如果你刚开始接触 Claude Code或者已经写了几个Skill但总觉得哪里不对劲那这篇内容应该能帮你少走至少一个月的弯路。我会从Skill的整体设计思路讲起拆解SKILL.md的结构、frontmatter的写法、和MCP的配合方式再给出一套可以直接抄的实操流程和排查清单。不管你是刚安装完Claude Code的新手还是已经在折腾skill插件的老手都能从中找到能直接用的东西。先说结论Skill写得好不好跟你写多少行提示词关系不大关键在于你有没有想清楚“这个Skill到底在什么场景下被触发、触发后需要哪些上下文、输出给谁看”。前30个Skill之所以白写就是因为我一直在“写提示词”而不是在“设计工作流”。2. Skill到底是个什么东西为什么值得认真对待2.1 从“每次都要重新解释”到“一次封装反复调用”没用Skill之前我用Claude Code的典型流程是这样的打开终端输入一段长长的提示词告诉它“你现在是一个资深后端工程师请帮我审查这段代码重点关注并发安全和错误处理输出格式用表格每个问题标注严重等级”。每次审查新代码这段话都要重新打一遍或者从某个笔记里复制粘贴。偶尔忘了加某个约束条件输出格式就变了还得重新来。Skill解决的正是这个问题。它把“角色设定任务描述输出格式约束条件”打包成一个可复用的单元放在特定目录下Claude Code在合适的时机自动加载。你不需要每次重新解释它就知道该干什么、怎么干、干完输出成什么样。打个比方没有Skill的时候你像一个每次都要给新员工做岗前培训的老板有了Skill你相当于写了一份标准作业程序新员工入职直接照着做就行。2.2 SKILL.md、frontmatter、MCP三者的分工很多人一开始会把这三个概念搞混。我用一个实际例子来说明它们的关系。假设你要做一个“代码审查Skill”。SKILL.md是主体文件里面写的是审查的流程、关注点、输出格式这些“软性”内容。frontmatter是SKILL.md开头用---包裹的元数据区域用来声明这个Skill叫什么名字、什么时候触发、需要哪些工具权限。MCP则是更底层的能力扩展协议当你的Skill需要访问外部系统比如查数据库、调API、读Figma设计稿时就需要通过MCP来桥接。三者的关系可以这样理解frontmatter是门牌号告诉Claude Code“我在哪、什么时候来找我”SKILL.md是操作手册告诉Claude Code“找到我之后按这个流程干活”MCP是工具箱当操作手册里写到“需要拧螺丝”时MCP负责把螺丝刀递过来。我前30个Skill犯的最大错误就是把这三者混在一起写。frontmatter里塞了一大堆触发条件SKILL.md里又重复了一遍触发逻辑MCP配置散落在各个地方。结果就是Skill之间互相干扰有时候该触发的没触发不该触发的乱触发。2.3 什么样的任务适合封装成Skill不是所有任务都值得写成Skill。我踩过的坑包括把一次性任务写成Skill用完就再也没打开过、把过于宽泛的任务写成Skill触发条件写不清楚Claude Code不知道该不该用、把需要大量人工判断的任务写成Skill输出质量不稳定还不如自己动手。经过50个Skill的筛选我总结出一个判断标准高频、有固定流程、输出格式可标准化、不需要太多外部实时信息的任务才适合封装成Skill。比如代码审查、提交信息生成、测试用例生成、文档格式转换、会议纪要结构化这些都符合条件。而像“帮我设计系统架构”这种需要大量上下文和人工判断的任务写成Skill反而会限制发挥。3. 前30个Skill白写的根本原因3.1 触发条件写得太模糊Claude Code根本不知道什么时候该用我最早写的Skillfrontmatter里是这么写的--- name: code-review description: 审查代码 ---看起来没问题对吧但实际用的时候Claude Code要么不触发要么在不该触发的时候触发。原因很简单“审查代码”这四个字太模糊了。我写新代码的时候它触发我读别人代码的时候它也触发甚至我讨论代码设计的时候它还触发。后来我改成这样--- name: code-review description: 当用户要求对新增或修改的代码进行质量审查时使用重点关注并发安全、错误处理、边界条件和性能问题输出结构化审查报告 ---触发准确率立刻上来了。关键区别在于description里写清楚了“什么时候用”新增或修改的代码、“关注什么”并发安全、错误处理等、“输出什么”结构化审查报告。Claude Code根据这些信息来判断当前场景是否匹配。3.2 把Skill当提示词仓库塞了太多无关内容我有个坏习惯喜欢把各种零散的经验都塞进SKILL.md里。比如写代码审查Skill的时候我把“如何写好提交信息”“如何做代码分支管理”“如何写单元测试”全都塞进去了。结果这个Skill变得无比臃肿每次触发都要加载一大堆无关内容既浪费上下文窗口又让Claude Code抓不住重点。后来我学乖了一个Skill只做一件事。代码审查就只管代码审查提交信息生成就单独做一个Skill。如果两个Skill之间有依赖关系通过frontmatter里的dependencies字段声明而不是把内容混在一起。3.3 忽略了输出格式的约束导致每次结果都不一样前30个Skill里有将近一半是因为输出格式不稳定被我废弃的。同样的输入今天输出表格明天输出列表后天又变成一大段文字。原因是我在SKILL.md里只写了“输出审查结果”没有规定具体格式。后来我在每个Skill里都加了一段“输出模板”明确指定用什么格式、包含哪些字段、字段的顺序是什么。比如代码审查Skill的输出模板是这样的## 审查结果 | 严重等级 | 文件位置 | 问题描述 | 建议修改 | |---------|---------|---------|---------| | Critical | ... | ... | ... | | Warning | ... | ... | ... | | Info | ... | ... | ... | ## 总结 - 阻塞性问题X个 - 建议修改Y个 - 仅供参考Z个有了这个模板不管谁来用、什么时候用输出格式都是统一的。3.4 没有考虑Skill之间的协作和冲突当我写到第20个Skill的时候发现一个严重问题多个Skill同时被触发输出结果互相干扰。比如我同时有“代码审查Skill”和“安全审查Skill”审查一段代码时两个都触发了输出两份报告内容还有重叠。解决方法是引入优先级机制。在frontmatter里加一个priority字段数值越大优先级越高。当多个Skill的触发条件都满足时只执行优先级最高的那个。或者在SKILL.md里明确写清楚“本Skill不处理安全相关问题安全审查请使用security-review Skill”。4. 一个合格Skill的完整结构拆解4.1 frontmatter里必须写清楚的五个字段经过反复调整我现在每个Skill的frontmatter至少包含这五个字段--- name: code-review description: 当用户要求对新增或修改的代码进行质量审查时使用重点关注并发安全、错误处理、边界条件和性能问题 version: 1.2.0 priority: 80 dependencies: - security-review ---name是Skill的唯一标识用短横线连接的小写字母不要用中文或空格。description是最关键的字段直接决定触发准确率写法遵循“什么时候用关注什么输出什么”的公式。version用于版本管理每次修改都递增方便回滚。priority控制多个Skill同时匹配时的执行顺序。dependencies声明依赖的其他SkillClaude Code会先加载依赖项。注意description不要写得太长控制在200字以内。太长了Claude Code反而抓不住重点触发准确率会下降。4.2 SKILL.md正文的黄金三段式frontmatter之后是SKILL.md的正文。我试过各种结构最后固定为三段式角色与目标、执行流程、输出规范。第一段“角色与目标”用两三句话说明这个Skill是干什么的、以什么身份执行、最终目标是什么。比如代码审查Skill的开头是“你是一名有十年经验的后端工程师负责对新增或修改的代码进行质量审查。你的目标是发现潜在的并发安全问题、错误处理缺陷、边界条件遗漏和性能瓶颈并给出可操作的修改建议。”第二段“执行流程”是核心按步骤列出审查过程。每一步都要具体到可执行的程度不要写“仔细检查代码”这种空话而要写“检查所有共享变量的读写是否加了锁检查所有可能返回错误的函数调用是否处理了错误分支”。第三段“输出规范”规定输出格式。可以直接给一个模板也可以描述字段和结构。我倾向于给模板因为模板的约束力更强。4.3 用MCP扩展Skill的能力边界有些Skill需要访问外部系统才能完成工作。比如“Figma设计稿转代码”这个Skill需要读取Figma文件“数据库查询优化”这个Skill需要连接数据库查看执行计划。这些能力通过MCP来提供。MCP的配置不在SKILL.md里而是在Claude Code的全局配置或项目配置中。SKILL.md里只需要声明“本Skill需要访问Figma MCP”然后在执行流程中调用相应的MCP工具即可。我踩过的坑是在SKILL.md里硬编码MCP的连接信息。这样做的后果是Skill无法在不同环境之间迁移换一台机器就要改一遍。正确做法是把MCP配置抽离到环境变量或独立的配置文件中SKILL.md只引用配置名称。4.4 一个完整示例代码审查Skill把上面的内容串起来一个完整的代码审查Skill长这样--- name: code-review description: 当用户要求对新增或修改的代码进行质量审查时使用重点关注并发安全、错误处理、边界条件和性能问题 version: 1.2.0 priority: 80 --- 你是一名有十年经验的后端工程师负责对新增或修改的代码进行质量审查。你的目标是发现潜在的并发安全问题、错误处理缺陷、边界条件遗漏和性能瓶颈并给出可操作的修改建议。 ## 执行流程 1. 读取用户指定的代码文件或代码片段 2. 检查所有共享变量的读写是否加了适当的锁或使用了线程安全的数据结构 3. 检查所有可能返回错误的函数调用是否处理了错误分支 4. 检查所有循环和条件判断的边界条件是否覆盖完整 5. 检查是否存在明显的性能问题如循环内重复计算、不必要的内存分配 6. 将发现的问题按严重等级分类 ## 输出规范 按以下模板输出 | 严重等级 | 文件位置 | 问题描述 | 建议修改 | |---------|---------|---------|---------| | Critical | ... | ... | ... | | Warning | ... | ... | ... | | Info | ... | ... | ... | 最后给出总结阻塞性问题X个建议修改Y个仅供参考Z个。这个Skill我用了三个月触发准确率在90%以上输出格式稳定基本不需要手动调整。5. 从零开始写一个Skill的完整实操5.1 环境准备与目录结构Claude Code的Skill存放位置有两个全局目录和项目目录。全局目录下的Skill对所有项目生效项目目录下的Skill只对当前项目生效。我一般把通用性强的Skill放在全局目录把项目相关的Skill放在项目目录。全局目录的路径根据操作系统不同有所差异。在Linux和macOS上通常是~/.claude/skills/在Windows上是%USERPROFILE%\.claude\skills\。每个Skill一个子目录子目录名就是Skill的name字段值。子目录里至少包含一个SKILL.md文件如果有辅助脚本或模板文件也放在这个子目录里。# 创建全局Skill目录 mkdir -p ~/.claude/skills/code-review # 创建SKILL.md touch ~/.claude/skills/code-review/SKILL.md提示Skill的name字段必须和子目录名完全一致包括大小写。不一致的话Claude Code找不到这个Skill。5.2 编写frontmatter的实操要点写frontmatter的时候我习惯先写description因为这是最需要反复打磨的部分。写完之后自己读一遍问自己三个问题这个描述能不能让我在正确的场景下想到用这个Skill能不能让我在错误的场景下不想到用这个Skill如果换一个人来看他能不能理解什么时候该用如果三个问题的答案都是肯定的description就合格了。如果有一个是否定的就继续改。version字段我建议从1.0.0开始每次修改递增。priority字段的取值范围是0到100默认50。数值越大优先级越高。我一般把通用性强的Skill设成60到70把特定场景的Skill设成80到90。5.3 正文撰写的三个关键技巧第一个技巧用第二人称“你”来写而不是“Claude”或“助手”。这样写出来的内容更像是在给一个具体的人下指令执行效果更好。第二个技巧每个步骤都以动词开头。不要写“代码中的并发安全问题”而要写“检查代码中的并发安全问题”。动词开头的步骤更明确不容易被忽略。第三个技巧在输出规范里给具体模板不要只描述格式。模板的约束力比描述强得多。如果输出内容比较复杂可以给多个模板分别对应不同的场景。5.4 测试与迭代怎么知道Skill写得好不好写完一个Skill之后我会做三轮测试。第一轮是正向测试在应该触发这个Skill的场景下使用看它是否触发、输出是否符合预期。第二轮是负向测试在不应该触发这个Skill的场景下使用看它是否误触发。第三轮是边界测试在模棱两可的场景下使用看它的表现是否合理。三轮测试都通过之后才算是一个合格的Skill。我前30个Skill之所以白写就是因为跳过了测试环节写完直接用用出问题再改改来改去最后废弃。6. 常见问题与排查技巧实录6.1 Skill不触发怎么办这是最常见的问题。排查顺序如下先检查目录结构和文件名。Skill的子目录名必须和frontmatter里的name字段完全一致SKILL.md的文件名必须是大写的SKILL.md不能是skill.md或Skill.md。再检查frontmatter的格式。---必须独占一行字段名和值之间用冒号加空格分隔缩进用空格不用Tab。YAML对格式很敏感一个缩进错误就可能导致整个frontmatter解析失败。最后检查description的写法。如果description写得太模糊或太宽泛Claude Code可能判断当前场景不匹配。试着把description改得更具体加入“当用户要求...时使用”这样的触发条件描述。6.2 Skill触发了但输出不符合预期先看SKILL.md的正文里有没有明确的输出规范。如果没有Claude Code就会自由发挥每次输出都不一样。加上输出模板之后这个问题基本能解决。如果加了输出模板还是不稳定检查模板本身是否足够具体。比如“输出一个表格”就不如“输出一个包含严重等级、文件位置、问题描述、建议修改四列的表格”具体。还有一种可能是Skill之间的干扰。检查是否有其他Skill同时被触发如果有调整priority字段或修改description来消除歧义。6.3 Skill之间互相冲突怎么处理冲突的表现形式有两种一种是多个Skill同时触发输出结果混在一起另一种是一个Skill的输出被另一个Skill覆盖或修改。第一种情况的解决方法是调整priority。把更重要的Skill的priority设高一些Claude Code会优先执行它忽略其他Skill。第二种情况的解决方法是明确职责边界。在SKILL.md里写清楚“本Skill不处理XX问题XX问题请使用YY Skill”。同时检查两个Skill的description是否有重叠如果有修改description让它们各自覆盖不同的场景。6.4 MCP连接失败怎么排查MCP连接失败通常有三个原因配置错误、服务未启动、权限不足。配置错误最常见。检查MCP的配置文件路径是否正确字段名是否拼写正确连接信息是否完整。我遇到过因为把command写成cmd导致MCP无法启动的情况排查了半天才发现。服务未启动的话检查MCP对应的后台服务是否在运行。有些MCP需要单独启动一个服务进程如果进程挂了Skill调用MCP时就会失败。权限不足的情况比较少见但一旦遇到就很难排查。检查当前用户是否有权限访问MCP所需的资源比如数据库连接、文件读取等。6.5 常见问题速查表问题现象可能原因排查方法解决方案Skill不触发目录名与name不一致检查子目录名和frontmatter改成完全一致Skill不触发description太模糊读一遍description加入触发条件描述输出格式不稳定缺少输出模板检查SKILL.md正文添加具体输出模板多个Skill同时触发priority相同或未设置检查各Skill的priority调整priority区分优先级MCP连接失败配置字段拼写错误逐字段检查配置文件修正拼写错误MCP连接失败后台服务未启动检查服务进程状态启动服务进程Skill加载慢SKILL.md内容过多检查文件大小拆分Skill或精简内容7. 让Skill真正好用的几个进阶思路7.1 用组合Skill替代大而全的Skill我早期喜欢写“万能Skill”一个Skill里塞了代码审查、提交信息生成、文档撰写、测试用例生成等一堆功能。结果就是每个功能都做不好触发条件写不清楚输出格式也统一不了。后来我改成组合模式每个Skill只做一件事通过dependencies字段声明依赖关系。比如“提交信息生成Skill”依赖“代码审查Skill”执行的时候先审查代码再根据审查结果生成提交信息。这样每个Skill都很轻量维护起来也方便。7.2 给Skill加上版本管理和回滚机制Skill写多了之后修改一个Skill可能会影响其他依赖它的Skill。我现在的做法是每次修改Skill都递增version字段同时在Skill目录下保留历史版本的备份。如果新版本出了问题可以快速回滚到旧版本。备份的方式很简单在Skill目录下建一个versions子目录每次修改前把当前的SKILL.md复制进去文件名加上版本号。比如SKILL-v1.1.0.md、SKILL-v1.2.0.md。需要回滚的时候把对应版本的文件复制回SKILL.md即可。7.3 用Skill解决“去AI味”的问题Claude Code默认的输出风格偏正式、偏书面化有时候读起来像机器写的。我专门做了一个“去AI味Skill”在输出规范里明确要求用短句、用口语化表达、避免“通过...可以...”这类句式、避免“总之”“综上所述”这类总结词、每段不超过四行。这个Skill我放在所有其他Skill的dependencies里这样所有Skill的输出都会经过它处理整体风格统一了很多。7.4 把Skill当成团队资产来维护一个人用Skill和团队用Skill是两回事。团队用的时候Skill的description要写得更明确因为不同人的使用场景可能有差异。输出模板也要更严格确保不同人用同一个Skill得到的结果是一致的。我现在的做法是每个Skill都有一个维护者负责定期检查触发准确率和输出质量。如果发现某个Skill的触发准确率下降就及时调整description。如果发现输出格式不稳定就检查输出模板是否需要更新。8. 我踩过的几个典型坑第一个坑在SKILL.md里写“请仔细检查代码”。这种空话没有任何约束力Claude Code不知道该检查什么。后来我改成“检查所有共享变量的读写是否加了锁”效果立刻不一样了。第二个坑把Skill的description写得太短。我一开始觉得description越短越好后来发现太短了触发准确率反而低。现在我的description基本都在100到200字之间把触发条件、关注点、输出内容都写清楚。第三个坑忽略Skill之间的依赖关系。我有个“测试用例生成Skill”依赖“代码审查Skill”但一开始没有声明依赖导致测试用例生成的时候没有先审查代码生成的用例质量很差。加上dependencies之后问题解决了。第四个坑在Windows上用了Linux的路径写法。Claude Code在Windows上的Skill目录路径和Linux不一样我一开始用~/.claude/skills/结果找不到目录。后来改成%USERPROFILE%\.claude\skills\才正常。第五个坑MCP配置写在SKILL.md里。这样做的后果是Skill无法在不同环境之间迁移。后来我把MCP配置抽离到独立的配置文件中SKILL.md只引用配置名称迁移的时候只需要改配置文件。9. 关于Skill数量和质量的一点个人体会写了50个Skill之后我最大的体会是Skill的价值不在于数量而在于质量。一个写得好的Skill能顶十个写得差的。我现在保留的20个Skill每一个都经过反复测试和迭代触发准确率在90%以上输出格式稳定基本不需要手动调整。如果你刚开始写Skill我的建议是先写三个把这三个写到极致再考虑扩展。这三个可以是代码审查、提交信息生成、文档格式转换。这三个场景高频、流程固定、输出可标准化最适合用来练手。等你把这三个Skill写好了自然就知道怎么写第四个、第五个了。前30个白写的经历告诉我Skill写作是一门需要练习的手艺没有捷径但有很多坑可以避开。希望这篇内容能帮你少走一些弯路。