agent-aide/docs/reference/02-技能指南.md

# Claude Code 技能（Skills）指南

## 概述

Agent Skills（技能）是模块化的能力包，用于扩展 Claude 的功能。与斜杠命令不同，技能是由 Claude 根据用户请求**自动激活**的，而非用户显式调用。

### 核心特性

- **模型调用**：Claude 根据任务上下文自主决定何时使用技能
- **可发现性**：Claude 通过技能的 description 了解何时使用
- **可共享**：通过 git 或插件在团队间分发
- **可组合**：多个技能可以协同处理复杂任务

## 技能存储位置

| 类型 | 位置 | 适用场景 |
|------|------|----------|
| 个人技能 | `~/.claude/skills/` | 个人工作流、实验性技能、跨所有项目可用 |
| 项目技能 | `.claude/skills/` | 团队工作流、项目特定专业知识、通过 git 自动共享 |
| 插件技能 | 插件 `skills/` 目录 | 通过插件安装自动可用 |

## 技能文件结构

### 基本结构

每个技能是一个包含 `SKILL.md` 文件的目录：

```
my-skill/
├── SKILL.md           # 必需：技能定义文件
├── FORMS.md           # 可选：专题文档
├── REFERENCE.md       # 可选：API 参考
└── scripts/           # 可选：辅助脚本
    └── helper.py
```

### SKILL.md 文件格式

```yaml
---
name: your-skill-name
description: 简要描述技能的功能和使用场景。当用户需要...时使用。
allowed-tools: Read, Grep, Glob    # 可选：限制可用工具
---

# 技能名称

## 说明
提供清晰的分步指导。

## 示例
展示具体的使用示例。
```

### 字段要求

| 字段 | 要求 | 限制 |
|------|------|------|
| `name` | 必需 | 小写字母、数字和连字符，最多 64 字符 |
| `description` | 必需 | 描述功能和使用时机，最多 1024 字符 |
| `allowed-tools` | 可选 | 逗号分隔的工具列表，限制技能可使用的工具 |

## Description 编写指南

> **关键原则**：`description` 是技能的**主要发现机制**，Claude 根据它决定何时使用技能。

### 必须包含的内容

1. **技能做什么** - 核心功能描述
2. **什么时候使用它** - 明确的触发条件
3. **用户可能提到的关键词** - 帮助匹配用户请求

### 示例对比

❌ **太模糊**：
```yaml
description: Helps with documents
```

✅ **具体明确**：
```yaml
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
```

✅ **另一个好例子**：
```yaml
description: Analyze Excel spreadsheets, create pivot tables, and generate charts. Use when working with Excel files, spreadsheets, or analyzing tabular data in .xlsx format.
```

## 渐进式披露

技能使用渐进式披露来高效管理上下文：

- **SKILL.md** 仅在技能被触发时加载
- **附加文件**（如 FORMS.md、REFERENCE.md）仅在 Claude 需要时按需加载

这意味着你可以在技能目录中包含大量参考资料，而不会浪费上下文空间。

## 快速开始

### 创建个人技能

```bash
# 创建技能目录
mkdir -p ~/.claude/skills/commit-helper

# 创建 SKILL.md 文件
cat > ~/.claude/skills/commit-helper/SKILL.md << 'EOF'
---
name: commit-helper
description: 从 git diff 生成清晰的提交信息。当编写提交信息或审查暂存变更时使用。
---

# 提交信息生成器

## 说明

1. 运行 `git diff --staged` 查看变更
2. 我会建议一个提交信息，包含：
   - 50 字符以内的摘要
   - 详细描述
   - 受影响的组件

## 最佳实践

- 使用现在时态
- 说明"做了什么"和"为什么"，而非"怎么做"
EOF
```

### 创建项目技能

```bash
# 创建项目技能目录
mkdir -p .claude/skills/code-reviewer

# 创建 SKILL.md 文件
cat > .claude/skills/code-reviewer/SKILL.md << 'EOF'
---
name: code-reviewer
description: 审查代码的最佳实践和潜在问题。当审查代码、检查 PR 或分析代码质量时使用。
allowed-tools: Read, Grep, Glob
---

# 代码审查器

## 审查清单

1. 代码组织和结构
2. 错误处理
3. 性能考虑
4. 安全隐患
5. 测试覆盖率

## 说明

1. 使用 Read 工具查看目标文件
2. 使用 Grep 搜索模式
3. 使用 Glob 查找相关文件
4. 提供详细的代码质量反馈
EOF
```

## 技能工作原理

### 自动发现机制

Claude 自动发现三个位置的技能：
- `~/.claude/skills/`（个人）
- `.claude/skills/`（项目）
- 已安装插件的技能目录

### 查看可用技能

```
有哪些可用的技能？
```
或
```
列出所有可用的技能
```

### 智能激活

技能通过 description 匹配自动激活：

```
# 用户请求
帮我从这个 PDF 中提取文本

# Claude 自动激活匹配的技能（如 pdf-processing 技能）
```

## 工具限制

使用 `allowed-tools` 限制技能可以使用的工具：

```yaml
---
name: safe-file-reader
description: 只读方式访问文件。当需要只读文件访问且不进行修改时使用。
allowed-tools: Read, Grep, Glob
---
```

**适用场景**：
- 只读技能（不应修改文件）
- 限定范围技能（仅数据分析，不写文件）
- 安全敏感工作流

## 实用示例

### 示例1：简单技能（单文件）

```yaml
---
name: api-documenter
description: 为 API 端点生成文档。当需要记录 REST API、GraphQL 接口或函数签名时使用。
---

# API 文档生成器

## 说明

1. 分析代码中的 API 端点
2. 生成包含以下内容的文档：
   - 端点路径和方法
   - 请求参数
   - 响应格式
   - 示例请求

## 文档格式

使用 OpenAPI 3.0 规范格式。
```

### 示例2：带工具限制的技能

```yaml
---
name: safe-file-reader
description: 只读方式访问文件。当需要只读文件访问且不进行修改时使用。
allowed-tools: Read, Grep, Glob
---

# 安全文件读取器

## 说明

此技能仅使用只读工具：
- Read：读取文件内容
- Grep：搜索文件内容
- Glob：查找文件

## 使用场景

- 代码审查（不修改）
- 日志分析
- 配置检查
```

### 示例3：多文件技能

**目录结构：**
```
pdf-processing/
├── SKILL.md
├── FORMS.md
├── REFERENCE.md
└── scripts/
    ├── fill_form.py
    └── validate.py
```

**SKILL.md：**
```yaml
---
name: pdf-processing
description: 提取文本、填写表单、合并 PDF。当处理 PDF 文件、表单或文档提取时使用。需要 pypdf 和 pdfplumber 包。
---

# PDF 处理

## 快速开始

提取文本：
```python
import pdfplumber
with pdfplumber.open("doc.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

表单填写请参阅 [FORMS.md](FORMS.md)。
详细 API 参考请参阅 [REFERENCE.md](REFERENCE.md)。

## 依赖

```bash
pip install pypdf pdfplumber
```
```

### 示例4：数据库操作技能

```yaml
---
name: db-migration-helper
description: 帮助创建和管理数据库迁移。当需要创建迁移脚本、修改数据库架构或执行数据迁移时使用。
---

# 数据库迁移助手

## 支持的数据库

- PostgreSQL
- MySQL
- SQLite

## 迁移流程

1. 分析当前架构
2. 生成迁移脚本
3. 验证迁移安全性
4. 提供回滚方案

## 最佳实践

- 始终创建回滚脚本
- 在测试环境先验证
- 大表修改分批进行
```

## 团队共享技能

### 方式1：通过 Git（项目技能）

```bash
# 添加到项目
mkdir -p .claude/skills/team-skill
# 创建 SKILL.md...

# 提交到仓库
git add .claude/skills/
git commit -m "添加团队技能"
git push

# 团队成员拉取后自动可用
git pull
claude  # 技能立即可用
```

### 方式2：通过插件（推荐）

1. 创建包含 `skills/` 目录的插件
2. 将插件添加到市场
3. 团队成员安装插件即可使用

## 管理技能

### 更新技能

```bash
# 编辑 SKILL.md
code ~/.claude/skills/my-skill/SKILL.md

# 重启 Claude Code 使更改生效
```

### 删除技能

```bash
# 删除个人技能
rm -rf ~/.claude/skills/my-skill

# 删除项目技能
rm -rf .claude/skills/my-skill
git commit -m "移除不再使用的技能"
```

## 故障排除

### Claude 没有使用我的技能

**检查1：Description 是否足够具体**
- 包含 WHAT（做什么）和 WHEN（何时使用）
- 使用用户可能提到的具体关键词
- 避免模糊描述

**检查2：YAML 语法是否有效**
```bash
# 查看 frontmatter
cat .claude/skills/my-skill/SKILL.md | head -n 15

# 常见问题：
# - 缺少开头/结尾的 ---
# - 使用 Tab 而非空格
# - 特殊字符未加引号
```

**检查3：文件路径是否正确**
```bash
# 个人技能
ls ~/.claude/skills/*/SKILL.md

# 项目技能
ls .claude/skills/*/SKILL.md
```

**检查4：使用调试模式**
```bash
claude --debug
```

### 技能执行出错

- 检查依赖项是否已安装
- 确保脚本有执行权限：`chmod +x scripts/*.py`
- 使用正斜杠路径：`scripts/helper.py` ✅（而非 `scripts\helper.py` ❌）

## 技能与斜杠命令的区别

| 方面 | Agent Skills | 斜杠命令 |
|------|--------------|----------|
| **调用方式** | 模型自动调用 | 用户显式调用（`/command`） |
| **发现机制** | 基于 description | 基于 `/` 前缀 |
| **复杂度** | 复杂能力包 | 简单提示 |
| **文件结构** | 目录 + SKILL.md + 资源 | 单个 .md 文件 |
| **适用场景** | 扩展 Claude 能力 | 快速重复任务 |

**选择建议**：
- 使用**斜杠命令**：快速、常用的提示（review、explain、optimize）
- 使用 **Skills**：包含脚本、跨文件知识、团队标准化的综合工作流

## 最佳实践

| 实践 | 说明 |
|------|------|
| **保持专注** | 一个技能解决一个能力（如"PDF 表单填充"而非"文档处理"） |
| **清晰描述** | 包含具体触发条件，如"当处理 Excel 文件、电子表格时使用" |
| **测试验证** | 技能是否在预期情况下激活？说明是否清晰？ |
| **版本记录** | 在 SKILL.md 中记录版本历史 |

```markdown
# 我的技能

## 版本历史
- v2.0.0 (2025-10-01): 重大 API 变更
- v1.1.0 (2025-09-15): 添加新功能
- v1.0.0 (2025-09-01): 初始版本
```

## 相关资源

- [自定义斜杠命令指南](./01-自定义斜杠命令指南.md)
- [Plugins 插件指南](./03-插件指南.md)
- [Plugin Marketplaces 插件市场指南](./04-插件市场指南.md)
- [官方文档：Agent Skills](https://code.claude.com/docs/en/skills)