Claude Code Skill 完全指南：从入门到精通
·
Claude Code Skill 完全指南：从入门到精通
引言
在日常开发中，我们常常面临重复性的工作：
- 需要对代码进行一致性审核
- 需要自动生成API文档
- 需要进行数据格式转换
如果每次都手动处理这些任务，不仅效率低下，而且容易出错。Claude Code 的 Skill 功能就是为了解决这个问题而设计的。
本文将深入讲解 Claude Skill 的概念、用法和最佳实践，帮助你构建高效的开发工作流。
1. Claude Skill 是什么？
1.1 核心定义
Skill 是 Claude Code 中的高级功能扩展机制，用于创建可复用、参数化的 AI 工作流。
简单来说：
- 一个 Skill 就是一个自动化的工作流脚本
- 它可以执行特定的、重复性的业务任务
- 它会生成结构化的输出
- 它可以被无限次复用
1.2 Skill 的形式
一个 Skill 实际上是一个 Markdown 文件，包含：
---
name: MySkill
description: 这是一个Skill的描述
---
[Skill的内容和工作流说明]
1.3 Skill 的本质
从技术角度看，Skill 是：
- 持久化的 - 存储在项目的
.claude/目录中 - 参数化的 - 支持命令行参数输入
- 工作流化的 - 可以进行多步骤的操作
- 可复用的 - 定义一次，无限使用
2. 为什么需要 Skill？
2.1 实际问题场景
场景1：代码审核的一致性
没有 Skill 的做法：
需要审核一个Java文件 → 手动检查代码质量 → 手动检查安全问题
→ 手动写审核报告 → 需要审核另一个文件 → 重复上述过程...
缺点：
- 耗时，容易疲劳导致检查不全
- 审核标准不一致，不同审核人员的结果差异大
- 无法追踪审核历史
有 Skill 的做法：
/code-review src/OrderService.java → 自动生成审核报告
/code-review src/PaymentService.java → 自动生成审核报告
[使用相同的标准和流程，审核结果一致]
优势：
- 快速 - 几分钟内完成审核
- 一致 - 所有审核遵循相同的标准
- 可追踪 - 有详细的审核历史记录
场景2：文档生成
没有 Skill：
- 需要手动阅读代码
- 手动编写API文档
- 容易遗漏某些接口
- 文档与代码容易不同步
有 Skill：
- 自动解析代码结构
- 自动生成接口文档
- 保证文档完整性
- 文档随代码自动更新
2.2 Skill 解决的核心问题
| 问题 | Skill的解决方案 |
|---|---|
| 重复劳动 | 一次定义，无限复用 |
| 标准不一致 | 使用相同的Skill保证一致性 |
| 容易出错 | 自动化处理，减少人工错误 |
| 难以追踪 | 生成详细的操作记录 |
| 新人培训 | Skill中包含最佳实践，新人可快速上手 |
| 知识流失 | 知识沉淀到Skill中，可传承 |
3. Skill 的基本概念
3.1 Skill 的文件结构
项目根目录
├── .claude/
│ ├── settings.local.json ← 配置文件
│ ├── CodeReview/
│ │ └── CodeReview.md ← Skill文件
│ ├── APIGenerator/
│ │ └── APIGenerator.md ← Skill文件
│ └── SupplierIntegration/
│ └── Supplier.md ← Skill文件
└── CLAUDE.md ← 项目文档（可选）
3.2 Skill 的最小结构
---
name: MyFirstSkill
description: 这是我的第一个Skill，用来演示基本结构
---
# 功能说明
此Skill用来完成XXX任务
## 使用方法
```bash
/my-first-skill <param1> [param2]
示例
/my-first-skill hello
### 3.3 Skill Front Matter 详解
```yaml
---
# 必需字段
name: SkillName # Skill的名称，用于引用
description: 简短的功能描述 # 一句话说明这个Skill做什么
# 可选字段
version: 1.0 # 版本号
author: Your Name # 作者
tags: # 标签，便于分类
- code-generation
- automation
parameters: # 参数定义（可选）
entity_name:
type: string
required: true
description: 实体名称
fields:
type: string
required: true
description: 字段定义，格式 field:type,field:type
---
3.4 Skill 的生命周期
定义 Skill
↓
├─ 创建 .md 文件
├─ 编写 Front Matter 元数据
└─ 编写工作流说明
↓
注册 Skill
├─ 在 settings.local.json 中配置
└─ 或通过 /skill 命令动态注册
↓
使用 Skill
├─ 执行命令 /skill-name <params>
├─ Claude Code 解析参数
├─ 加载 Skill 定义
└─ 执行工作流
↓
生成输出
├─ 代码文件
├─ 配置文件
├─ 文档文件
└─ 审核报告
↓
维护 Skill
├─ 收集用户反馈
├─ 改进工作流
├─ 更新文档
└─ 发布新版本
3.5 Skill 的执行模型
用户输入命令
↓
/code-review src/Main.java --strict
↓
Claude Code 命令解析器
├─ 提取 skill 名称: code-review
├─ 提取参数: [src/Main.java, --strict]
└─ 查找 Skill 定义
↓
加载 Skill 文件 (.claude/CodeReview/CodeReview.md)
├─ 解析 Front Matter 元数据
├─ 提取工作流说明
└─ 识别处理逻辑
↓
执行工作流
├─ 第一步：参数验证
├─ 第二步：输入分析
├─ 第三步：处理逻辑
├─ 第四步：生成输出
└─ 第五步：保存结果
↓
返回结果
├─ 生成文件
├─ 显示摘要
└─ 提供建议
4. 创建第一个 Skill
4.1 简单案例：问候 Skill
让我们创建一个最简单的 Skill 来理解基础概念。
第一步：创建目录
mkdir .claude/Greeting
第二步：创建 Skill 文件
创建文件 .claude/Greeting/Greeting.md：
---
name: Greeting
description: 一个简单的问候Skill，演示基本用法
version: 1.0
---
# 问候 Skill
## 功能
这是一个演示Skill，用来展示Skill的基本结构和用法。
## 使用方法
```bash
/greeting <name>
参数
name(必需): 被问候人的名字
示例
/greeting Alice
/greeting 张三
工作流
此Skill执行以下步骤：
- 接收用户名称参数
- 生成个性化的问候信息
- 添加一些有趣的emoji表情
- 返回问候结果
预期输出
Hello, Alice! 👋
希望今天有美好的一天！✨
**第三步：测试 Skill**
```bash
/greeting Alice
预期输出：
Hello, Alice! 👋
希望今天有美好的一天！✨
4.2 进阶案例：代码审核 Skill
现在让我们创建一个更实用的 Skill。
创建文件 .claude/CodeReview/CodeReview.md：
---
name: CodeReview
description: 对代码进行全面质量审核，检查安全性、性能和可维护性
version: 1.0
author: Development Team
tags:
- code-quality
- security
- review
parameters:
file_path:
type: string
required: true
description: 要审核的代码文件路径
strict_mode:
type: boolean
required: false
description: 是否启用严格模式，检查更多问题
---
# Code Review Skill
## 功能概述
自动分析代码质量，检查以下方面：
- 安全性 (Security)
- 性能 (Performance)
- 可维护性 (Maintainability)
- 测试覆盖 (Test Coverage)
## 使用方法
```bash
/code-review <file_path> [--strict]
参数
file_path(必需): Java代码文件路径--strict(可选): 启用严格模式，进行更深入的检查
示例
# 基础审核
/code-review src/main/java/OrderService.java
# 严格模式
/code-review src/main/java/PaymentProcessor.java --strict
审核维度
1. 安全性审核
检查的内容：
- SQL注入风险
- XSS漏洞
- 敏感信息泄露
- 认证和授权问题
代码示例：
// ❌ 有问题的代码 (SQL注入风险)
String query = "SELECT * FROM user WHERE id = " + userId;
List<User> users = jdbcTemplate.query(query, mapper);
// ✅ 改进后的代码
String query = "SELECT * FROM user WHERE id = ?";
List<User> users = jdbcTemplate.query(query, new Object[]{userId}, mapper);
2. 性能审核
检查的内容：
- N+1查询问题
- 无限循环
- 内存泄漏
- 算法复杂度
代码示例：
// ❌ 有问题的代码 (N+1查询)
List<Order> orders = orderService.findAll();
for (Order order : orders) {
User user = userService.findById(order.getUserId()); // 每次循环查询
process(user);
}
// ✅ 改进后的代码 (批量查询)
List<Order> orders = orderService.findAllWithUsers(); // 一次查询获取所有关联数据
for (Order order : orders) {
process(order.getUser());
}
3. 可维护性审核
检查的内容：
- 圈复杂度
- 方法长度
- 命名规范
- 代码重复
代码示例：
// ❌ 有问题的代码 (魔法数字，复杂度高)
if (status == 1 && amount > 100 && days < 7) {
// 30行复杂逻辑
}
// ✅ 改进后的代码 (常量，逻辑清晰)
private static final int PENDING_STATUS = 1;
private static final BigDecimal MIN_AMOUNT = new BigDecimal("100");
if (isPending() && isHighValue() && isUrgent()) {
// 逻辑清晰，易于维护
}
输出格式
审核完成后会生成：
-
审核摘要
代码审核报告 ============= 文件: OrderService.java 评分: 75/100 级别: 良好 问题统计: 严重 (Critical): 1个 高 (High): 3个 中 (Medium): 5个 -
详细问题列表
- 问题描述
- 代码位置
- 修复建议
- 参考资料
-
改进建议
- 优先级排序
- 预计工作量
- 性能影响评估
最佳实践清单
生成的代码应该通过以下检查：
安全清单
- 无SQL注入风险
- 无XSS漏洞
- 敏感数据已加密
- 异常信息不暴露细节
性能清单
- 无N+1查询
- 合理的算法复杂度
- 没有内存泄漏
- 资源正确释放
可维护清单
- 圈复杂度 ≤ 10
- 方法长度 ≤ 50行
- 命名规范正确
- 注释充分
故障排查
问题1: 找不到文件
# 错误用法
/code-review OrderService.java
# 正确用法 - 提供完整路径
/code-review src/main/java/OrderService.java
问题2: 审核耗时很长
这是正常的，代码深度分析需要时间。可以尝试：
- 分割大文件后分别审核
- 使用–strict参数控制审核深度
### 4.3 创建完整的 Skill 配置
编辑或创建 `.claude/settings.local.json`：
```json
{
"model": "haiku",
"skills": {
"code-review": {
"enabled": true,
"path": ".claude/CodeReview/CodeReview.md",
"description": "代码质量审核",
"timeout": 300
},
"greeting": {
"enabled": true,
"path": ".claude/Greeting/Greeting.md",
"description": "问候Skill",
"timeout": 60
}
},
"custom_slash_commands": [
{
"name": "/code-review",
"type": "skill",
"description": "对代码进行全面质量审核"
},
{
"name": "/greeting",
"type": "skill",
"description": "生成个性化问候信息"
}
]
}
4.4 测试你的 Skill
# 测试问候Skill
/greeting 李明
# 测试代码审核Skill
/code-review src/main/java/UserService.java
/code-review src/main/java/PaymentService.java --strict
5. Skill 与其他功能的区别
5.1 Skill vs Slash Commands
| 特性 | Skill | Slash Commands |
|---|---|---|
| 定义方式 | Markdown + Front Matter | JSON配置 |
| 存储位置 | .claude/ 目录 | settings.json |
| 持久化 | 是 | 是 |
| 复杂度 | 高 | 中等 |
| 参数支持 | 完整的参数解析 | 需要手动解析 |
| 工作流 | 完整的多步工作流 | 简单的命令包装 |
| 文件生成 | 支持生成多个文件 | 主要输出文本 |
| 跨项目复用 | 容易 | 需要复制配置 |
| 团队分享 | 易于分享 | 需要同步配置 |
关键区别： Slash Commands 实际上是调用 Skill 的快捷方式！
/code-review file.java
↓
查找关联的Skill
↓
执行.claude/CodeReview/CodeReview.md中的定义
↓
返回结果
5.2 Skill vs Tasks/Agents
| 特性 | Skill | Task/Agent |
|---|---|---|
| 持久化 | 是 | 否 |
| 复用性 | 高 | 一次性 |
| 调用方式 | /skill-name | 代码中动态创建 |
| 场景 | 重复性工作流 | 即席任务 |
| 知识沉淀 | 是 | 否 |
使用场景：
- 用 Skill 当你需要反复执行相同的任务
- 用 Task 当你需要处理一次性的、复杂的任务
5.3 Skill vs Hooks
| 特性 | Skill | Hooks |
|---|---|---|
| 触发方式 | 显式调用 | 自动触发 |
| 执行时机 | 用户主动执行时 | 命令执行前/后 |
| 粒度 | 业务级别 | 系统级别 |
| 用途 | 自动化工作流 | 拦截和验证命令 |
6. 实战案例分析
6.1 案例1：代码审核 Skill
背景： 新员工代码质量审核费时费力，审核标准不一致。
需求：
- 快速审核新人代码
- 保证审核标准一致
- 提供学习建议
Skill 设计：
- 自动检查5大维度（安全、性能、可维护性等）
- 生成详细审核报告
- 提供代码改进建议
收益：
- 审核时间从30分钟降到5分钟
- 新人能快速学到最佳实践
- 减少代码审核中的遗漏
6.2 案例2：API文档生成 Skill
背景： 手动编写API文档容易遗漏，且容易与代码不同步。
需求：
- 自动生成完整的API文档
- 包括接口清单、参数说明、示例等
- 自动保持与代码同步
工作流：
扫描代码 → 提取接口定义 → 生成文档 → 输出Markdown
收益：
- 文档生成从1小时降到5分钟
- 确保文档完整性
- 文档自动与代码同步
7. 最佳实践
7.1 Skill 设计原则
1. 单一职责
每个 Skill 应该专注于一个特定的任务。
不好的做法 ❌
---
name: DoEverything
description: 生成代码、审核代码、生成文档、发布代码
---
# 这个Skill做太多事情，难以维护
好的做法 ✓
---
name: CodeGenerate
description: 根据业务需求生成代码
---
---
name: CodeReview
description: 对代码进行质量审核
---
---
name: DocGenerate
description: 根据代码生成文档
---
2. 清晰的参数定义
参数应该清晰明确，易于理解。
不好的做法 ❌
## 使用方法
/my-skill <arg1> [arg2]
# 不清楚arg1和arg2是什么
好的做法 ✓
## 使用方法
/code-generate <entity_name> --fields <field_list> [--methods <method_list>]
### 参数说明
- `entity_name` (必需): 实体名称，如Order, User
- `--fields` (必需): 字段定义，格式 name:type,email:string
- `--methods` (可选): 方法集合，如CRUD,search,export
3. 详细的工作流说明
要让用户理解 Skill 做了什么。
不好的做法 ❌
## 功能
生成代码。
好的做法 ✓
## 功能
此Skill执行以下步骤：
1. **分析需求** (2-3分钟)
- 提取关键信息
- 验证参数有效性
2. **生成代码** (3-5分钟)
- 创建实体类
- 创建Service层
- 创建Controller层
3. **生成配置** (1-2分钟)
- 创建配置文件
- 生成Mybatis映射
4. **生成测试** (2-3分钟)
- 单元测试
- 集成测试模板
4. 提供具体的示例
示例帮助用户快速上手。
不好的做法 ❌
## 示例
/my-skill <something>
好的做法 ✓
## 示例
### 示例1：生成订单API
```bash
/generate-api Order --fields "id:Long,userId:Long,amount:BigDecimal" --methods CRUD
生成的文件：
- OrderController.java
- OrderService.java
- OrderMapper.java
示例2：生成用户API
/generate-api User --fields "id:Long,name:String,email:String" --methods "CRUD,auth"
生成的文件：
- UserController.java
- UserService.java
- UserMapper.java
#### 5. 明确的质量检查清单
说明 Skill 生成的输出会通过什么检查。
**示例：**
```markdown
## 质量检查清单
生成的代码会通过以下检查：
### 代码质量
- [ ] 遵循项目编码规范 (驼峰、命名等)
- [ ] 无硬编码值
- [ ] 异常处理完整
- [ ] 日志记录充分
### 安全性
- [ ] 参数验证完整
- [ ] SQL注入防护
- [ ] 权限检查
- [ ] 敏感数据加密
### 性能
- [ ] 合理的查询优化
- [ ] 缓存策略恰当
- [ ] 批量操作支持
7.2 Skill 文档最佳实践
1. 使用清晰的标题层级
# Skill名称 (一级标题)
## 功能说明 (二级标题)
### 功能点1 (三级标题)
#### 详细说明 (四级标题)
2. 包含丰富的代码示例
- 错误的做法（❌ 标记）
- 正确的做法（✓ 标记）
- 解释为什么
3. 添加参考链接
链接到相关资源、文档、规范等。
4. 提供故障排查
## 故障排查
### Q: 问题描述
A: 解决方案
7.3 Skill 版本管理
---
name: CodeReview
description: 代码质量审核
version: 2.1.0
changelog:
- 2.1.0: 增加性能分析功能
- 2.0.0: 重构安全审核模块
- 1.0.0: 初始版本
---
7.4 Skill 团队协作
分享 Skill：
- 将 Skill 文件上传到团队仓库
- 添加到项目的
.claude/目录 - 在团队 Wiki 中记录使用方法
- 定期收集反馈并改进
版本控制：
# Skill 文件应该加入 Git 版本控制
git add .claude/
git commit -m "feat: add code-review skill v2.0"
8. 总结和资源
8.1 核心要点总结
-
Skill 是什么
- 可复用的、参数化的 AI 工作流
- 存储在
.claude/目录中的 Markdown 文件 - 用于自动化重复性任务
-
为什么需要 Skill
- 提高效率：从小时级别降到分钟级别
- 保证一致性：统一的标准和流程
- 沉淀知识：最佳实践可以传承
- 减少错误：自动化处理减少人工失误
-
如何创建 Skill
- 创建
.md文件 - 编写 Front Matter 元数据
- 编写清晰的工作流说明
- 提供具体的示例
- 创建
-
Skill 与其他功能的区别
- Skill 是持久化的，可复用的
- Slash Commands 是调用 Skill 的快捷方式
- Tasks/Agents 用于一次性的复杂任务
-
最佳实践
- 单一职责原则
- 清晰的参数定义
- 详细的工作流说明
- 丰富的代码示例
- 明确的质量检查清单
8.2 快速开始清单
- 创建
.claude/目录结构 - 创建你的第一个 Skill 文件
- 编写清晰的元数据和说明
- 提供至少2个示例
- 在 settings.json 中注册 Skill
- 测试 Skill 是否正常工作
- 邀请团队成员使用和反馈
- 根据反馈不断改进 Skill
8.3 常见问题 (FAQ)
Q: Skill 和 MCP Server 有什么区别？
A:
- Skill: 本地 AI 工作流自动化
- MCP Server: 与外部系统集成
Q: 可以在 Skill 中调用其他 Skill 吗？
A: 可以的。Skill 支持嵌套和链式调用。
Q: Skill 文件可以放在其他地方吗？
A: 虽然技术上可以，但建议始终放在 .claude/ 目录以保持一致性。
Q: 如何管理多个版本的 Skill？
A: 在 Front Matter 中使用 version 字段，在 changelog 中记录变更。
8.4 相关资源
- Claude Code 官方文档：https://github.com/anthropics/claude-code
- Claude Code Skill 示例：https://github.com/anthropics/claude-code-examples
- 最佳实践指南：[Your Organization Wiki]
8.5 下一步学习
-
创建你的第一个 Skill
- 选择一个重复性任务
- 创建对应的 Skill
-
与团队分享
- 邀请团队成员使用
- 收集反馈
-
不断改进
- 根据使用情况优化
- 添加新功能
-
探索高级特性
- Skill 的参数化
- Skill 的链式调用
- Skill 与其他功能的集成
结语
Claude Code 的 Skill 功能为我们提供了一个强大的工具来自动化重复性工作。通过合理地设计和使用 Skill，我们可以：
- 提高生产力 - 从手动操作转向自动化工作流
- 保证质量 - 通过统一的标准和最佳实践
- 传承知识 - 将专业知识编码到 Skill 中
- 赋能团队 - 让团队成员快速上手复杂任务
希望这篇文章能够帮助你理解和有效使用 Claude Code 的 Skill 功能。现在就开始创建你的第一个 Skill 吧！
如果有任何疑问，欢迎在评论区留言讨论！
有“AI”的1024 = 2048，欢迎大家加入2048 AI社区
更多推荐
19
0- 0
已为社区贡献1条内容
所有评论(0)