458 lines
10 KiB
Markdown
Executable File
458 lines
10 KiB
Markdown
Executable File
# 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)
|