1. 从“写了50个Skill”到“前30个白写”一个真实的能力成长曲线我大概是在三个月前开始密集写 Claude Code Skill 的。那时候刚把 Claude Code 装好摸清了SKILL.md的基本结构知道了 frontmatter 里可以写name、description知道了正文里可以塞指令、示例、约束条件于是整个人进入一种“我什么都能封装”的亢奋状态。第一个 Skill 写的是代码审查第二个是提交信息生成第三个是接口文档补全第四个是数据库迁移脚本检查……一路写到第三十个的时候我回头翻了一遍发现一个很尴尬的事实这三十个 Skill 里真正每天在用的不超过五个剩下的要么被我自己忘了要么触发条件写得一塌糊涂要么和 Claude Code 自带的默认行为高度重叠纯属重复造轮子。这个标题里的“白写”不是自嘲是一个很具体的判断。前三十个 Skill 的问题集中在几个地方把 Skill 当 Prompt 模板写、把 Skill 当脚本写、把 Skill 当知识库写唯独没有把 Skill 当成“一个可被模型稳定调用的能力单元”来写。Skill 的本质不是“我告诉模型该怎么做”而是“我定义了一个边界清晰、触发明确、输出可预期的行为契约”。这个认知转变是我写到第四十个左右才真正完成的。这篇文章想做的事情很直接把我在 Claude Code Skill 这条路上踩过的坑、总结出的结构方法、以及那些真正让 Skill 从“能跑”变成“好用”的细节完整地摊开讲一遍。关键词里的SKILL.md、frontmatter、MCP、agent skill、skill开发指南这些概念我会在对应的章节里逐一拆解不堆术语讲清楚每个东西为什么存在、什么时候该用、什么时候不该用。如果你刚开始接触 Claude Code或者已经写了十几个 Skill 但感觉效果不稳定这篇内容应该能帮你省下不少返工时间。2. 前三十个Skill到底“白”在哪里四类典型失败模式2.1 把Skill写成Prompt模板触发条件模糊导致调用不稳定最常见的失败模式是把 Skill 当成一个“高级一点的 Prompt 模板”。比如我早期写过一个叫code-review的 Skill正文大概是这样的--- name: code-review description: 审查代码质量 --- 请审查用户提供的代码关注以下方面 - 命名规范 - 错误处理 - 边界条件 - 性能问题这个 Skill 能跑但问题在于description写得太泛。“审查代码质量”这五个字模型在什么情况下应该调用它用户说“帮我看看这段代码”算不算用户说“这个函数有没有问题”算不算用户只是贴了一段代码什么都没说算不算触发条件模糊的直接后果是该调用的时候不调用不该调用的时候乱调用。我后来统计过这个 Skill 的实际触发率不到我预期的三分之一大部分时候模型直接用自己的默认能力回答了根本没走 Skill。正确的做法是把description写成“什么时候用”而不是“这是什么”。比如改成“当用户提供了一段代码并明确要求进行代码审查、质量检查、或询问代码是否存在问题时使用”。这句话里包含了触发场景用户提供代码、触发意图要求审查/检查/询问问题模型在匹配时就有了明确的判断依据。2.2 把Skill写成脚本过度依赖确定性逻辑第二类失败模式走向另一个极端把 Skill 当成 Shell 脚本或者 Python 脚本来写试图用确定性的步骤控制模型的行为。我写过一个db-migration的 Skill正文里列了十几步1. 检查 migrations 目录是否存在 2. 读取最新的 migration 文件 3. 对比 schema 差异 4. 生成新的 migration 文件 5. 运行测试 6. 如果测试失败回滚 ...写完之后我发现这个 Skill 在实际使用中非常僵硬。因为真实的数据库迁移场景千变万化有时候用户只是想让我看看某个 migration 写得对不对有时候是想让我生成一个新的有时候是想排查一个已经失败的迁移。用一个固定的步骤序列去覆盖所有场景结果就是每个场景都覆盖得不好。Skill 不是脚本它应该定义“目标和约束”而不是“步骤序列”。模型有能力根据当前上下文决定具体怎么做你把它框死反而限制了它的发挥。2.3 把Skill写成知识库信息过载稀释了核心指令第三类失败模式是信息过载。我写过一个api-convention的 Skill想把团队所有的接口规范都塞进去命名规则、错误码规范、分页约定、鉴权方式、版本管理、日志格式……洋洋洒洒写了两千多字。结果这个 Skill 的调用效果反而很差因为核心指令被大量背景信息稀释了。模型在读取 Skill 内容时注意力是有限的你塞进去的每一条无关信息都在抢占本该用于核心任务的注意力预算。后来我把这个 Skill 拆成了三个api-naming只管命名api-error只管错误码api-pagination只管分页。每个 Skill 的正文控制在三百字以内只保留最核心的规则和一到两个正反示例。拆分之后每个 Skill 的触发准确率和输出质量都明显提升。2.4 把Skill当万能钥匙和MCP、内置能力的边界不清第四类失败模式是没有搞清楚 Skill 和 MCP、和 Claude Code 内置能力之间的边界。我早期写过一个web-search的 Skill试图让模型通过某种方式去搜索网页。后来才明白搜索这件事应该由 MCP Server 来提供工具能力Skill 负责的是“什么时候该搜、搜完怎么用”而不是“怎么搜”。这两者的分工是MCP 提供原子能力工具调用Skill 提供行为编排什么时候调用、调用后如何处理。同理很多我早期写的 Skill其实 Claude Code 的内置能力已经覆盖了比如基本的文件读写、代码解释、简单的重构建议。这些场景根本不需要 Skill直接对话就行。Skill 应该用在那些“需要特定领域知识 需要稳定输出格式 需要明确触发边界”的场景而不是把所有能想到的事情都封装一遍。失败模式典型表现根本原因修复方向Prompt模板化触发不稳定该调不调description 写的是“是什么”而非“何时用”重写 description明确触发场景和意图脚本化流程僵硬场景覆盖差用步骤序列替代目标约束改为定义目标和边界让模型自主决策知识库化输出质量下降信息过载稀释核心指令拆分为多个单一职责的 Skill边界不清和内置能力/MCP重复没想清楚 Skill 的定位明确 Skill 负责编排MCP 负责工具3. 一个Skill从“能跑”到“好用”的结构拆解3.1 frontmatter不是装饰name和description的写法直接决定触发率SKILL.md的 frontmatter 里最核心的两个字段是name和description。很多人包括早期的我把这两个字段当成“元数据”随便填实际上它们是模型判断是否调用这个 Skill 的唯一依据。name要短、要唯一、要能一眼看出用途比如commit-msg、api-error、db-migrate这种。不要用my-awesome-skill或者helper这种无信息量的名字。description的写法有一个很实用的公式“当[触发场景]时用于[核心动作]输出[预期结果]”。举个例子--- name: commit-msg description: 当用户要求生成 Git 提交信息、或完成代码修改后需要提交时使用。基于 git diff 内容生成符合 Conventional Commits 规范的提交信息输出单行标题加可选的正文说明。 ---这个 description 里包含了三个关键信息触发场景要求生成提交信息/完成修改后、核心动作基于 diff 生成、预期结果符合规范的提交信息。模型在匹配时只要用户的意图落在这个范围内就会稳定触发。提示description里不要写“这是一个用于……的 Skill”这种废话直接写触发条件和输出。模型不需要你自我介绍它需要的是判断依据。3.2 正文的黄金结构目标、约束、示例、反例frontmatter 之后SKILL.md的正文结构我摸索出了一个比较稳定的四段式目标、约束、示例、反例。目标段用一两句话说明这个 Skill 要达成什么。比如 commit-msg 的目标段“根据当前 git diff 的内容生成一条符合 Conventional Commits 规范的提交信息。”约束段列出必须遵守的规则。比如“标题不超过 72 个字符类型限定在 feat/fix/docs/refactor/test/chore 之内如果改动涉及多个类型选择影响最大的那个正文只在改动较复杂时添加用来说明‘为什么’而不是‘做了什么’。”示例段给出一到两个正例。示例的作用不是让模型照抄而是让模型理解“好的输出长什么样”。比如给一个feat(auth): add token refresh mechanism的例子模型就能理解格式和粒度。反例段给出一到两个错误示范。反例往往比正例更有价值因为它明确了边界。比如“不要写成update code这种无信息量的标题不要在标题里写句号不要用中文类型前缀。”这四段加起来正文控制在 300 到 500 字之间效果最好。超过 800 字核心指令就开始被稀释了。3.3 示例和反例的写法让模型理解边界而不是照抄示例的写法有一个常见误区给一个完整的、复杂的例子希望模型能举一反三。实际上示例越简单、越聚焦模型理解得越准确。我早期写过一个api-doc的 Skill示例里给了一个包含十几个字段的完整接口文档结果模型每次输出都试图凑够十几个字段哪怕实际接口只有三个字段。后来我把示例改成极简版一个只有两个字段的接口展示格式和注释风格。模型反而能根据实际情况灵活扩展。反例也是同理不要给一个“完全错误”的例子而是给一个“看起来对但差一点”的例子这样模型才能理解微妙的边界在哪里。3.4 什么时候该拆成多个Skill单一职责的判定标准一个很实用的判定标准如果你发现这个 Skill 的正文里出现了“如果……则……否则……”这种分支结构超过两次就该考虑拆分了。因为每个分支本质上是一个独立的场景独立场景应该有独立的触发条件。另一个标准是触发场景的数量。如果一个 Skill 的 description 里需要用“或”连接超过三个触发场景说明它承担了太多职责。比如“当用户要求生成提交信息、或要求审查代码、或要求补全文档时使用”这种 Skill 几乎不可能稳定触发因为三个场景的意图差异太大模型很难用一个统一的判断标准来匹配。拆分的粒度可以参考这个原则一个 Skill 对应一个明确的用户意图。生成提交信息是一个意图审查代码是另一个意图补全文档是第三个意图。每个意图一个 Skill触发准确率和输出质量都会显著提升。4. Skill、MCP、内置能力三者边界与协作方式4.1 MCP提供工具Skill提供编排分工的本质MCPModel Context Protocol解决的是“模型能调用什么工具”的问题。比如 Playwright MCP 让模型能操作浏览器Chrome DevTools MCP 让模型能读取页面性能数据数据库 MCP 让模型能执行 SQL 查询。MCP 提供的是原子能力是“手”和“脚”。Skill 解决的是“模型在什么情况下、按什么规则使用这些工具”的问题。比如一个web-audit的 Skill它定义的是当用户要求审查网页性能时先通过 Chrome DevTools MCP 采集性能数据再按照特定的指标阈值进行分析最后输出结构化的报告。Skill 提供的是行为编排是“大脑”的决策逻辑。这两者的关系是互补的不是替代的。我早期犯的错误是试图用 Skill 去实现本该由 MCP 提供的工具能力比如写一个 Skill 让模型“去搜索网页”。正确的做法是搜索能力由搜索类 MCP 提供Skill 只负责定义“什么时候搜、搜完怎么筛选、怎么呈现”。4.2 什么时候用Skill什么时候直接对话一个很实际的判断标准如果你发现自己在重复输入同一段指令而且这段指令的输出格式有稳定要求那就该写成 Skill。比如你每次让模型生成提交信息都要打一遍“请按照 Conventional Commits 规范生成”那就写成 Skill。如果你只是偶尔让模型解释一段代码那就直接对话没必要封装。另一个标准是触发频率和一致性要求的乘积。触发频率高、一致性要求也高的场景最适合 Skill。触发频率低但一致性要求高的场景也可以写 Skill但优先级没那么高。触发频率高但一致性要求低的场景直接对话更灵活。4.3 一个真实案例用Skill编排Playwright MCP完成页面巡检我写过一个page-audit的 Skill配合 Playwright MCP 使用。这个 Skill 的 description 是“当用户要求对某个页面进行可访问性检查、性能检查、或截图对比时使用。通过 Playwright MCP 打开页面采集关键指标输出结构化报告。”正文里定义了检查项和阈值LCP 超过 2.5 秒标记为需要优化CLS 超过 0.1 标记为布局不稳定可访问性检查覆盖图片 alt、表单 label、颜色对比度三项。输出格式固定为“指标名 实测值 阈值 结论”的表格。这个 Skill 的价值在于它把“打开页面、采集数据、分析、输出”这一整套流程固化下来了。如果没有 Skill每次都要重新描述检查项和输出格式效率低且不一致。有了 Skill一句“帮我巡检一下这个页面”就能触发完整的流程。4.4 避免重复造轮子先查内置能力再决定是否封装在写任何 Skill 之前我都会先问自己三个问题这件事 Claude Code 内置能力能不能做如果能做输出质量是否稳定如果不稳定是因为缺少领域知识还是缺少格式约束如果内置能力能做且质量稳定就不写 Skill。如果缺少领域知识就把知识写进 Skill。如果缺少格式约束就把格式规则写进 Skill。这个检查流程帮我砍掉了至少十个原本打算写的 Skill。比如“解释这段代码”这件事内置能力已经做得很好不需要 Skill。“按照团队规范审查代码”这件事内置能力不知道团队规范需要 Skill 来补充。“生成符合特定模板的周报”这件事内置能力不知道模板需要 Skill 来约束格式。5. 让Skill真正被稳定调用的工程化细节5.1 触发率低的第一排查点description的意图覆盖如果你的 Skill 触发率低第一个要检查的就是 description。我做过一个简单的统计在触发率低于 50% 的 Skill 里超过八成的问题出在 description 上。常见的 description 问题有三类第一类是意图覆盖不全。比如一个test-gen的 Skilldescription 写的是“当用户要求生成单元测试时使用”但用户实际可能说“帮我给这个函数写点测试”“这个模块缺测试”“补一下测试覆盖”。如果 description 只覆盖了“生成单元测试”这一种表述其他表述就匹配不上。第二类是意图覆盖过宽。比如一个code-helper的 Skilldescription 写的是“当用户需要代码相关帮助时使用”。这个范围太大了几乎任何代码对话都能匹配结果就是模型不知道该不该调用干脆不调用。第三类是缺少否定边界。有些 Skill 需要明确“什么时候不用”。比如一个refactor的 Skill如果用户只是问“这段代码什么意思”不应该触发重构。在 description 里加上“当用户明确要求重构、优化结构、或改善代码组织时使用仅询问代码含义时不使用”能显著减少误触发。5.2 输出不稳定的根因约束写成了建议输出不稳定的常见根因是把约束写成了建议。比如“建议使用 2 空格缩进”“尽量保持标题简短”“最好按照类型分组”。“建议”“尽量”“最好”这些词在 Skill 里几乎等于没写。模型会把它们当成可选项而不是必须遵守的规则。正确的写法是直接、明确、可验证的约束“使用 2 空格缩进”“标题不超过 72 字符”“按类型分组类型之间空一行”。如果某个约束有例外情况就明确写出例外条件而不是用模糊的措辞。另一个根因是缺少输出格式的锚点。如果 Skill 要求输出表格但没有给出表格的列名和顺序模型每次输出的格式都可能不同。解决办法是在示例里给一个完整的格式锚点让模型有明确的参照。5.3 版本迭代Skill也需要回归测试Skill 写完之后不是一劳永逸的。我现在的做法是每个 Skill 都维护一个简单的测试用例集三到五个典型的用户输入以及期望的输出特征。每次修改 Skill 之后用这几个用例跑一遍确认触发正常、输出符合预期。这个做法听起来有点重但实际执行起来很快。因为 Skill 的测试不需要精确匹配输出内容只需要检查几个关键特征是否触发、输出格式是否正确、关键约束是否遵守。我通常用 Claude Code 本身来跑这些测试把测试用例贴进去看它的行为是否符合预期。注意修改 Skill 的 description 之后一定要重新测试触发率。description 的微小改动可能导致触发行为发生显著变化这是最容易出问题的地方。5.4 团队协作Skill的命名、分类与共享当 Skill 数量超过二十个之后命名和分类就变得很重要。我的做法是按领域分目录skills/code/、skills/docs/、skills/data/、skills/ops/。每个 Skill 的 name 用“领域-动作”的格式比如code-review、docs-api、>