Claude Code Skill 最佳实践：5 分钟封一个，6 条要点 + 团队共享

这是一个或许对你有用的社群 一对一交流/面试小册/简历优化/求职解惑欢迎加入「芋道快速开发平台」知识星球。下面是星球提供的部分资料《项目实战视频》从书中学往事上“练”《互联网高频面试题》面朝简历学习春暖花开《架构 x 系统设计》摧枯拉朽掌控面试高频场景题《精进 Java 学习指南》系统学习互联网主流技术栈《必读 Java 源码专栏》知其然知其所以然这是一个或许对你有用的开源项目国产Star破10w的开源项目前端包括管理后台、微信小程序后端支持单体、微服务架构RBAC权限、数据权限、SaaS多租户、商城、支付、工作流、大屏报表、ERP、CRM、AI大模型、IoT物联网等功能多模块https://gitee.com/zhijiantianya/ruoyi-vue-pro微服务https://gitee.com/zhijiantianya/yudao-cloud视频教程https://doc.iocoder.cn【国内首批】支持 JDK17/21SpringBoot3、JDK8/11Spring Boot2双版本Skill 是什么按需加载的任务 SOPSkill vs CLAUDE.md哪个放哪个Skill 放在哪3 个位置 × 3 种作用范围写一个最简单的 Skill5 分钟跑通frontmatter 字段速查表6 个把 Skill 写好的实战要点实战案例把团队的 Spring Boot Controller 规范封成 Skill验证 团队共享用 skills-ref Git3 个新人最常踩的小坑最后说一句Skill 是什么按需加载的任务 SOPSkill 的结构其实简单到不真实——一个文件夹里放一个SKILL.md就够了。但它的关键不在格式在加载时机Claude Code 启动时只扫描所有 Skill 的 name description——大概 100 个 token 记住有哪些技能可用。真正用某个 Skill 的时候才把完整内容加载进来。这是 Skill 设计上最聪明的一点——没用上的不占上下文。一台笔记本可以装上几百个 Skill对每次会话的成本几乎为零。基于 Spring Boot MyBatis Plus Vue Element 实现的后台管理系统 用户小程序支持 RBAC 动态权限、多租户、数据权限、工作流、三方登录、支付、短信、商城等功能项目地址https://github.com/YunaiV/ruoyi-vue-pro视频教程https://doc.iocoder.cn/video/Skill vs CLAUDE.md哪个放哪个很多人第一次接触会问Skill 和CLAUDE.md我都能放规则——区别到底在哪维度CLAUDE.mdSkill加载时机每次对话全量加载按需加载——只加载 name descriptionToken 消耗文件多大消耗多大初始 ~100 token触发才加载全文适合放什么全局规则、项目约定特定任务的 SOP / 工作流触发方式自动手动/命令或 Claude 自动匹配打个比方——CLAUDE.md 放的是「这个项目的基本规矩」——用什么语言、代码风格要求Skill 放的是「这类任务怎么做」——审一个 PR 怎么审、写一个组件怎么写。两者不是替代关系分工不同——CLAUDE.md 太厚了塞不进每次对话Skill 让你能为具体任务封装规则、按需取用。Skill 遵循一个开放规范——Agent Skills Specification。不只是 Claude CodeCursor / GitHub Copilot 等工具也在逐步支持。基于 Spring Cloud Alibaba Gateway Nacos RocketMQ Vue Element 实现的后台管理系统 用户小程序支持 RBAC 动态权限、多租户、数据权限、工作流、三方登录、支付、短信、商城等功能项目地址https://github.com/YunaiV/yudao-cloud视频教程https://doc.iocoder.cn/video/Skill 放在哪3 个位置 × 3 种作用范围Skill 有 3 个可放位置——取决于你希望它作用范围多大位置范围典型用法~/.claude/skills/name/SKILL.md个人级别所有项目都能用.claude/skills/name/SKILL.md项目级别只对当前项目生效提交 Gitplugin/skills/name/SKILL.md插件级别随插件分发大多数情况下项目级别就够用——把.claude/skills/提交到 Git团队所有人拉下来就能用不需要单独配置。关键约束文件夹名字要和SKILL.md里的name字段一致——这是规范要求。写一个最简单的 Skill5 分钟跑通Skill 文件由 2 部分组成——顶部 YAML 头部下面的 Markdown 正文--- name: hello-world description: 一个示例 skill用于演示基本结构 --- 当用户打招呼时用中文回复并附上一个冷笑话。放进~/.claude/skills/hello-world/SKILL.md之后——手动调用在对话框输入/就能看到 Skill 列表选hello-world或直接输/hello-world触发自动触发Claude 识别到对话内容和 description 匹配比如有人说 你好自动加载这个 Skill。创建好之后没看到——重启一下 Claude Code 就行或输入/reload。就这样——5 分钟、3 步建文件夹 → 写SKILL.md→ 重启——你的第一个 Skill 就跑通了。对话里说你好Claude 自动接一句冷笑话。frontmatter 字段速查表SKILL.md的 YAML 头部有一些常用字段——记住这张表字段是否必填说明name✅ 是1–64 字符只能小写字母 / 数字 / 连字符要和文件夹同名description✅ 是最重要的字段——Claude 根据它判断要不要加载这个 Skilldisable-model-invocation否设true则只能手动调用Claude 不会自动触发allowed-tools否Skill 激活时允许免确认使用的工具license否许可证类型compatibility否环境要求说明比如Requires python3.10metadata否自定义键值对存放额外信息description长度上限 1024 字符——内容要写清楚干什么 什么时候用。这字段是写给 Claude 看的不是写给人看的——把触发词和应用场景写进去。6 个把 Skill 写好的实战要点知道结构是一回事写得好用是另一回事。下面 6 条是实战中反复打磨出来的要点 1description 是触发器不是摘要这个字段决定了 Skill 能不能被自动加载——写法直接影响匹配命中率。❌不好摘要式description: 这是一个帮助生成代码的工具✅好触发词 应用场景description: 生成 Spring Boot Service 类。当用户要求写业务逻辑、新建 Service、实现业务接口时使用。差别在哪——前者太抽象、Claude 不知道什么时候该用后者有明确动作写业务逻辑 触发词新建 Service / 业务接口 应用场景。要点 2正文用命令语气、加编号写提取颜色主题不要写你应该提取颜色主题——Claude 按指令运行编号能让它按顺序执行减少遗漏。1. 读取当前文件 2. 检查安全问题 3. 输出审查结果要点 3SKILL.md控制在 500 行以内内容多了怎么办——拆到同目录下的小文件然后 SKILL.md 引用my-skill/ ├── SKILL.md # 主指令必须 ├── template.java # 业务代码模板Service / Controller / Mapper 等 ├── examples/ │ └── UserService.java # 示例代码 └── references/ └── REFERENCE.md # 详细技术参考在SKILL.md里这样引用## 参考资料 - 代码模板见 [template.java](template.java) - 详细技术参考见 [references/REFERENCE.md](references/REFERENCE.md)好处——Claude 只在真正需要时读关联文件不会一次性把所有内容塞进上下文。要点 4动态注入让 Skill 自己去拿上下文这个特性很强——用!命令语法可以在 Skill 加载前执行 shell 命令把输出直接嵌入提示词--- name: pr-review description: 审查当前 PR 的代码变更 --- ## 当前变更 !git diff --stat ## 变更详情 !git diff 请审查以上代码变更关注潜在的 bug 和规范问题。Claude 看到的不是命令本身——是命令的输出结果。这样它手里拿到的就是真实的 diff不需要你再粘贴一遍。要点 5用$ARGUMENTS接收参数如果 Skill 需要传变量——用$ARGUMENTS接收--- name: fix-issue description: 修复 GitHub issue disable-model-invocation: true --- 修复 GitHub issue #$ARGUMENTS 1. 阅读 issue 描述 2. 实现修复 3. 编写测试 4. 创建 commit调用/fix-issue 42时$ARGUMENTS替换为42。多个参数可以用$0/$1按位置取。这里特意加了disable-model-invocation: true——意思是只能手动调用。有副作用的操作部署 / 修改文件一定要加这条——避免 Claude 自作主张。要点 6区分谁能调用简单划分——辅助查询、生成类任务——允许自动触发部署、发消息、修改文件这类有副作用的——加上disable-model-invocation: true只能手动。实战案例把团队的 Spring Boot Controller 规范封成 Skill典型场景——你做一个 Spring Boot 项目每次让 Claude 写接口都要重复说一遍用RestController、参数加Validated校验、返回包装成CommonResult、路径用 kebab-case、Swagger 注解Tag/Operation文档要齐……封装成 Skillspring-controller/ ├── SKILL.md ├── template.java # 一个符合规范的 Controller 模板 └── examples/ └── UserController.java # 示例 ControllerSKILL.md内容--- name: spring-controller description: 生成符合团队规范的 Spring Boot Controller。当用户要求创建接口、写 Controller、加 API、新建 endpoint 时使用。 --- 按以下规范生成 Spring Boot Controller 1. 使用 RestController RequestMapping(/api/v1/...) 注解 2. 所有接口入参必须加 Validated 校验 3. 返回值统一用 CommonResultT 包装 4. 接口路径用 kebab-case如 /user-info不是 /userInfo 5. 用 Swagger 注解 Tag / Operation 写文档描述参数与返回值 6. 参考 [template.java](template.java) 的结构 输出示例见 [examples/UserController.java](examples/UserController.java)。以后只要说**帮我写一个用户登录的 Controller** 或者手动执行/spring-controller——Claude 直接出符合 yudao-cloud 风格的代码不用每次再口述一遍。其他场景类似套路——DAO 层写mybatis-mapperSkill / 前端写react-componentSkill / 单测写junit-caseSkill——模板都套这个结构。验证 团队共享用 skills-ref Git验证用 skills-ref 检查 frontmatterSkill 写好之后可以用官方工具模拟验证# 安装验证工具参考 GitHub: agentskills/agentskills skills-ref validate ./spring-controller它会检查name格式、description是否为空、命名规范等。小项目不用管但想公开发布或团队共享过这个检查比较稳妥。团队共享直接提交到 Git最简单的共享方式——把.claude/skills/目录提交到 Git新人克隆仓库就能直接用——不需要任何额外配置打开 Claude Code 就能看到团队所有人共享的 Skill。这比在CLAUDE.md里塞一堆规范要合理得多——模块化 按需加载 谁需要谁用。团队内的 Skill 分工原则有经验的人写好一批高价值 Skill提交到仓库入职的人下载下来就能用——这是内部沉淀。3 个新人最常踩的小坑坑 1name 格式写错最常见name字段只能小写字母 / 数字 / 单个连字符——✅my-skill、spring-controller、pr-review❌my--skill连续两个连字符、-my-skill开头连字符、my_skill下划线、MySkill大写。坑 2改完没重启 Claude Code容易忘如果当前有运行中的会话——新增或修改 Skill 之后需要重启 Claude Code或/reload才会生效。常见症状刚改完发现/name没出现 / 触发不到——90% 是这个问题。坑 3description 写得太空导致 Claude 抓不到症状——你以为写了description就万事大吉实际上 Claude 自动匹配时识别不到。修法把 description 当 SEO 关键词那样写——把所有可能触发的动词 名词都列上去# ❌ 太空 description: 帮助生成 Spring Boot 代码 # ✅ 触发词全列 description: 生成 Spring Boot Controller。当用户要求写接口 / 写 Controller / 加 API / 新建 endpoint时使用。最后说一句Skill 的核心逻辑其实很简单——把重复性的指令封装起来让 Claude 在合适时机自动拿出来用。第一步行动——想想你日常最常重复说的那一类指令——把它封装成 Skill提交到项目的.claude/skills/。1 周下来你会发现自己已经存了 3-5 个——团队效率会有明显提升。之后再慢慢往里面加。参考资料Agent Skills Specification 官方规范agentskills/agentskills GitHub Skill 验证工具掘金参考文章https://juejin.cn/post/7629641479674478642欢迎加入我的知识星球全面提升技术能力。 加入方式“长按”或“扫描”下方二维码噢星球的内容包括项目实战、面试招聘、源码解析、学习路线。文章有帮助的话在看转发吧。 谢谢支持哟 (*^__^*