⭐⭐⭐ Spring Boot 项目实战	⭐⭐⭐ Spring Cloud 项目实战
《Dubbo 实现原理与源码解析 —— 精品合集》	《Netty 实现原理与源码解析 —— 精品合集》
《Spring 实现原理与源码解析 —— 精品合集》	《MyBatis 实现原理与源码解析 —— 精品合集》
《Spring MVC 实现原理与源码解析 —— 精品合集》	《数据库实体设计合集》
《Spring Boot 实现原理与源码解析 —— 精品合集》	《Java 面试题 + Java 学习指南》

摘要: 原创出处 http://www.iocoder.cn/Fight/ruhexieyigezijide-Skill/ 「芋道源码」欢迎转载，保留摘要，谢谢！

🙂🙂🙂关注微信公众号：【芋道源码】有福利：

RocketMQ / MyCAT / Sharding-JDBC 所有源码分析文章列表

RocketMQ / MyCAT / Sharding-JDBC 中文注释源码 GitHub 地址

您对于源码的疑问每条留言都将得到认真回复。甚至不知道如何读源码也可以请教噢。

新的源码解析文章实时收到通知。每周更新一篇左右。

认真的源码交流微信群。

Skill 是什么：按需加载的”任务 SOP”

Skill 的结构其实简单到不真实——一个文件夹里放一个 SKILL.md，就够了。

但它的关键不在格式，在加载时机：

Claude Code 启动时只扫描所有 Skill 的 name + description——大概 100 个 token 记住”有哪些技能可用”。真正用某个 Skill 的时候才把完整内容加载进来。

这是 Skill 设计上最聪明的一点——没用上的不占上下文。一台笔记本可以装上几百个 Skill，对每次会话的成本几乎为零。

Skill vs CLAUDE.md：哪个放哪个

很多人第一次接触会问：Skill 和 CLAUDE.md 我都能放规则——区别到底在哪？

维度	CLAUDE.md	Skill
加载时机	每次对话全量加载	按需加载——只加载 name + description
Token 消耗	文件多大消耗多大	初始 ~100 token，触发才加载全文
适合放什么	全局规则、项目约定	特定任务的 SOP / 工作流
触发方式	自动	手动 `/命令` 或 Claude 自动匹配

打个比方——

CLAUDE.md 放的是「这个项目的基本规矩」——用什么语言、代码风格要求；Skill 放的是「这类任务怎么做」——审一个 PR 怎么审、写一个组件怎么写。

两者不是替代关系，分工不同——CLAUDE.md 太厚了塞不进每次对话，Skill 让你能为”具体任务”封装规则、按需取用。

Skill 遵循一个开放规范——Agent Skills Specification。不只是 Claude Code，Cursor / GitHub Copilot 等工具也在逐步支持。

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`	否	设 `true` 则只能手动调用，Claude 不会自动触发
`allowed-tools`	否	Skill 激活时允许免确认使用的工具
`license`	否	许可证类型
`compatibility`	否	环境要求说明，比如 `Requires python3.10+`
`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   # 示例 Controller

SKILL.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-mapper Skill / 前端写 react-component Skill / 单测写 junit-case Skill——模板都套这个结构。

验证 + 团队共享：用 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

芋道源码 —— 纯源码解析博客

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

Skill 是什么：按需加载的”任务 SOP”

Skill vs CLAUDE.md：哪个放哪个

Skill 放在哪：3 个位置 × 3 种作用范围

写一个最简单的 Skill（5 分钟跑通）

frontmatter 字段速查表

6 个把 Skill 写好的实战要点

要点 1：description 是”触发器”，不是”摘要”

要点 2：正文用命令语气、加编号

要点 3：`SKILL.md` 控制在 500 行以内

要点 4：动态注入：让 Skill 自己去拿上下文

要点 5：用 `$ARGUMENTS` 接收参数

要点 6：区分谁能调用

实战案例：把团队的 Spring Boot Controller 规范封成 Skill

验证 + 团队共享：用 skills-ref + Git

验证：用 skills-ref 检查 frontmatter

团队共享：直接提交到 Git

3 个新人最常踩的小坑

坑 1：name 格式写错（最常见）

坑 2：改完没重启 Claude Code（容易忘）

坑 3：description 写得太空导致 Claude 抓不到

最后说一句

Skill 是什么：按需加载的”任务 SOP”

Skill vs CLAUDE.md：哪个放哪个

Skill 放在哪：3 个位置 × 3 种作用范围

写一个最简单的 Skill（5 分钟跑通）

frontmatter 字段速查表

6 个把 Skill 写好的实战要点

要点 1：description 是”触发器”，不是”摘要”

要点 2：正文用命令语气、加编号

要点 3：SKILL.md 控制在 500 行以内

要点 4：动态注入：让 Skill 自己去拿上下文

要点 5：用 $ARGUMENTS 接收参数

要点 6：区分谁能调用

实战案例：把团队的 Spring Boot Controller 规范封成 Skill

验证 + 团队共享：用 skills-ref + Git

验证：用 skills-ref 检查 frontmatter

团队共享：直接提交到 Git

3 个新人最常踩的小坑

坑 1：name 格式写错（最常见）

坑 2：改完没重启 Claude Code（容易忘）

坑 3：description 写得太空导致 Claude 抓不到

最后说一句

要点 3：`SKILL.md` 控制在 500 行以内

要点 5：用 `$ARGUMENTS` 接收参数