1. 从 50 个 Skill 里踩出来的血泪教训我在过去几个月里陆陆续续写了 50 个 Claude Code Skill从最开始照着文档瞎写到后来慢慢摸出规律中间踩的坑实在太多了。最扎心的一个发现是前 30 个基本等于白写。不是功能跑不起来而是它们要么重复造轮子要么结构混乱到我自己过两周都看不懂要么就是把本该放在项目配置里的东西硬塞进 Skill 里。这篇文章就是把这 50 个 Skill 的实战经验完整拆开告诉你哪些坑可以提前绕过去哪些设计思路能让你的 Skill 从能跑变成好用。如果你正在用 Claude Code或者刚开始接触 Skill 这个概念这篇文章会帮你省下大量试错时间。我会从 Skill 的本质讲起拆解 SKILL.md 的结构、frontmatter 的写法、和 MCP 的配合方式再给出可以直接抄的模板和排查清单。不管你是刚安装完 Claude Code 的新手还是已经写过几个 Skill 想进阶的老手都能从里面找到能直接用的东西。先说一个最核心的认知Skill 不是插件不是脚本也不是简单的提示词模板。它更像是给 Claude Code 这个通用助手装上一套专业操作手册让它在特定场景下知道该按什么流程、用什么工具、遵守什么约束来干活。理解这一点后面所有的设计决策都会顺很多。2. Skill 到底是什么先搞清楚定位再动手2.1 Skill 和普通提示词的本质区别很多人第一次接触 Skill会把它当成存起来的提示词。我一开始也是这么理解的结果写出来的东西就是一堆指令堆砌Claude Code 执行起来时好时坏。后来才明白Skill 的核心价值不在于告诉 Claude 做什么而在于定义一套可复用的工作流。普通提示词是你每次对话时临时给的指令用完就没了。Skill 则是持久化的、结构化的能力单元它包含几个关键要素触发条件什么时候该用这个 Skill、执行流程按什么步骤做、工具依赖需要调用哪些工具或 MCP、输出规范结果应该长什么样。这四样东西缺一个Skill 就会变得不可靠。举个例子我早期写过一个代码审查 Skill内容就是请审查以下代码找出问题并给出建议。这东西看起来没毛病但实际用起来效果很差因为 Claude 每次审查的角度都不一样有时候关注性能有时候关注可读性输出格式也飘忽不定。后来我把它重写成结构化的 Skill明确定义了审查维度安全性、性能、可维护性、边界条件、每个维度的检查清单、以及固定的输出格式效果立刻稳定了。2.2 SKILL.md 的文件结构长什么样一个标准的 Skill 就是一个目录核心文件是SKILL.md。这个文件分两部分顶部的 frontmatter 元数据和下面的正文内容。frontmatter 用 YAML 格式写在---之间最关键的字段是name和description。name是 Skill 的唯一标识description决定了 Claude 什么时候会触发这个 Skill。我见过太多人把 description 写得含糊不清结果 Skill 要么不触发要么在不该触发的时候乱触发。正文部分就是具体的指令内容可以用 Markdown 组织支持标题、列表、代码块等。这里有个经验正文不要写得太长太啰嗦Claude 的上下文是有限的Skill 内容越长留给实际任务的空间就越少。我一般控制在 500 到 1500 字之间把最关键的流程和约束写清楚就行。2.3 为什么前 30 个 Skill 会白写回头看那 30 个失败的 Skill问题集中在几个方面。第一是定位错误把本该用 MCP 解决的事情硬写成 Skill比如需要实时访问外部数据的场景Skill 根本做不到。第二是粒度过细一个 Skill 只做一件极小的事导致需要写几十个 Skill 才能完成一个完整任务维护成本爆炸。第三是缺乏复用设计每个 Skill 都是独立的一次性产物没有考虑参数化和组合。最典型的一个例子是我写的生成 commit messageSkill。第一版就是简单的一句根据 diff 生成规范的 commit message结果生成的格式五花八门。第二版加了格式约束好了一点但还是经常不符合团队规范。直到第三版我才想明白应该把团队的 commit 规范完整写进去包括类型前缀、scope 规则、描述长度限制、以及几个正反示例。这一版才真正可用。3. 写 Skill 前必须想清楚的五件事3.1 这个需求真的适合用 Skill 吗不是所有需求都适合做成 Skill。判断标准很简单如果这个任务需要实时数据、需要复杂的外部 API 调用、或者需要长时间运行的状态管理那它更适合用 MCP 或者直接写脚本。Skill 最擅长的是流程性、知识性、规范性的任务比如代码审查、文档生成、格式转换、按固定流程排查问题。我踩过的一个坑是写了个查询数据库Skill想让 Claude 能直接查数据。结果发现 Skill 根本没法维持数据库连接每次都要重新配置还不如直接用 MCP 封装一个数据库工具。后来我把这个 Skill 删了改用 MCP 方案问题立刻解决。3.2 触发条件怎么设计才精准description 字段是 Skill 的门面它决定了 Claude 在什么情况下会加载这个 Skill。写得太宽泛Skill 会到处乱触发写得太窄又该触发的时候不触发。我的经验是description 里要包含三类信息动作这个 Skill 做什么、场景什么情况下用、关键词用户可能提到的词。比如一个API 文档生成Skill 的 description 可以写成根据代码中的路由定义和注释生成符合 OpenAPI 规范的接口文档。当用户需要为后端接口生成文档、更新 API 说明、或检查接口文档完整性时使用。这样写的好处是Claude 能通过生成文档API 说明接口文档这些关键词准确匹配到场景不会在无关的时候触发。3.3 输出格式要不要严格约束这个问题我纠结了很久。早期我倾向于让 Claude 自由发挥觉得这样更灵活。但实际用下来发现输出格式不固定的 Skill 几乎没法用在自动化流程里因为下游处理没法预期结果长什么样。后来我改成严格约束输出格式用模板加示例的方式明确告诉 Claude 应该输出什么结构。比如要求输出 JSON 就给出完整的 schema要求输出 Markdown 就给出标题层级和字段顺序。这样虽然牺牲了一点灵活性但换来的是可靠性值得。3.4 要不要依赖 MCPMCP 是 Claude Code 连接外部工具的协议它让 Claude 能调用文件系统、数据库、浏览器等各种能力。Skill 和 MCP 的关系是Skill 定义做什么和怎么做MCP 提供用什么工具做。我的建议是如果任务需要访问外部资源优先考虑 MCP。Skill 里只需要写清楚调用哪个 MCP 工具、传什么参数、怎么处理返回结果就行。不要把本该 MCP 做的事硬塞进 Skill那样只会让 Skill 变得臃肿且不可靠。3.5 怎么判断 Skill 写得好不好我总结了一个简单的判断标准把 Skill 交给一个完全不了解背景的同事他能不能照着 Skill 的描述在 Claude Code 里复现出稳定的结果。如果能说明 Skill 写得合格如果不能说明还有模糊地带需要补充。另一个标准是看 Skill 的复用率。好的 Skill 应该能在多个项目、多个场景下重复使用。如果一个 Skill 只在某个特定项目里用过一次就再也没用过那它大概率设计得不够通用。4. 一个高质量 Skill 的完整拆解4.1 从零写一个代码审查 Skill我拿一个实际在用的代码审查Skill 来完整拆解这个 Skill 是我迭代了五版之后才稳定下来的。首先是目录结构我习惯这样组织skills/ code-review/ SKILL.md templates/ review-output.md examples/ good-review.md bad-review.mdSKILL.md是主文件templates放输出模板examples放正反示例。这种结构的好处是主文件保持简洁细节内容按需加载。4.2 frontmatter 的写法细节这个 Skill 的 frontmatter 是这样的--- name: code-review description: 对代码进行结构化审查覆盖安全性、性能、可维护性和边界条件四个维度。当用户提交代码片段、文件或 PR 需要审查或提到代码审查review检查代码时使用。 ---注意 description 里明确列出了四个审查维度这样 Claude 在触发时就知道这个 Skill 的覆盖范围。同时列出了触发关键词提高匹配准确率。4.3 正文流程的分步设计正文部分我分成几个明确的步骤每一步都有具体的操作要求第一步是识别输入类型判断用户给的是单个文件、代码片段还是整个 PR。不同类型的输入审查策略不一样。第二步是逐维度审查按照安全性、性能、可维护性、边界条件的顺序每个维度用固定的检查清单过一遍。这里我会把每个维度的检查项列出来比如安全性维度包括输入验证、SQL 注入、XSS、敏感信息泄露、权限检查等。第三步是分级标注问题把发现的问题按严重程度分成 blocker、major、minor 三级。blocker 是必须修复的major 是建议修复的minor 是可以忽略的。第四步是生成结构化输出按照模板输出审查结果包含问题列表、修复建议、以及整体评价。4.4 输出模板的设计思路输出模板我放在templates/review-output.md里内容大致是这样## 审查结果 ### 整体评价 [一句话总结代码质量] ### 问题列表 #### Blocker - [文件:行号] 问题描述 - 原因 - 建议 #### Major ... #### Minor ... ### 亮点 [值得肯定的地方]这个模板的好处是结构固定下游可以直接解析。同时保留了亮点部分避免审查结果全是负面反馈这在团队协作里很重要。4.5 正反示例的作用examples目录里我放了两个示例一个是好的审查输出一个是差的。好的示例展示了完整的结构、具体的建议、以及恰当的语气。差的示例展示了常见问题比如问题描述模糊、建议不可操作、语气过于苛刻。这两个示例的作用是给 Claude 提供参照物让它在生成输出时有个明确的对标。实测下来加了示例之后输出质量的稳定性提升非常明显。5. 那些让我返工的坑和排查方法5.1 Skill 不触发怎么办这是最常见的问题。我遇到过好几次写完 Skill 但 Claude 完全不理的情况。排查思路是这样的先检查 frontmatter 格式是否正确YAML 对缩进和符号很敏感一个多余的空格都可能导致解析失败。然后检查 description 是否包含用户可能提到的关键词如果用户说帮我看看这段代码而你的 description 里只有代码审查那可能匹配不上。最后检查 Skill 的存放位置是否正确不同版本的 Claude Code 对 Skill 目录的要求可能不一样。我踩过最坑的一次是 frontmatter 里用了中文冒号看起来没问题但解析直接失败。这种问题很难发现建议写完 Skill 后先用一个简单的测试用例验证一下。5.2 Skill 触发太频繁怎么办反过来有些 Skill 会在不该触发的时候乱触发。这通常是 description 写得太宽泛导致的。比如一个文档生成Skill如果 description 只写生成文档那用户说帮我写个 README时也可能触发。解决办法是在 description 里加上明确的场景限定比如当用户需要为代码生成 API 文档时使用把范围收窄。同时可以在正文里加一句如果输入不满足以下条件请忽略本 Skill给 Claude 一个主动跳过的选项。5.3 输出格式不稳定怎么办这个问题我折腾了很久。即使写了模板Claude 有时候还是会自由发挥。后来发现几个关键点模板要足够具体不能只说输出 Markdown 格式而要给出完整的结构示例。示例要放在正文里不能只放在单独的文件里因为 Claude 不一定每次都会去读那些文件。约束要用强指令比如必须严格按照以下格式输出不得增删字段而不是建议按照以下格式。5.4 Skill 之间冲突怎么办当你有多个 Skill 时可能会出现两个 Skill 都想处理同一个请求的情况。我的经验是在 description 里明确写出不适用场景主动排除掉不该触发的范围。比如代码审查 Skill 可以写不适用于代码生成、重构建议等场景把边界划清楚。5.5 常见问题速查表问题现象可能原因排查方法Skill 完全不触发frontmatter 格式错误检查 YAML 缩进和符号Skill 触发但结果不对正文指令模糊补充具体步骤和示例输出格式飘忽模板不够具体给出完整结构示例多个 Skill 冲突description 范围重叠明确写出不适用场景Skill 加载慢正文内容过长拆分或精简内容MCP 调用失败工具名或参数错误检查 MCP 配置和工具签名6. 让 Skill 真正好用的进阶技巧6.1 参数化设计让 Skill 更通用早期我写的 Skill 都是硬编码的比如审查 Python 代码。后来发现这样复用性太差改成参数化之后一个 Skill 能覆盖多种场景。参数化的做法是在正文里定义变量比如{{language}}、{{framework}}、{{strictness}}然后在 description 里说明这些参数怎么传。Claude 会根据上下文自动填充这些变量。这样同一个 Skill 就能处理 Python、JavaScript、Go 等多种语言的审查。6.2 用 MCP 扩展 Skill 的能力边界Skill 本身只能做知识性的工作要访问外部资源必须靠 MCP。我常用的几个 MCP 组合是文件系统 MCP 让 Skill 能读写文件Git MCP 让 Skill 能查看提交历史浏览器 MCP 让 Skill 能抓取网页内容。关键是要在 Skill 里明确写出调用哪个 MCP 工具、传什么参数。比如使用 filesystem MCP 的 read_file 工具读取目标文件参数为文件路径。这样 Claude 就知道该调用什么不会瞎猜。6.3 版本管理和迭代策略Skill 也是代码需要版本管理。我的做法是在 Skill 目录里放一个CHANGELOG.md记录每次修改的原因和内容。同时在 frontmatter 里加一个version字段方便追踪。迭代策略上我建议小步快跑。每次只改一个点改完立刻测试确认有效再继续。不要一次性大改那样出问题很难定位。6.4 团队协作中的 Skill 规范如果是团队使用Skill 需要统一规范。我们团队的做法是所有 Skill 必须包含 description、正文流程、输出模板、至少一个示例。命名统一用小写加连字符比如code-review、api-doc-gen。每个 Skill 必须有负责人负责维护和更新。另外建议建一个 Skill 索引文档列出所有 Skill 的名称、用途、负责人、最后更新时间。这样新人能快速了解团队有哪些能力可用。6.5 实测有效的三个小技巧第一个技巧是在 Skill 开头加一句在开始之前先确认以下前提条件是否满足让 Claude 先做一次自检避免在不满足条件的情况下硬执行。第二个技巧是在 Skill 结尾加一句完成后请简要说明执行了哪些步骤这样你能看到 Claude 的实际执行路径方便排查问题。第三个技巧是把常用的 Skill 组合成一个工作流 Skill比如代码提交前检查可以组合代码审查、测试运行、commit message 生成三个 Skill一次调用完成整个流程。7. 我个人的一些体会写了 50 个 Skill 之后最大的感受是Skill 的质量不取决于你写了多少而取决于你想得有多清楚。前 30 个白写的根本原因是我在没想清楚需求、场景、输出格式的情况下就急着动手结果写出来的东西自己都不想用。现在我写 Skill 的流程固定下来了先用一句话说清楚这个 Skill 解决什么问题然后列出触发场景和不适用场景再设计输出格式最后才动手写正文。这个顺序看起来慢但实际上省下了大量返工时间。另外一点体会是Skill 不是越多越好。我现在维护的 Skill 只有十几个但每一个都是经过多次迭代、在多个项目里验证过的。与其写一堆半成品不如把几个核心 Skill 打磨到真正好用。这个道理说起来简单但真要做到需要克制多写几个的冲动。