1. 从“写了50个”到“前30个白写”一个Skill作者的自我推翻我大概是在三个月前开始系统性地写 Claude Code Skill 的。那时候刚把 Claude Code 装好摸清楚了SKILL.md的基本结构知道了 frontmatter 里可以写name、description知道了 skill 会被自动加载进上下文于是产生了一种“我懂了”的错觉。接下来的两周我像流水线一样产出了三十多个 skill有帮我整理 Git 提交信息的有自动生成周报的有把会议纪要转成待办清单的还有几个是给特定项目定制的代码审查规则。每个 skill 我都写得很认真description 写得像产品文案正文步骤写得像操作手册。结果呢真正高频使用的不到五个。大部分 skill 写完之后就躺在.claude/skills/目录里吃灰偶尔被触发一次输出的结果还不如我直接跟 Claude 说一句话来得准确。更尴尬的是有些 skill 之间还会互相干扰——比如一个负责“精简输出”的 skill 和一个负责“详细解释”的 skill在同一个会话里被同时加载Claude 的行为变得非常拧巴一会儿啰嗦一会儿惜字如金。直到我写到第 50 个 skill 的时候才突然意识到一个残酷的事实前 30 个 skill 的问题不在于写得不好而在于我根本没想清楚“什么该做成 skill什么不该”。我把太多本该用 prompt 解决的事情固化成了 skill又把太多需要动态判断的事情写成了死板的步骤。这篇文章就是把这 50 个 skill 的踩坑过程拆开讲清楚 skill 的边界在哪里、SKILL.md的 frontmatter 到底该怎么写、MCP 和 skill 的分工怎么划、以及为什么“少即是多”在 skill 设计里是铁律。如果你刚开始接触 Claude Code或者已经写了一堆 skill 但感觉效果一般这篇内容应该能帮你省下至少两周的无效劳动。我会从最基础的概念讲起但重点放在那些文档里不会写的判断逻辑和实操细节上。2. 先搞清楚Skill到底解决什么问题再动手写第一个2.1 Skill不是Prompt的“高级版”它是上下文的“预加载器”很多人第一次接触 skill 的时候会把它理解成“写得更长的 prompt”。这个理解不能说错但非常容易导致设计跑偏。Prompt 是你每次对话时临时给 Claude 的指令而 skill 是一段在特定条件下被自动注入上下文的指令集合。这个区别听起来很微妙但实际影响巨大。举个例子。如果你只是想让 Claude 在回答时“用中文、分点、每点不超过两句话”这完全不需要 skill。你直接在对话里说一次或者在项目的CLAUDE.md里写一句全局规则就行了。但如果你希望 Claude 在每次处理数据库迁移文件时都自动检查三件事有没有加索引、有没有回滚方案、字段命名是否符合团队规范——这种“特定场景触发 固定检查清单”的需求才是 skill 真正擅长的。我前 30 个 skill 里有一大半犯的就是这个错误把全局偏好写成了 skill。比如我写过一个叫concise-output的 skilldescription 是“让 Claude 的输出更简洁”。结果它确实被触发了但触发得太频繁导致我在需要详细解释的时候也得手动关掉它。后来我把这个需求直接挪到了CLAUDE.md里用一句话解决“默认输出简洁除非我明确要求详细展开。” 一个 skill 就这么被一行配置替代了。判断标准很简单如果一个规则你希望它在所有对话里都生效写进CLAUDE.md如果只在特定任务类型里生效才考虑做成 skill。2.2 什么样的任务值得固化成Skill我后来总结了一个“三问法则”每次想写新 skill 之前先问自己三个问题这个任务会不会重复出现如果只是偶尔做一次直接对话解决不值得写 skill。这个任务的执行步骤是否稳定如果每次的流程都不一样skill 的固定步骤反而会成为束缚。这个任务是否需要额外的上下文或工具如果需要读取特定文件、调用 MCP 工具、或者依赖项目里的某些约定那 skill 的价值就很高。三个问题都答“是”的时候才值得动手写SKILL.md。我第 31 个 skill 开始用这个标准过滤产出效率反而提高了——因为不再写那些“看起来有用但实际用不上”的东西了。举个正面例子。我写过一个叫db-migration-review的 skill专门用来审查数据库迁移脚本。它满足三问迁移脚本每周都有、审查步骤固定检查索引、检查回滚、检查命名、需要读取迁移文件并对照项目里的 schema 约定。这个 skill 到现在还在用而且每次触发都能稳定输出有价值的检查结果。反面例子是我写过一个meeting-notesskill想把会议纪要自动转成待办。问题是每次会议的格式都不一样有的人写得很结构化有的人就是一堆散点。skill 里的固定解析步骤根本处理不了这种多样性最后还不如我直接把纪要粘贴给 Claude 说“帮我提取待办”。这个 skill 写了不到一周就被我删了。2.3 Frontmatter里的description决定了Skill的“触发命运”SKILL.md的 frontmatter 里最重要的字段就是description。它不只是给人看的说明更是 Claude 判断“要不要加载这个 skill”的核心依据。我前 30 个 skill 的 description 写得都很“官方”比如“用于处理代码审查相关任务”“帮助生成文档”。这种写法的问题是太模糊导致触发时机完全不可控。后来我改成了一个更实用的写法在 description 里直接写清楚“什么时候用”和“什么时候不用”。比如我那个db-migration-review的 description 是这样的--- name: db-migration-review description: 当用户创建或修改数据库迁移文件migration时使用。检查索引、回滚方案、字段命名规范。不适用于查询优化或 schema 设计讨论。 ---这个写法有两个好处。第一Claude 在判断是否加载时能明确知道触发条件是“创建或修改迁移文件”而不是模糊的“数据库相关”。第二明确写了“不适用于”的场景避免了在讨论 schema 设计时被误触发。我还见过有人把 description 写成一段很长的自然语言里面塞了各种关键词。实测下来简洁、场景明确、带排除条件的 description 效果最好。一般控制在两三句话第一句说“什么时候用”第二句说“做什么”第三句说“不用在什么地方”。3. 前30个Skill踩过的四类坑以及第31个之后的修正方案3.1 坑一把Skill写成了“万能工具箱”我早期写过一个叫code-helper的 skilldescription 是“帮助处理各种代码相关问题”。这个 skill 的正文里塞了代码审查、重构建议、bug 排查、性能优化、文档生成五六个模块。结果就是它确实经常被触发但每次触发后 Claude 都要在五六个模块里“猜”用户到底想要哪个输出质量非常不稳定。这个坑的本质是职责不清。一个 skill 应该只做一件事而且这件事的边界要清晰到可以用一句话说清楚。后来我把code-helper拆成了四个独立的 skillcode-review、refactor-suggest、bug-triage、perf-check。每个 skill 的 description 都明确指向一个具体场景触发准确率和输出质量都上来了。经验法则如果一个 skill 的正文超过 150 行或者需要用小标题分成三个以上的模块那它大概率应该被拆开。3.2 坑二在Skill里写“死步骤”忽略了Claude的判断力我写过一个commit-messageskill用来生成 Git 提交信息。正文里我写了非常详细的步骤第一步读取 diff第二步提取变更类型第三步按照type(scope): description的格式生成第四步检查字数不超过 72 个字符。看起来很严谨对吧但实际用起来很僵硬。有时候变更很简单Claude 按步骤走一遍反而显得啰嗦有时候变更很复杂固定格式又装不下。后来我把这个 skill 改成了“原则 示例”的写法给出提交信息的核心原则说清楚“做了什么”和“为什么”给两三个好例子和坏例子剩下的交给 Claude 判断。改完之后生成的提交信息反而更自然、更准确。这个坑的教训是Skill 应该提供“判断依据”和“参考标准”而不是“执行脚本”。Claude 本身有很强的推理能力你把它当成一个需要手把手教的新人反而浪费了它的能力。正确的做法是告诉它“好的标准是什么”而不是“第一步做什么、第二步做什么”。3.3 坑三Skill之间互相打架上下文被污染前面提到过我同时加载了concise-output和detailed-explain两个 skill结果 Claude 的行为变得很分裂。这个问题在 skill 数量多了之后特别容易出现。因为 skill 是自动加载的你很难精确控制同一时刻到底有哪些 skill 在上下文里。我后来做了一个“skill 冲突检查表”每次新增 skill 之前先看看它和现有 skill 有没有功能重叠或指令矛盾。具体检查三类冲突冲突类型表现解决方案输出风格冲突一个要求简洁一个要求详细合并成一个 skill用条件分支处理触发场景重叠两个 skill 都声称处理“代码审查”合并或明确划分边界指令矛盾一个说“先问再做”一个说“直接做”统一行为准则写进 CLAUDE.md这个检查表帮我砍掉了至少八个冗余 skill。现在我的 skill 目录里常年保持在 15 个以内每个都有明确的职责边界。3.4 坑四忽略了MCP和Skill的分工MCP 和 skill 是两种不同的扩展机制但我早期完全没搞清楚它们的区别导致有些该用 MCP 的事情被我硬写成了 skill。比如我写过一个fetch-api-docsskill想让它去读取某个 API 的在线文档。但 skill 本身没有网络请求能力它只能“指导” Claude 去调用工具。而 MCP 才是真正提供工具能力的那个层。后来我理清了分工MCP 负责“能做什么”提供工具和资源Skill 负责“怎么做”提供流程和标准。比如我有一个 MCP 工具可以查询数据库 schema然后我写了一个schema-checkskill告诉 Claude 在什么情况下应该去调用这个 MCP 工具、拿到结果后怎么分析。两者配合起来效果比单独用任何一个都好。如果你现在还在纠结某个需求该做成 MCP 还是 skill可以这样判断需要连接外部系统、执行实际操作读文件、调 API、查数据库的做成 MCP需要规范 Claude 的行为、提供判断标准的做成 skill。4. 一个高质量SKILL.md的完整拆解从frontmatter到正文结构4.1 Frontmatter的字段选择与写法细节一个标准的SKILL.mdfrontmatter 至少包含name和description两个字段。name用英文小写加连字符保持简洁比如db-migration-review。description的写法前面已经讲过核心是“场景 动作 排除条件”。有些实现还支持allowed-tools字段用来限制这个 skill 可以调用哪些工具。这个字段在需要控制权限的场景下很有用。比如一个只负责“读取和分析”的 skill可以把工具限制在文件读取和搜索上避免它意外执行写操作。还有一个容易被忽略的点frontmatter 里的name要和文件名保持一致。我有一次改了文件名但忘了改 frontmatter 里的 name结果 skill 加载行为变得很奇怪排查了半天才发现是这个不一致导致的。4.2 正文的“三段式”结构原则、示例、边界经过多次迭代我现在写SKILL.md正文基本遵循一个三段式结构第一段核心原则。用三到五句话说明这个 skill 的目标和判断标准。比如db-migration-review的原则是“迁移脚本必须可回滚、必须有索引覆盖、字段命名必须符合 snake_case 规范。如果任何一项不满足标记为需要修改。”第二段正反示例。给出两到三个“好的做法”和“坏的做法”的对比。这比单纯列步骤有效得多因为 Claude 能从示例中推断出你想要的模式。比如我会贴一段符合规范的迁移脚本和一段有问题的迁移脚本让 Claude 对照着判断。第三段边界与例外。说明什么情况下这个 skill 不适用或者需要特殊处理。比如“如果迁移涉及数据删除不要自动生成回滚方案而是提示用户手动确认。”这个结构的好处是原则给方向示例给标准边界防误用。三者缺一不可。我早期只写步骤不写示例结果 Claude 执行得很机械后来只写原则不写边界结果在特殊场景下频繁出错。4.3 用“检查清单”代替“操作步骤”另一个重要的转变是把“操作步骤”改写成“检查清单”。步骤是线性的清单是并行的。Claude 不需要按顺序执行它只需要确保清单上的每一项都被覆盖到。比如db-migration-review的检查清单是这样的[ ] 迁移文件是否有对应的回滚方案[ ] 新增字段是否有索引如果该字段会出现在查询条件里[ ] 字段命名是否符合 snake_case[ ] 是否有 NOT NULL 约束但没有默认值[ ] 是否修改了现有字段的类型高风险操作这种写法比“第一步检查回滚第二步检查索引……”灵活得多。Claude 可以根据实际情况调整检查顺序也可以在一次输出里同时报告多个问题。5. 实测有效的Skill组织策略数量控制、命名规范与迭代节奏5.1 把Skill数量控制在“能记住”的范围内我现在稳定使用的 skill 有 14 个分成三类通用类3 个比如concise-output的替代方案已经挪到 CLAUDE.md现在通用类只剩commit-message、pr-description、changelog-gen、项目类6 个针对当前项目的特定流程、工具类5 个配合 MCP 工具使用。这个数量是刻意控制的。因为 skill 太多会导致两个问题一是触发冲突的概率增加二是你自己都记不住有哪些 skill更别说管理它们了。我的经验是个人使用的 skill 集合控制在 15 个以内比较舒服。超过这个数就应该考虑合并或者删除一些低频的。5.2 命名规范让触发条件一目了然命名看起来是小事但实际影响很大。我早期的命名很随意有helper、utils、tool1这种完全看不出用途的名字。后来统一成了“场景-动作”的格式db-migration-review数据库迁移-审查api-doc-genAPI 文档-生成bug-triageBug-分诊perf-check性能-检查这种命名方式的好处是当你在会话里看到 Claude 说“正在使用 db-migration-review skill”时你立刻就知道它在干什么。而且命名规范也会反过来约束你的设计——如果你没法用“场景-动作”的格式给一个 skill 命名那说明它的职责可能不够清晰。5.3 迭代节奏先跑一周再决定要不要留我现在写新 skill 的流程是先写一个最小可用的版本用一周然后决定是保留、修改还是删除。这一周里我会记录三件事触发次数、输出质量、有没有误触发。一周后如果触发次数少于三次或者输出质量不稳定直接删掉不犹豫。这个“一周试用期”帮我砍掉了很多“看起来有用”的 skill。我第 40 个左右的 skill 里有一个叫weekly-report的写的时候觉得每周都能用结果实际一周只触发了一次而且输出还不如我手动整理。试用期结束后直接删了。一个反直觉的经验删除 skill 比添加 skill 更能提升整体效果。因为每删掉一个低质量 skill就减少了一份上下文污染和触发冲突的风险。6. 从“写得多”到“写得准”我现在的Skill工作流6.1 新Skill的“最小验证”流程现在每次想写新 skill我会先做一个“最小验证”不写SKILL.md直接在对话里把想要的流程和标准跟 Claude 说一遍看它能不能稳定执行。如果连续三次都能得到满意的结果说明这个流程是稳定的值得固化成 skill。如果三次里有一次翻车说明这个任务本身就不适合用固定流程处理直接放弃。这个验证流程帮我省下了大量写SKILL.md的时间。以前我是先写 skill 再测试现在我是先测试再决定要不要写 skill。顺序反过来之后无效 skill 的产出率下降了至少七成。6.2 定期清理每月一次的“Skill审计”我每个月会花半小时做一次 skill 审计检查四件事过去一个月里每个 skill 被触发了多少次低于三次的标记为“待观察”。有没有 skill 的 description 需要更新因为项目需求可能变了。有没有新的 skill 和旧的 skill 功能重叠有没有 skill 的正文里引用了已经废弃的 MCP 工具或文件路径这个审计习惯是从写代码的“依赖清理”里借鉴过来的。Skill 也是一种依赖不定期清理就会积累技术债。6.3 和MCP配合的“分层设计”最后说一下 MCP 和 skill 的配合。我现在会把一个完整的能力拆成两层MCP 层提供工具skill 层提供使用规范。比如我有一个 MCP 工具可以查询数据库的 schema 信息然后schema-checkskill 负责告诉 Claude什么时候该查 schema、查到之后怎么对照迁移文件、发现不一致时怎么报告。这种分层设计的好处是MCP 工具可以被多个 skill 复用而 skill 只关注“怎么用”而不是“怎么实现”。如果你现在还在把工具调用逻辑硬写在 skill 里建议尽早拆开。MCP 负责“手”skill 负责“脑”各司其职整体效果会稳定很多。写 skill 这件事说到底是一个“做减法”的过程。前 30 个白写的经历让我明白skill 的价值不在于数量而在于每一个都精准地解决了某个重复出现的、流程稳定的、需要额外上下文的问题。如果你现在正在写自己的第一批 skill我的建议是先写三个用两周然后再决定要不要写第四个。慢一点反而快。