Claude Code Skill 最佳实践：5 分钟封一个，6 条要点 + 团队共享
基于 Spring Cloud Alibaba + Gateway + Nacos + RocketMQ + Vue & Element 实现的后台管理系统 + 用户小程序，支持 RBAC 动态权限、多租户、数据权限、工作流、三方登录、支付、短信、商城等功能。基于 Spring Boot + MyBatis Plus + Vue & Element 实现的后台管理系统 + 用户小程序，支持 RBA
👉 这是一个或许对你有用的社群
🐱 一对一交流/面试小册/简历优化/求职解惑，欢迎加入「芋道快速开发平台」知识星球。下面是星球提供的部分资料：
《项目实战（视频）》：从书中学，往事上“练”
《互联网高频面试题》：面朝简历学习，春暖花开
《架构 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/21+SpringBoot3、JDK8/11+Spring Boot2双版本
Skill 是什么：按需加载的"任务 SOP"
Skill 的结构其实简单到不真实——一个文件夹里放一个 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.md |
Skill |
|---|---|---|
| 加载时机 | 每次对话全量加载 | 按需加载
——只加载 name + description |
| Token 消耗 |
文件多大消耗多大 |
初始 ~100 token，触发才加载全文 |
| 适合放什么 |
全局规则、项目约定 |
特定任务的 SOP / 工作流 |
| 触发方式 |
自动 |
手动 |
打个比方——
CLAUDE.md 放的是「这个项目的基本规矩」 ——用什么语言、代码风格要求；Skill 放的是「这类任务怎么做」 ——审一个 PR 怎么审、写一个组件怎么写。
两者不是替代关系，分工不同 ——CLAUDE.md 太厚了塞不进每次对话，Skill 让你能为"具体任务"封装规则、按需取用。
Skill 遵循一个开放规范——Agent Skills Specification 。不只是 Claude Code，Cursor / 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 |
项目级别 |
只对当前项目生效（提交 Git） |
<plugin>/skills/<name>/SKILL.md |
插件级别 |
随插件分发 |
大多数情况下，项目级别就够用 ——把 .claude/skills/ 提交到 Git，团队所有人拉下来就能用 ，不需要单独配置。
关键约束 ：文件夹名字要和
SKILL.md里的name字段一致——这是规范要求。
写一个最简单的 Skill（5 分钟跑通）
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 根据它判断要不要加载这个 Skill |
disable-model-invocation |
否 |
设 |
allowed-tools |
否 |
Skill 激活时允许免确认使用的工具 |
license |
否 |
许可证类型 |
compatibility |
否 |
环境要求说明，比如 |
metadata |
否 |
自定义键值对，存放额外信息 |
description长度上限 1024 字符 ——内容要写清楚干什么 + 什么时候用 。这字段是写给 Claude 看的，不是写给人看的 ——把"触发词"和"应用场景"写进去。
6 个把 Skill 写好的实战要点
知道结构是一回事，写得好用 是另一回事。下面 6 条是实战中反复打磨出来的：
要点 1：description 是"触发器"，不是"摘要"
这个字段决定了 Skill 能不能被自动加载——写法直接影响匹配命中率 。
❌ 不好 ：摘要式
description: 这是一个帮助生成代码的工具✅ 好 ：触发词 + 应用场景
description: 生成 Spring Boot Service 类。当用户要求写业务逻辑、新建 Service、实现业务接口时使用。差别在哪——前者太抽象、Claude 不知道什么时候该用 ；后者有明确动作（写业务逻辑）+ 触发词（新建 Service / 业务接口）+ 应用场景 。
要点 2：正文用命令语气、加编号
写"提取颜色主题"，不要写"你应该提取颜色主题" ——
Claude 按指令运行，编号能让它按顺序执行，减少遗漏 。
1. 读取当前文件
2. 检查安全问题
3. 输出审查结果要点 3：SKILL.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文档要齐……
封装成 Skill ：
spring-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. 返回值统一用 CommonResult<T> 包装
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 检查 frontmatter
Skill 写好之后，可以用官方工具模拟验证：
# 安装验证工具（参考 GitHub: agentskills/agentskills）
skills-ref validate ./spring-controller它会检查 name 格式、description 是否为空、命名规范等。小项目不用管 ，但想公开发布或团队共享，过这个检查比较稳妥 。
团队共享：直接提交到 Git
最简单的共享方式 ——把 .claude/skills/ 目录提交到 Git ：
新人克隆仓库就能直接用 ——不需要任何额外配置，打开 Claude Code 就能看到团队所有人共享的 Skill。
这比在 CLAUDE.md 里塞一堆规范要合理得多——模块化 + 按需加载 + 谁需要谁用 。
团队内的 Skill 分工原则 ：
有经验的人写好一批高价值 Skill，提交到仓库；入职的人下载下来就能用——这是内部沉淀。
3 个新人最常踩的小坑
坑 1：name 格式写错（最常见）
name 字段只能小写字母 / 数字 / 单个连字符 ——
-
✅
my-skill、spring-controller、pr-review； -
❌
my--skill（连续两个连字符）、-my-skill（开头连字符）、my_skill（下划线）、MySkill（大写）。
坑 2：改完没重启 Claude Code（容易忘）
如果当前有运行中的会话——新增或修改 Skill 之后需要重启 Claude Code （或 /reload）才会生效。
常见症状 ：刚改完发现
/<name>没出现 / 触发不到——90% 是这个问题 。
坑 3：description 写得太空导致 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
欢迎加入我的知识星球，全面提升技术能力。
👉 加入方式，“长按”或“扫描”下方二维码噢：
星球的内容包括：项目实战、面试招聘、源码解析、学习路线。
文章有帮助的话，在看，转发吧。
谢谢支持哟 (*^__^*）
Agent 垂直技术社区，欢迎活跃、内容共建。
更多推荐
13
0- 0
已为社区贡献11条内容
所有评论(0)