Claude Code Skill 技能使用指南

本文档介绍 Claude Code 技能（Skills）的定义、触发机制和调用方法，帮助您充分利用项目中的技能文件提升开发效率。

---

目录

1. 什么是技能
2. 技能文件结构
3. 技能的存储位置
4. 技能的触发方式
5. 如何调用技能
6. 技能与 CLAUDE.md 的关系
7. 实战示例
8. 故障排除

---

什么是技能

技能（Skills） 是 Claude Code 的一种扩展机制，允许您定义可复用的专业能力和工作流程。

技能的核心价值

价值	说明
角色专业化	定义特定角色（如 Android 工程师、架构师）的专业知识和行为规范
流程标准化	固化重复性工作流程（如代码审查、发布流程）
知识复用	将最佳实践封装为可复用的指令集
上下文控制	精确控制 Claude 可用的工具和行为模式

技能 vs 项目指令

对比项	CLAUDE.md	Skill 文件
加载时机	每次对话自动加载	按需加载或自动检测
作用范围	全局项目规则	特定专业能力
粒度	粗粒度	细粒度、可组合
使用方式	隐式生效	显式调用或条件触发

---

技能文件结构

技能文件使用 .skill.md 扩展名，包含两个主要部分：

1. Frontmatter（元数据）

---
name: skill-name                  # 技能名称（唯一标识）
description: 技能描述              # 简短描述
version: "1.0"                    # 版本号（可选）
tools: [Read, Edit, Write, Bash]  # 允许使用的工具
---

工具列表

可用的工具包括：
- Read - 读取文件
- Edit - 编辑文件
- Write - 创建文件
- Bash - 执行命令
- Glob - 文件搜索
- Grep - 内容搜索
- Agent - 创建子代理

2. 指令内容

# 技能标题

## 角色定义
定义该技能对应的角色身份。

## 工作流程
1. 步骤一
2. 步骤二
3. 步骤三

## 输出格式
规定输出内容的格式规范。

## 注意事项
- 要点一
- 要点二

---

技能的存储位置

Claude Code 从以下位置加载技能文件：

1. 项目级技能（推荐）

项目根目录/
├── .claude/
│   └── skills/
│       ├── skill-name-1.skill.md
│       ├── skill-name-2.skill.md
│       └── README.md          # 技能目录说明
└── ...

特点：
- 跟随项目版本控制
- 团队成员共享
- 针对项目定制

2. 全局技能

~/.claude/skills/              # 用户级全局技能
~/.claude-code/skills/         # 替代路径

特点：
- 跨项目可用
- 个人定制化
- 通用能力封装

3. 当前项目结构

documents/
├── .claude/
│   └── skills/
│       ├── README.md                 # 技能目录索引
│       ├── android-engineer.skill.md # Android 全栈工程师
│       └── review-code.skill.md      # 代码审查技能
└── ...

---

技能的触发方式

技能可以通过三种方式触发：

1. 显式调用（Explicit Invocation）

在对话中直接使用 /skill 命令：

/skill android-engineer
帮我设计一个蓝牙通信模块的架构...

适用场景：
- 明确需要特定专业能力
- 首次使用技能进行测试
- 临时切换角色

2. 自动检测（Auto-detection）

Claude Code 根据对话内容自动识别并建议相关技能。

触发条件：
- 对话中出现技能描述中的关键词
- 文件路径匹配技能关联的目录
- 问题类型符合技能定义的领域

示例：

用户：帮我审查这段 Kotlin 代码的内存泄漏问题
Claude：检测到代码审查需求，建议激活 /skill review-code

3. 自然语言触发（Natural Language）

在提问中直接提及角色或技能相关描述：

请以 Android 全栈工程师的身份，帮我优化这个 RecyclerView 的性能...

效果：Claude 会自动应用对应技能的指令和行为规范。

---

如何调用技能

方法一：命令行调用

# 基本语法
/skill <skill-name>

# 示例
/skill android-engineer
/skill review-code

方法二：自然语言触发

"作为 Android 工程师，帮我设计..."
"使用代码审查模式检查这段代码..."
"以架构师视角评估这个方案..."

方法三：上下文继承

在多轮对话中，已激活的技能会持续生效：

用户：/skill android-engineer
Claude：技能已激活 [android-engineer]

用户：帮我设计蓝牙模块          <-- 自动使用工程师角色
用户：再帮我优化一下网络层      <-- 继续保持该角色

技能调用状态指示

当技能成功激活时，您会看到：

=== 技能已激活：skill-name ===

[技能描述]

当前可用工具: [工具列表]

---

技能与 CLAUDE.md 的关系

协同工作模型

┌─────────────────────────────────────────────────────────┐
│                     对话开始                             │
├─────────────────────────────────────────────────────────┤
│  1. 自动加载 CLAUDE.md                                   │
│     └── 项目规则、目录结构、通用约定                      │
├─────────────────────────────────────────────────────────┤
│  2. 检测/调用 Skill                                      │
│     └── 专业能力、特定工作流程                           │
├─────────────────────────────────────────────────────────┤
│  3. 合并上下文                                           │
│     └── CLAUDE.md + Skill 指令 = 完整行为准则            │
└─────────────────────────────────────────────────────────┘

配置建议

CLAUDE.md 应包含：
- 项目整体架构说明
- 目录结构和命名规范
- 通用开发约定
- 技能文件的引用说明

Skill 文件应包含：
- 特定角色的专业知识
- 具体的工作流程
- 输出格式规范
- 工具使用限制

本项目配置示例

CLAUDE.md（项目指令）：

## 角色配置

本项目配置了 Android 全栈工程师角色，技能文件位于 `.claude/skills/`。

### 可用技能
- `android-engineer` - Android 开发专家
- `review-code` - 代码审查

### 使用方法
- 直接提及角色："请以 Android 工程师身份..."
- 或显式调用：`/skill android-engineer`

.claude/skills/android-engineer.skill.md（专业技能）：

---
name: android-engineer
description: Android 全栈工程师...
tools: [Read, Edit, Write, Bash]
---

## 技术栈
- Kotlin、RxJava、协程
- JT808、北斗三号协议
- WebRTC、蓝牙通信
...

---

实战示例

示例 1：使用 Android 工程师技能

场景：设计一个蓝牙文件传输模块

对话：

用户：/skill android-engineer

Claude：
=== 技能已激活：android-engineer ===
角色：Android 全栈工程师
专注：物联网通信、多网融合...

用户：帮我设计一个基于 Ymodem 协议的蓝牙文件传输模块

Claude：[以 Android 工程师角色输出]
1. 首先分析需求场景...
2. 技术方案设计...
3. 核心代码实现...
4. 注意事项（内存泄漏、生命周期）...

示例 2：使用代码审查技能

场景：审查新提交的代码

对话：

用户：请审查这个 ViewModel 的实现
[粘贴代码]

Claude：检测到代码审查需求，建议激活 /skill review-code

用户：/skill review-code

Claude：[以审查模式输出]
## 代码审查结果

### 🔴 严重问题
1. 协程未绑定生命周期...

### 🟡 改进建议
...

### 🟢 优点
...

示例 3：组合使用

场景：设计多网融合架构并进行审查

对话：

用户：/skill android-engineer
帮我设计一个多网融合通信架构（4G/北斗/自组网）

Claude：[输出设计方案]

用户：/skill review-code
请审查上述方案的潜在问题

Claude：[以审查模式分析方案]

---

故障排除

常见问题

1. 技能未找到

现象：

/skill unknown-skill
错误：未找到技能 'unknown-skill'

解决方案：
- 检查技能文件名是否正确
- 确认技能文件位于 .claude/skills/ 目录
- 查看 README.md 获取可用技能列表

2. 技能未生效

现象：
调用了技能但 Claude 的行为没有变化。

排查步骤：
1. 确认技能文件格式正确（包含 frontmatter）
2. 检查技能名称拼写
3. 尝试重启 Claude Code 或运行 /refresh

3. 工具权限不足

现象：

Claude：我需要使用 Bash 工具执行命令，但当前技能未授权。

解决方案：
在技能文件的 frontmatter 中添加所需工具：

---
tools: [Read, Edit, Write, Bash]
---

调试技巧

1. 验证技能加载：

   /skill <name>
   请简要说明你的角色和能力
   

2. 查看技能列表：

   ls .claude/skills/
   cat .claude/skills/README.md
   

3. 测试技能触发：
   尝试不同的自然语言描述，观察技能是否被自动检测。

---

最佳实践

1. 技能命名

• 使用小写字母和连字符
• 名称简洁、描述性强
• 示例：android-engineer, api-designer, test-writer

2. 技能粒度

• 一个技能聚焦一个专业领域
• 避免过于庞大和复杂的技能
• 相关技能可以组合使用

3. 版本管理

• 技能文件纳入版本控制
• 重大更新时更新版本号
• 保留技能变更历史

4. 文档维护

• 保持 README.md 技能列表最新
• 为每个技能提供使用示例
• 记录技能的适用场景

---

参考资源

• Claude Code 官方文档
• 本项目技能目录：.claude/skills/
• 技能编写指南：ClaudeCode/004-Claude Code 如何写 Skill 技能.md

---

文档版本：1.0
更新日期：2026-03-07
适用项目：documents（Android 开发知识库）