1. 从50个Skill里爬出来的血泪教训先交代背景。过去几个月我一直在折腾 Claude Code 的 Skill 系统前前后后写了差不多50个覆盖代码生成、接口调试、数据库迁移、文档整理、测试用例补全这些日常场景。写到最后我回头复盘发现一个很扎心的事实前30个基本等于白写。不是不能用而是用起来别扭、维护成本高、复用率低很多Skill写完之后我自己都不怎么调用。这篇文章就是把这50个Skill的踩坑过程摊开讲。如果你正在用 Claude Code或者准备给自己的团队搭一套 Skill 体系又或者你只是好奇 SKILL.md 到底该怎么写才不浪费生命那这篇内容应该能帮你少走至少两个月的弯路。我会从整体设计思路讲到具体文件结构再到实操步骤和排查技巧尽量把每个“为什么”都讲透。核心关键词先摆出来Claude Code、Skill、SKILL.md、MCP、Spring Boot。这几个词基本构成了我整套工作流的骨架。Claude Code 负责调度和推理Skill 负责把领域知识固化下来SKILL.md 是载体MCP 负责打通外部工具和数据源Spring Boot 则是我主要服务的技术栈场景。先说结论性的判断Skill 不是提示词模板不是写给人看的文档也不是越详细越好。它更像是一份“给AI看的操作手册”核心目标是让模型在特定场景下做出稳定、可预期、可复现的行为。前30个Skill之所以白写根本原因就是我把它当成了“知识堆砌”而不是“行为约束”。2. 前30个Skill为什么白写了2.1 把Skill当文档写信息密度高但可执行性差我最早写的Skill典型结构是这样的一段背景介绍一段技术栈说明然后罗列一堆注意事项最后附上几个示例。看起来很像一份合格的技术文档但问题在于——Claude Code 读完之后不知道该“做什么”。它知道了很多事实但没有明确的行为指令。举个例子我写过一个“Spring Boot 接口开发规范”的Skill里面详细描述了 Controller 层要怎么写、Service 层要怎么分层、DTO 要怎么转换。结果实际调用的时候模型还是会按它自己的习惯来因为我的描述是“陈述性”的不是“指令性”的。后来我改成明确的步骤式指令比如“生成 Controller 时必须包含以下注解”“参数校验必须使用 Valid”“返回值必须包装成统一响应体”效果立刻不一样。提示Skill 里的每一句话都要问自己——这是在告诉模型“是什么”还是在告诉模型“怎么做”前者价值有限后者才是核心。2.2 粒度失控要么太泛要么太碎第二个大坑是粒度。我写过那种“万能Skill”一个文件里塞了代码生成、代码审查、测试补全、文档输出四件事结果模型每次调用都要在脑子里做一次任务分类准确率反而下降。也写过那种“超细Skill”比如“生成一个带分页的查询接口”单独成一个Skill导致Skill数量爆炸维护起来想死。实测下来比较合理的粒度是一个Skill对应一类明确的任务场景场景内部可以有分支但分支之间必须共享同一套上下文和约束。比如“Spring Boot CRUD接口生成”可以是一个Skill里面区分单表、多表关联、分页查询几种情况但不要把“接口生成”和“接口文档输出”混在一起。2.3 忽略MCP的协同Skill孤军奋战前30个Skill里我几乎没有考虑 MCP 的配合。MCP 是模型和外部工具之间的桥梁它能让 Claude Code 真正去读数据库、调接口、查日志、操作文件系统。我早期写的Skill全是“纯文本指令”模型只能靠自己的知识来回答没法验证、没法落地。后来我把 MCP 接进来之后整个玩法变了。比如我写一个“数据库迁移检查”的Skill里面明确要求模型通过 MCP 去读取当前表结构对比目标结构再生成迁移脚本。这样出来的结果是有事实依据的不是模型瞎编的。再比如“接口联调”场景Skill 里要求模型通过 MCP 调用本地服务拿到真实响应之后再判断是否符合预期。2.4 没有版本管理和回归测试这个坑最隐蔽。我早期改Skill很随意今天加一条规则明天删一条规则改完之后也不记录。结果某天发现某个Skill突然不好用了回头查根本不知道是哪次改动导致的。后来我养成了习惯每个Skill都带版本号每次修改都写变更说明并且准备一组固定的测试用例改完就跑一遍。下面这张表是我总结的前30个Skill的典型问题分布你可以对照看看自己有没有中招。问题类型出现频次典型表现修复方向陈述性描述过多高频模型知道事实但不执行改成指令式步骤粒度失控高频太泛导致分类困难太碎导致维护爆炸按任务场景划分忽略MCP协同中频结果无法验证容易幻觉接入外部工具做事实校验无版本管理中频改动后无法回溯加版本号和变更日志缺少边界条件中频异常场景处理混乱补充失败分支和兜底逻辑示例过于理想化低频实际输入不匹配增加真实脏数据示例3. SKILL.md 的正确打开方式3.1 文件结构从“给人看”转向“给模型看”一个能打的 SKILL.md结构应该非常清晰而且每一部分都有明确目的。我现在的标准结构是这样的# Skill 名称 ## 适用场景 ## 前置条件 ## 执行步骤 ## 输出格式 ## 异常处理 ## 示例 ## 版本记录看起来简单但每一部分的写法都有讲究。“适用场景”要写清楚什么时候该用这个Skill什么时候不该用这是给模型做路由判断用的。“前置条件”要列出执行前必须满足的状态比如需要哪些MCP工具可用、需要哪些环境变量。“执行步骤”是核心必须是指令式的一步一步来。“输出格式”要明确到字段级别避免模型自由发挥。“异常处理”要覆盖常见失败情况。“示例”要给真实输入输出不要给理想化的假数据。3.2 指令式写法把“应该”换成“必须”这是最关键的转变。对比一下两种写法陈述式“在Spring Boot项目中Controller层通常需要处理参数校验建议使用Valid注解。”指令式“生成Controller方法时必须在请求体参数前添加Valid注解。如果参数校验失败必须返回统一错误响应HTTP状态码为400。”后者模型执行起来几乎没有歧义。我实测下来指令式写法的Skill输出稳定性比陈述式高出至少一个档次。原因很简单模型在生成内容时是在做概率选择约束越明确可选空间越小结果越可控。3.3 用MCP做事实锚点Skill里凡是涉及外部状态的判断都应该通过MCP去获取真实数据而不是让模型凭记忆回答。比如判断某个接口是否存在通过MCP去读项目源码或接口文档判断数据库表结构通过MCP去查information_schema判断依赖版本通过MCP去读pom.xml或build.gradle判断服务是否运行通过MCP去调健康检查接口这样做的好处是Skill的输出有了事实基础不会出现“模型以为是这样实际不是”的情况。我在Spring Boot项目里大量使用了这种方式尤其是接口联调和数据库迁移场景效果非常明显。3.4 版本记录不能省每个SKILL.md末尾我都会加一段版本记录格式如下## 版本记录 - v1.3 (2025-01-15): 增加分页查询场景补充异常处理分支 - v1.2 (2025-01-08): 修正输出格式统一响应体字段 - v1.1 (2024-12-30): 增加MCP前置条件检查 - v1.0 (2024-12-20): 初始版本别小看这几行字排查问题的时候能救命。有一次某个Skill突然输出格式不对我翻版本记录发现是前一天改了一条输出规则回滚之后立刻恢复正常。4. 实操从零写一个能打的Skill4.1 场景选择Spring Boot 接口生成我拿一个真实场景来演示给 Spring Boot 项目生成标准的 CRUD 接口。这个场景足够典型涉及代码生成、规范约束、MCP协同、异常处理能把前面讲的要点全部串起来。先明确目标输入一个实体类名和字段定义输出完整的 Controller、Service、Mapper、DTO 代码并且符合项目现有规范。要求模型通过 MCP 读取项目现有的代码风格和依赖版本确保生成结果能直接编译通过。4.2 前置条件与MCP配置前置条件要写清楚项目根目录存在 pom.xml 或 build.gradle存在统一的响应体类比如 Result存在统一异常处理类MCP 文件系统工具可用能读取项目源码MCP 数据库工具可用能查询表结构可选MCP 配置这块我用的是文件系统访问加数据库查询两个工具。文件系统工具让模型能读项目结构、读现有代码、读配置文件数据库工具让模型能查表结构、查索引、查字段类型。这两个工具配合起来基本能覆盖接口生成所需的全部上下文。注意MCP 工具的权限要控制好只开放必要的读写范围。我一般只给读权限写操作由模型生成代码后人工确认再落盘。4.3 执行步骤的写法执行步骤是整个Skill的核心我把它拆成明确的阶段## 执行步骤 ### 第一步读取项目上下文 1. 通过MCP读取项目根目录的pom.xml提取Spring Boot版本和关键依赖版本 2. 通过MCP读取现有Controller目录分析代码风格注解使用、命名规范、包结构 3. 通过MCP读取统一响应体类和异常处理类记录其包路径和方法签名 ### 第二步确认实体信息 1. 如果用户提供了实体类通过MCP读取该实体类的字段定义 2. 如果用户只提供了表名通过MCP查询数据库表结构推导实体字段 3. 输出字段清单包含字段名、类型、是否必填、校验规则 ### 第三步生成代码 1. 生成DTO类包含请求DTO和响应DTO 2. 生成Mapper接口包含基础CRUD方法 3. 生成Service接口和实现类包含业务逻辑 4. 生成Controller类包含RESTful接口 5. 所有生成代码必须符合第一步读取到的项目规范 ### 第四步自检 1. 检查所有注解是否完整 2. 检查包路径是否正确 3. 检查响应体是否统一 4. 检查异常处理是否覆盖 5. 输出自检报告这种写法模型执行起来非常顺每一步都有明确的输入和输出不会跑偏。4.4 输出格式与异常处理输出格式要精确到文件级别## 输出格式 按以下顺序输出文件 1. {EntityName}RequestDTO.java - 请求参数 2. {EntityName}ResponseDTO.java - 响应数据 3. {EntityName}Mapper.java - 数据访问 4. {EntityName}Service.java - 服务接口 5. {EntityName}ServiceImpl.java - 服务实现 6. {EntityName}Controller.java - 接口层 每个文件必须包含 - 完整的package声明 - 完整的import列表 - 类级别注释 - 方法级别注释异常处理要覆盖这些情况异常场景处理方式项目结构读取失败终止执行提示检查MCP配置实体类不存在提示用户确认实体名或表名依赖版本不兼容输出兼容性警告建议调整版本代码风格冲突以项目现有风格为准输出冲突说明数据库连接失败跳过表结构查询要求用户手动提供字段4.5 实测效果与调优记录这个Skill写完第一版之后我拿三个真实项目做了测试。第一个项目是标准的分层架构生成结果直接能用编译通过率100%。第二个项目用了自定义的响应体包装模型通过MCP读到了这个类生成结果也正确。第三个项目用了多模块结构模型一开始把包路径搞错了后来我在前置条件里加了“必须读取模块划分”这一条问题解决。调优过程中最大的收获是MCP读取的上下文越充分生成结果越准确。我后来把“读取项目上下文”这一步从3个子项扩展到7个子项包括读取配置文件、读取工具类、读取常量定义生成准确率从70%左右提升到95%以上。5. 常见问题与排查技巧实录5.1 Skill不生效或效果不稳定这是最常见的问题。排查思路按以下顺序来检查SKILL.md是否被正确加载路径和命名是否符合规范检查Skill的“适用场景”是否写得太宽泛导致模型路由错误检查执行步骤是否指令式有没有模糊表述检查是否有冲突的Skill同时生效检查MCP工具是否可用前置条件是否满足我遇到过一次典型情况两个Skill的适用场景都写了“代码生成”结果模型每次调用都随机选一个输出自然不稳定。后来把场景描述改得更具体一个写“Spring Boot接口生成”一个写“单元测试生成”问题就解决了。5.2 MCP调用失败MCP调用失败的原因比较多我整理了一张速查表现象可能原因解决方法工具列表为空MCP服务未启动检查服务进程和端口调用超时网络或服务响应慢增加超时配置检查服务负载权限拒绝工具权限配置过严调整权限范围开放必要路径返回数据格式错误工具实现有bug检查工具输出格式修复解析逻辑间歇性失败连接池或并发问题检查连接配置增加重试机制提示MCP调用失败时Skill里要有兜底逻辑。比如数据库查询失败时不要直接报错终止而是提示用户手动提供信息继续执行后续步骤。5.3 生成结果不符合项目规范这个问题通常是因为Skill里没有强制要求读取项目上下文。我的做法是在执行步骤第一步就明确要求通过MCP读取现有代码提取规范。如果项目本身规范不统一那就以最近修改的文件为准或者让用户指定参考文件。还有一个技巧在Skill里加一段“规范冲突处理”逻辑当模型发现项目内存在多种风格时输出冲突清单让用户选择。这样既保证了生成质量又避免了模型自作主张。5.4 Skill维护成本高Skill数量多了之后维护确实是个问题。我的经验是建立Skill索引文件记录每个Skill的用途、版本、依赖关系定期清理不再使用的Skill别舍不得删把公共约束抽出来比如代码风格、响应格式做成共享片段每次修改都跑回归测试确保没有破坏现有功能我现在维护的Skill大概20个左右比巅峰期的50个少了一半多但实际使用频率和效果反而更好。少即是多这句话在Skill管理上特别成立。6. 我现在的Skill体系长什么样经过这一轮大浪淘沙我现在的Skill体系大概分四类第一类是代码生成类包括接口生成、实体生成、测试生成这类Skill依赖MCP读取项目上下文输出可直接使用的代码。第二类是代码审查类包括规范检查、安全扫描、性能分析这类Skill依赖MCP读取源码输出问题清单和修复建议。第三类是运维操作类包括日志查询、服务健康检查、配置对比这类Skill依赖MCP调用外部服务输出操作结果。第四类是文档类包括接口文档生成、变更记录整理、知识库更新这类Skill依赖MCP读取代码和提交记录输出结构化文档。每一类下面大概3到5个Skill每个Skill都有明确的适用场景、前置条件、执行步骤、输出格式、异常处理和版本记录。整套体系跑下来日常开发效率提升非常明显尤其是接口开发和联调环节以前要半天的工作现在半小时能搞定。最后分享一个我踩过的最大的坑不要为了写Skill而写Skill。我前30个Skill里有一半是“觉得应该有用”而写的实际根本用不上。真正有价值的Skill都是从真实痛点里长出来的。你先手动做一件事做烦了再把它固化成Skill这样的Skill才有生命力。