Claude Skills

把可复用的专业知识打包起来，只在真正需要的时候才加载

🎯 什么是 Skill？

Skill（技能）是一个包含 SKILL.md 文件的文件夹，用来记录某一项具体的专业知识——编码规范、调试流程、检查清单、领域特定的操作步骤。Claude Code 启动时只会读取技能的简短描述（description），只有当前任务与这段描述匹配时，才会把完整内容加载进上下文。

这正是它和直接把规则写进 CLAUDE.md 的关键区别：skills 能让你的上下文窗口保持干净。一份 2000 行的 Java 编码规范，在你没有真正写 Java 代码之前，不会占用你一个 token。

💡 Skills vs. Rules vs. CLAUDE.md

• CLAUDE.md —— 始终加载，用于每一次对话都必须知道的内容（技术栈、构建命令）
• Rules（.claude/rules/*.md）—— 根据正在编辑的文件路径自动加载（详见 .claude 配置层级）
• Skills（.claude/skills/*/SKILL.md）—— 根据任务描述匹配按需加载，内容可以又大又细

📦 目录结构

.claude/
└── skills/
    ├── java-coding-standards/
    │   └── SKILL.md
    ├── java-unit-testing/
    │   └── SKILL.md
    └── java-security-standards/
        └── SKILL.md

每个技能都住在以技能名命名的独立目录里，包含一个 SKILL.md 文件。如果任务需要真正跑代码而不只是读指令，技能目录里也可以捆绑一些辅助脚本或参考文件。

🧩 SKILL.md 的结构解剖

---
name: java-coding-standards
description: 阿里巴巴 Java 编码规范，涵盖命名、格式化、OOP 规约、日期时间处理、
  集合处理与并发处理。在编写 Java 代码、代码评审或需要遵循阿里巴巴 Java
  规范时使用。
---

# 编程规约

## 命名风格
...

## 代码格式
...

字段	作用
name	唯一标识，与目录名保持一致
description	最关键的字段。 Claude 正是靠扫描它来判断要不要加载这个技能。要写清楚触发条件（"在……时使用"）和排除条件（"……时跳过"）
正文	完整的指令、示例、检查清单——只有触发时才会加载

⚠️ description 要写成触发条件，而不是摘要

一段模糊的描述（比如"Java 最佳实践"）很难被可靠地触发。好的描述会点名具体信号：文件后缀、请求中的关键词、报错信息，或者明确排除容易和它混淆的相邻技能。

🚀 企业级仓库中常见的技能分类

真正的工程团队通常按关注点拆分技能，而不是写成一份巨大的文档：

技能	覆盖内容
*-coding-standards	命名、格式化、语言惯用法
*-project-structure	模块布局、包结构规范
*-exception-logging	异常处理与日志规范
*-security-standards	输入校验、鉴权、敏感信息处理
*-unit-testing	测试结构、mock 规则、覆盖率要求
*-database	表结构规范、迁移规则、查询规范

这样拆分之后，每个技能的 description 都能写得很窄很精准，触发就更可靠，也不会让无关的上下文污染不相关的任务。

🛠️ 创建一个技能

1. 创建目录：.claude/skills/<技能名>/
2. 添加 SKILL.md，写好 frontmatter（name、description），正文写完整指令
3. 把 description 写成明确的触发条件——先想"什么时候该触发"，内容其次
4. 测试一下：开始一个应该触发该技能的任务，确认 Claude 真的加载了它
5. 提交到仓库（项目级技能），让整个团队都受益

💡 个人技能 vs. 团队技能

• 项目技能 —— 仓库内的 .claude/skills/，提交到 git，全团队共享
• 全局技能 —— ~/.claude/skills/，个人专属，在你机器上的所有项目里都能用（适合"我喜欢的 commit message 格式"这类跟具体项目无关的技能）

📖 示例：一段真实的 SKILL.md 摘录

---
name: java-exception-logging
description: 异常处理与日志规范——自定义异常体系、全局异常处理器、SLF4J 使用、
  日志级别规则。在编写 try/catch 代码块、自定义异常或 Java 日志语句时使用。
---

# 异常与日志规约

## 异常体系
- 业务异常统一继承 `BusinessException`，携带错误码与错误信息
- 禁止大范围捕获 `Exception`——应捕获具体的异常类型
- 禁止静默吞掉异常；必须记录日志或重新抛出

## 日志
- 统一使用 SLF4J（`@Slf4j`），禁止使用 `System.out.println`
- `log.error` 必须把异常对象作为最后一个参数传入，以保留堆栈信息
- 禁止在多个层级对同一个异常反复"记录日志后再抛出"（log-and-throw 反模式）

🎉 效果

当开发者的 Claude Code 会话涉及到 try/catch 代码块时，这个技能的描述会被匹配到，完整规范自动加载——不需要在每次提问里重复交代。