Claude Code Skills 完全指南

前言

Claude Code Skills 是 Claude Code CLI 工具的核心扩展机制，允许开发者将专业知识、工作流程和最佳实践封装为可复用的 AI 能力。通过 Skills，你可以让 Claude 掌握特定领域的专业技能，从代码规范、测试策略到复杂的开发工作流，都能实现自动化和标准化。

本文将深入介绍 Skills 的概念、创建方法、使用技巧和最佳实践，帮助你充分发挥 Claude Code 的潜力。

Skills 是什么

Skills 是一种结构化的提示词（Prompt）封装机制，它将专业知识、工作流程和操作指南打包成可调用的 AI 能力单元。每个 Skill 包含：

• 明确的触发条件：定义何时应该使用这个 Skill
• 详细的执行指令：告诉 Claude 如何完成任务
• 参考文档：提供必要的背景知识和规范
• 示例和模板：展示预期的输出格式

Skills 的核心价值

为什么需要 Skills

1. 知识复用

将一次性的专业知识转化为可重复使用的能力，避免每次都要重新解释。

示例场景：

• 代码审查标准
• 测试驱动开发流程
• 特定框架的使用规范
• 安全编码准则

2. 流程标准化

确保团队成员遵循统一的开发流程和质量标准。

示例场景：

• Git 提交规范（Conventional Commits）
• PR 创建流程
• 代码重构步骤
• 调试方法论

3. 团队协作

通过共享 Skills，让整个团队的 AI 助手具备相同的专业能力。

示例场景：

• 公司代码规范
• 项目特定的架构模式
• 领域特定语言（DSL）
• 内部工具使用指南

4. 效率提升

减少重复性的指令输入，让 Claude 自动遵循最佳实践。

示例场景：

• 自动化测试生成
• 代码审查检查清单
• 性能优化步骤
• 文档生成模板

Skills 的类型

1. 流程型 Skills（Process Skills）

定义完整的工作流程，指导 Claude 按步骤完成复杂任务。

特点：

• 包含明确的步骤序列
• 有检查点和验证环节
• 适合多阶段任务

示例：

• test-driven-development: TDD 开发流程
• systematic-debugging: 系统化调试方法
• writing-plans: 实施计划编写

2. 规范型 Skills（Standard Skills）

定义编码规范、命名约定和质量标准。

特点：

• 包含详细的规则和约束
• 提供正反示例
• 适合代码审查和生成

示例：

• java-dev: Java 开发规范
• code-review: 代码审查标准
• commit: Git 提交规范

3. 工具型 Skills（Tool Skills）

封装特定工具或框架的使用方法。

特点：

• 聚焦特定技术栈
• 包含配置和使用示例
• 适合技术集成

示例：

• mcp-builder: MCP 服务器构建
• frontend-design: 前端设计系统
• skill-creator: Skills 创建工具

4. 知识型 Skills（Knowledge Skills）

提供领域知识和参考文档。

特点：

• 包含丰富的背景信息
• 提供决策依据
• 适合学习和查询

示例：

• claude-code-guide: Claude Code 使用指南
• using-superpowers: Superpowers 使用说明
• skill-lookup: Skills 查找和安装

Skills 的结构

基本结构

一个标准的 Skill 文件（SKILL.md）包含以下部分：

---
name: skill-name
description: 简短描述（一句话说明用途）
---

# Skill 标题

## 使用场景
明确说明何时应该使用这个 Skill

## 核心原则
列出关键的指导原则

## 执行步骤
详细的操作步骤

## 检查清单
验证任务完成的检查项

## 示例
实际使用示例

## 注意事项
常见陷阱和最佳实践

高级结构（多文件 Skills）

复杂的 Skills 可以包含多个文件：

.claude/skills/my-skill/
├── SKILL.md           # 主文件（必需）
├── reference.md       # 参考文档
├── examples/          # 示例代码
│   ├── example1.java
│   └── example2.java
├── templates/         # 模板文件
│   └── template.md
└── scripts/           # 辅助脚本
    └── helper.sh

创建 Skills

方法 1：使用 skill-creator Skill

最简单的方式是使用内置的 skill-creator Skill：

# 在 Claude Code 中调用
/skill-creator

Claude 会引导你完成 Skill 创建过程：

1. 确定 Skill 的用途和触发场景
2. 定义核心原则和执行步骤
3. 添加示例和检查清单
4. 生成 SKILL.md 文件

方法 2：手动创建

1. 创建 Skill 目录：

mkdir -p .claude/skills/my-skill

2. 编写 SKILL.md：

---
name: my-skill
description: 我的自定义 Skill
---

# My Skill

## 使用场景
当需要执行 XXX 任务时使用此 Skill

## 执行步骤
1. 第一步：...
2. 第二步：...
3. 第三步：...

## 检查清单
- [ ] 检查项 1
- [ ] 检查项 2

3. 测试 Skill：

# 在 Claude Code 中调用
/my-skill

方法 3：从 prompts.chat 安装

使用 skill-lookup Skill 从社区获取现成的 Skills：

# 搜索 Skills
/skill-lookup "关键词"

# 安装 Skill
# Claude 会提示你确认安装

使用 Skills

基本调用

在 Claude Code 对话中使用 / 前缀调用 Skill：

# 调用 Skill
/skill-name

# 带参数调用
/skill-name 参数1 参数2

# 示例
/code-review main
/commit
/test-driven-development

Skills 的执行流程

Skills 的优先级

当多个 Skills 可能适用时，遵循以下优先级：

1. 用户显式调用：/skill-name 优先级最高
2. 流程型 Skills：如 brainstorming、debugging
3. 实施型 Skills：如 frontend-design、mcp-builder
4. 规范型 Skills：如 java-dev、code-review

Skills 组合使用

多个 Skills 可以组合使用，形成完整的工作流：

# 示例：完整的功能开发流程
/brainstorming          # 1. 需求澄清
/writing-plans          # 2. 编写计划
/test-driven-development # 3. TDD 实施
/code-review            # 4. 代码审查
/commit                 # 5. 提交代码

最佳实践

1. 明确触发条件

好的示例：

## 使用场景
当用户要求"实现新功能"、"添加特性"或"开发模块"时，
在编写任何代码之前，必须使用此 Skill 进行需求澄清。

不好的示例：

## 使用场景
用于开发功能

2. 提供具体步骤

好的示例：

## 执行步骤
1. 读取现有代码结构（使用 Glob 工具）
2. 分析依赖关系（检查 import 语句）
3. 生成测试用例（遵循 AAA 模式）
4. 实施代码（TDD 红-绿-重构循环）
5. 运行测试验证（使用 Bash 工具）

不好的示例：

## 执行步骤
1. 分析代码
2. 写测试
3. 实现功能

3. 包含检查清单

## 检查清单
- [ ] 所有测试通过
- [ ] 代码符合项目规范
- [ ] 添加了必要的注释
- [ ] 更新了相关文档
- [ ] 没有引入安全漏洞

4. 提供示例

## 示例

### 输入
用户请求："添加用户认证功能"

### 输出
1. 需求澄清问题：
   - 使用哪种认证方式（JWT/Session/OAuth）？
   - 需要支持哪些登录方式（邮箱/手机/第三方）？
   - 密码策略要求是什么？

2. 技术方案：
   - 使用 JWT 进行无状态认证
   - 密码使用 bcrypt 加密
   - 实现 refresh token 机制

5. 说明注意事项

## 注意事项
- ⚠️ 不要在日志中输出敏感信息（密码、token）
- ⚠️ 确保所有输入都经过验证和清理
- ⚠️ 使用参数化查询防止 SQL 注入
- ✅ 优先使用成熟的安全库，不要自己实现加密算法

6. 保持简洁和聚焦

每个 Skill 应该专注于一个明确的任务或领域：

好的示例：

• test-driven-development: 专注于 TDD 流程
• code-review: 专注于代码审查
• commit: 专注于 Git 提交

不好的示例：

• everything: 试图涵盖所有开发任务
• general-helper: 没有明确的职责边界

实际案例

案例 1：Java 开发规范 Skill

---
name: java-dev
description: Java 开发代码规范，包含命名约定、Lombok 使用、日志规范等
---

# Java 开发规范

## 使用场景
当进行 Java 开发、编写 Java 代码、修改 Java 文件时自动触发

## 核心原则

### 1. 命名规范
- 类名：大驼峰（PascalCase）
- 方法名：小驼峰（camelCase）
- 常量：全大写下划线分隔（UPPER_SNAKE_CASE）
- 包名：全小写，使用点分隔

### 2. Lombok 使用
- 优先使用 `@Slf4j` 而非手动创建 Logger
- 使用 `@RequiredArgsConstructor` 进行依赖注入
- 避免使用 `@Data`，改用 `@Getter` + `@Setter`

### 3. 金额计算
- 必须使用 `BigDecimal`，禁止使用 `double` 或 `float`
- 使用 `BigDecimal(String)` 构造器，避免精度丢失

### 4. 日志规范
- 使用占位符 `{}` 而非字符串拼接
- 异常日志必须包含堆栈信息
- 敏感信息不得输出到日志

## 检查清单
- [ ] 所有金额字段使用 BigDecimal
- [ ] 日志使用 @Slf4j 和占位符
- [ ] 依赖注入使用构造器注入
- [ ] 类和方法有完整的 Javadoc
- [ ] 没有使用已废弃的 API

## 示例

### 正确示例
\`\`\`java
@Slf4j
@Service
@RequiredArgsConstructor
public class OrderService {
    private final OrderRepository orderRepository;

    public BigDecimal calculateTotal(List<OrderItem> items) {
        BigDecimal total = BigDecimal.ZERO;
        for (OrderItem item : items) {
            total = total.add(item.getPrice()
                .multiply(new BigDecimal(item.getQuantity())));
        }
        log.info("订单总额计算完成: {}", total);
        return total;
    }
}
\`\`\`

### 错误示例
\`\`\`java
public class OrderService {
    private static final Logger log = LoggerFactory.getLogger(OrderService.class);

    @Autowired
    private OrderRepository orderRepository;

    public double calculateTotal(List<OrderItem> items) {
        double total = 0.0;  // ❌ 使用 double 计算金额
        for (OrderItem item : items) {
            total += item.getPrice() * item.getQuantity();
        }
        log.info("订单总额: " + total);  // ❌ 字符串拼接
        return total;
    }
}
\`\`\`

案例 2：系统化调试 Skill

---
name: systematic-debugging
description: 系统化调试方法，用于定位和修复 bug
---

# 系统化调试

## 使用场景
当遇到任何 bug、测试失败或意外行为时，在提出修复方案之前使用此 Skill

## 执行步骤

### 1. 重现问题
- 确认问题的触发条件
- 记录错误信息和堆栈跟踪
- 确定问题的影响范围

### 2. 收集信息
- 读取相关代码文件
- 检查最近的代码变更（git log）
- 查看测试用例和日志

### 3. 形成假设
- 基于错误信息推断可能的原因
- 列出 2-3 个最可能的假设
- 按可能性排序

### 4. 验证假设
- 设计验证实验（添加日志、断点、测试）
- 逐个验证假设
- 记录验证结果

### 5. 实施修复
- 编写修复代码
- 添加或更新测试用例
- 验证修复效果

### 6. 防止复发
- 分析根本原因
- 考虑是否需要重构
- 更新文档或添加注释

## 检查清单
- [ ] 问题已成功重现
- [ ] 收集了所有相关信息
- [ ] 形成了明确的假设
- [ ] 假设已被验证
- [ ] 修复已通过测试
- [ ] 考虑了防止复发的措施

## 示例

### 问题
测试失败：`NullPointerException in UserService.getUserById()`

### 调试过程
1. **重现**：调用 `getUserById(999)` 时抛出 NPE
2. **收集信息**：
   - 读取 UserService.java
   - 检查数据库查询逻辑
   - 查看测试用例
3. **假设**：
   - 假设 1：数据库返回 null 但未检查
   - 假设 2：缓存返回 null
   - 假设 3：ID 格式错误
4. **验证**：
   - 添加日志确认数据库返回 null
   - 假设 1 验证通过
5. **修复**：
   - 添加 null 检查
   - 抛出 UserNotFoundException
6. **防止复发**：
   - 添加测试用例覆盖 null 情况
   - 更新文档说明异常处理

案例 3：Git 提交规范 Skill

---
name: commit
description: 智能 Git 提交工具，分析代码变更并生成符合 Conventional Commits 规范的提交信息
---

# 智能 Git 提交

## 使用场景
当用户要求"提交代码"、"创建 commit"或使用 `/commit` 命令时

## 执行步骤

### 1. 分析变更
\`\`\`bash
# 查看未暂存的变更
git status

# 查看详细差异
git diff
git diff --staged
\`\`\`

### 2. 确定提交类型
根据变更内容确定类型：
- `feat`: 新功能
- `fix`: Bug 修复
- `refactor`: 重构（不改变功能）
- `docs`: 文档更新
- `style`: 代码格式调整
- `test`: 测试相关
- `chore`: 构建/工具配置

### 3. 生成提交信息
格式：`<type>(<scope>): <subject>`

示例：
- `feat(auth): 添加 JWT 认证功能`
- `fix(order): 修复订单金额计算精度问题`
- `refactor(user): 优化用户查询性能`

### 4. 执行提交
\`\`\`bash
# 暂存文件
git add <files>

# 提交
git commit -m "$(cat <<'EOF'
<type>(<scope>): <subject>

<body>
EOF
)"
\`\`\`

### 5. 验证提交
\`\`\`bash
git log -1
git status
\`\`\`

## 检查清单
- [ ] 提交信息符合 Conventional Commits 规范
- [ ] 提交范围合理（不过大也不过小）
- [ ] 没有包含敏感信息（密码、密钥）
- [ ] 没有包含不相关的文件
- [ ] 提交信息清晰描述了变更内容

## 注意事项
- ⚠️ 不要提交 `.env`、`credentials.json` 等敏感文件
- ⚠️ 不要使用 `git add .` 或 `git add -A`，明确指定文件
- ⚠️ 提交前确保代码已通过编译和测试
- ✅ 提交信息使用中文，清晰易懂
- ✅ 一次提交只做一件事

Skills 管理

查看已安装的 Skills

# 列出所有 Skills
ls .claude/skills/

# 查看 Skill 内容
cat .claude/skills/skill-name/SKILL.md

更新 Skills

# 手动编辑
vim .claude/skills/skill-name/SKILL.md

# 或使用 skill-creator 更新
/skill-creator
# 选择"更新现有 Skill"

分享 Skills

方法 1：Git 仓库

# 将 .claude/skills 目录提交到 Git
git add .claude/skills/
git commit -m "docs: 添加自定义 Skills"
git push

方法 2：发布到 prompts.chat

使用 prompts.chat MCP 工具发布：

# 在 Claude Code 中
/skill-lookup
# 选择"发布 Skill"

删除 Skills

# 删除 Skill 目录
rm -rf .claude/skills/skill-name

高级技巧

1. Skills 继承和组合

创建一个"元 Skill"来组合多个 Skills：

---
name: full-stack-dev
description: 全栈开发工作流，组合前端和后端 Skills
---

# 全栈开发工作流

## 执行步骤
1. 使用 `/brainstorming` 澄清需求
2. 使用 `/writing-plans` 编写实施计划
3. 后端开发：
   - 调用 `/java-dev` 遵循 Java 规范
   - 调用 `/test-driven-development` 进行 TDD
4. 前端开发：
   - 调用 `/frontend-design` 设计界面
   - 调用 `/test-driven-development` 编写测试
5. 使用 `/code-review` 审查代码
6. 使用 `/commit` 提交变更

2. 条件触发

在 Skill 中定义条件逻辑：

## 执行步骤
1. 检查项目类型：
   - 如果是 Java 项目 → 调用 `/java-dev`
   - 如果是 TypeScript 项目 → 调用 `/typescript-dev`
   - 如果是 Python 项目 → 调用 `/python-dev`
2. 继续后续步骤...

3. 参数化 Skills

支持动态参数的 Skill：

---
name: deploy
description: 部署应用到指定环境
---

# 应用部署

## 使用方法
\`\`\`bash
/deploy <environment>
# environment: dev | staging | production
\`\`\`

## 执行步骤
1. 验证参数：
   - 检查 environment 是否有效
   - 确认部署权限
2. 根据环境执行不同的部署策略：
   - dev: 直接部署，无需审批
   - staging: 需要 Tech Lead 审批
   - production: 需要 Tech Lead + PM 审批

4. Skills 版本管理

为 Skills 添加版本信息：

---
name: java-dev
version: 2.1.0
description: Java 开发规范
changelog:
  - 2.1.0: 添加 JDK 21 新特性支持
  - 2.0.0: 重构 Lombok 使用规范
  - 1.0.0: 初始版本
---

常见问题

Q1: Skill 没有被触发怎么办？

解决方案：

1. 检查 Skill 的触发条件是否明确
2. 尝试显式调用：/skill-name
3. 查看 .claude/skills/ 目录确认 Skill 已安装
4. 检查 SKILL.md 文件格式是否正确

Q2: 如何调试 Skill？

解决方案：

1. 在 Skill 中添加详细的日志输出
2. 使用 AskUserQuestion 工具与用户交互
3. 分步骤执行，每步确认结果
4. 查看 Claude Code 的输出日志

Q3: Skills 之间有冲突怎么办？

解决方案：

1. 明确每个 Skill 的职责边界
2. 使用优先级机制（显式调用 > 流程型 > 规范型）
3. 在 Skill 中说明与其他 Skills 的关系
4. 必要时合并或重构冲突的 Skills

Q4: 如何让团队成员使用相同的 Skills？

解决方案：

1. 将 .claude/skills/ 目录提交到 Git
2. 在项目 README 中说明 Skills 的使用方法
3. 定期同步和更新 Skills
4. 使用 CI/CD 验证 Skills 的有效性

总结

Claude Code Skills 是一个强大的扩展机制，它让你能够：

1. 封装专业知识：将领域专长转化为可复用的 AI 能力
2. 标准化流程：确保团队遵循统一的开发规范
3. 提升效率：减少重复性工作，专注于创造性任务
4. 持续改进：通过迭代优化 Skills，不断提升开发体验

下一步行动

1. 探索现有 Skills：使用 /skill-lookup 发现社区 Skills
2. 创建第一个 Skill：使用 /skill-creator 封装你的专业知识
3. 分享给团队：将 Skills 提交到项目仓库
4. 持续优化：根据使用反馈改进 Skills

相关资源

• Claude Code 官方文档
• Prompts.chat Skills 社区
• Conventional Commits 规范
• Claude Agent SDK

---

最后更新: 2026-01-24
作者: Claude Code 社区
版本: 1.0.0