Skills 技能系统入门

Claude Skills 的概念与基本用法

🌐 查看英文原文 | 源码 Notebook

评估者-优化者工作流

Learn how to use Claude’s Skills feature to create professional documents, analyze data, and automate business workflows with Excel, PowerPoint, and PDF generation.

See it in action: The Skills you’ll learn about power Claude’s file creation capabilities! Check out Claude Creates Files to see how these Skills enable Claude to create and edit documents directly in Claude.ai.

1. 设置与安装

前提条件

在开始之前，请确保您已具备以下条件： - Python 3.8 或更高版本 - 从 console.anthropic.com 获取的 Anthropic API 密钥

环境设置（首次设置）

如果您尚未设置环境，请按照以下步骤操作：

第一步：创建虚拟环境

请注意，以下步骤仅适用于首次设置环境。 :::```bash # Navigate to the skills directory cd /path/to/claude-cookbooks/skills

Create virtual environment

python -m venv venv

Activate it

source venv/bin/activate # On macOS/Linux # OR venv# On Windows


#### Step 2: Install Dependencies

```bash
# With venv activated, install requirements
pip install -r requirements.txt
```#### 第3步：在VSCode/Jupyter中选择内核

**在VSCode中：**
1. 打开此笔记本
2. 点击右上角的内核选择器（例如，“Python 3.11.x”）
3. 选择“Python Environments...”
4. 选择 `./venv/bin/python` 解释器

**在Jupyter中：**
1. 从内核菜单 → 更改内核
2. 选择匹配您的 venv 的内核

#### 第4步：配置API密钥```bash
# Copy the example file
cp .env.example .env

# Edit .env and add your API key:
# ANTHROPIC_API_KEY=sk-ant-api03-...
```### 快速安装检查

运行下面的单元格以验证您的环境是否正确设置：

**如果您在上面的内容中看到任何❌或⚠️警告，请在继续之前完成设置步骤。**

**如果anthropic SDK版本太旧（需要0.71.0或更高版本）：**```bash
pip install anthropic>=0.71.0
```然后 **重启Jupyter内核** 以获取新版本。

---

### API配置

现在让我们加载API密钥并配置客户端：

### API配置

**⚠️ 重要**：在skills目录中创建一个`.env`文件：

::: callout-attention
请注意，以下代码块中的变量名和函数名将保持不变。
```python
def process_data(data):
    # 处理数据
    pass
``````bash
# Copy the example file
cp ../.env.example ../.env

Then edit ../.env to add your Anthropic API key.

import os
import sys
from pathlib import Path

# Add parent directory to path for imports
sys.path.insert(0, str(Path.cwd().parent))


from anthropic import Anthropic
from dotenv import load_dotenv

# Import our file utilities
from file_utils import (
    download_all_files,
    extract_file_ids,
    get_file_info,
    print_download_summary,
)

# Load environment variables from parent directory
load_dotenv(Path.cwd().parent / ".env")

API_KEY = os.getenv("ANTHROPIC_API_KEY")
MODEL = os.getenv("ANTHROPIC_MODEL", "claude-sonnet-4-6")

if not API_KEY:
    raise ValueError(
        "ANTHROPIC_API_KEY not found. Copy ../.env.example to ../.env and add your API key."
    )

# Initialize client
# Note: We'll add beta headers per-request when using Skills
client = Anthropic(api_key=API_KEY)

# Create outputs directory if it doesn't exist
OUTPUT_DIR = Path.cwd().parent / "outputs"
OUTPUT_DIR.mkdir(exist_ok=True)

print("✓ API key loaded")
print(f"✓ Using model: {MODEL}")
print(f"✓ Output directory: {OUTPUT_DIR}")
print("\n📝 Note: Beta headers will be added per-request when using Skills")

Test Connection

Let’s verify our API connection works:

# Simple test to verify API connection
test_response = client.messages.create(
    model=MODEL,
    max_tokens=100,
    messages=[
        {
            "role": "user",
            "content": "Say 'Connection successful!' if you can read this.",
        }
    ],
)

print("API Test Response:")
print(test_response.content[0].text)
print(
    f"\n✓ Token usage: {test_response.usage.input_tokens} in, {test_response.usage.output_tokens} out"
)
```## 2. 理解技能 {#understanding}

### 什么是技能？

**技能**是一组有序的指令、可执行代码和资源包，赋予Claude在特定任务上的专业能力。将其视为Claude可以发现和动态加载的“专业知识包”。

📖 阅读我们的工程博客文章 [使用技能为代理装备真实世界的能力](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)

### 技能的重要性

在了解MCPs（模型上下文协议）和工具之后，你可能会想知道为什么技能很重要：

- **技能比单个工具更高级** - 它们结合了指令、代码和资源
- **技能是可组合的** - 多个技能可以无缝协作
- **技能是高效的** - 渐进式披露意味着你只需为所使用的部分付费
- **技能包含经过验证的代码** - 可靠的辅助脚本，节省时间并减少错误

### 主要优势

- **专家级性能**：无需学习曲线即可提供专业结果
- **经过验证的辅助脚本**：技能包含经过测试且可立即使用的代码
- **组织知识**：打包公司工作流程和最佳实践
- **成本效益**：渐进式披露最小化token使用
- **可靠性**：预测试的脚本意味着更少的错误和一致的结果
- **节省时间**：Claude使用现有解决方案而不是从头生成代码
- **可组合性**：多个技能协同工作以实现复杂工作流程

### 渐进式披露架构

技能使用三层加载模型：

![渐进式披露 - 技能如何加载](../assets/prog-disc-1.png)

1. **元数据**（名称：64个字符，描述：1024个字符）：Claude看到技能名称和描述
2. **完整指令**（<5k tokens）：当技能相关时加载
3. **链接文件**：仅在需要时加载附加资源
![渐进式披露阶段](../assets/prog-disc-2.png)

这保持了操作的效率，同时按需提供深入的专业知识。最初，Claude 只看到 SKILL.md 的 YAML 前置信息的元数据。只有当技能相关时，Claude 才会加载完整的内容，包括任何辅助脚本和资源。

### 技能类型

| 类型 | 描述 | 示例 |
|------|-------------|----------|
| **Anthropic-Managed** | 由 Anthropic 维护的预构建技能 | `xlsx`, `pptx`, `pdf`, `docx` |
| **Custom** | 用于特定工作流程的用户定义技能 | 品牌指南，财务模型 |

### 技能概念概述

![技能概念图](../assets/skills-conceptual-diagram.png)

此图说明了：
- **技能目录结构**：技能如何通过 SKILL.md 和支持文件组织
- **YAML 前置信息**：Claude 初始看到的元数据
- **渐进式加载**：技能如何按需发现和加载
- **可组合性**：多个技能在单个请求中协同工作

### 技能与代码执行如何协同工作

技能需要启用 **代码执行** 工具。以下是典型的工作流程：

```python
# 示例代码
def example_function():
    # 代码逻辑
    pass

// 示例 JSON
{
    "key": "value"
}

-- 示例 SQL
SELECT * FROM table_name;
``````python
# Use client.beta.messages.create() for Skills support
response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"}
        ]
    },
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
    messages=[{"role": "user", "content": "Create an Excel file..."}],
    # Use betas parameter instead of extra_headers
    betas=["code-execution-2025-08-25", "files-api-2025-04-14", "skills-2025-10-02"]
)
```**发生什么：**
1. Claude接收到您带有xlsx技能的请求
2. Claude使用代码执行来创建文件
3. 响应中包含创建文件的`file_id`
4. 您使用**文件API**下载文件

**重要：Beta API**
- 使用`client.beta.messages.create()`（而不是`client.messages.create()`）
- `container`参数仅在Beta API中可用
- 使用`betas`参数启用Beta功能：
  - `code-execution-2025-08-25` - 启用代码执行
  - `files-api-2025-04-14` - 下载文件所需
  - `skills-2025-10-02` - 启用技能功能

⚠️ **注意**：当使用技能时，您必须将code_execution工具包含在您的请求中。

### Token使用优化

与在提示中提供指令相比，技能可以显著减少token的使用：

| 方法 | Token成本 | 性能 |
|------|----------|------|
| 手动指令 | 5,000-10,000 tokens/请求 | 变量质量 |
| 技能（仅元数据） | 最小（仅名称/描述） | 专家级 |
| 技能（完全加载） | 使用技能时约为5,000 tokens | 专家级 |

**重大胜利**：您可以在提示中打包多个技能而不会使其膨胀。每个技能仅花费您元数据（名称 + 描述），直到您实际使用它。

**示例**：创建带有格式的Excel文件
- 无技能：解释所有Excel功能需要约8,000 tokens
- 有技能：初始元数据开销最小，仅在调用Excel技能时需要约5,000 tokens
- **关键洞察**：98%的节省适用于初始上下文。一旦使用技能，就会加载完整指令。

**额外好处**：
- 技能包含已知可工作的辅助脚本，提高可靠性
- Claude通过使用经过验证的代码模式而不是从头生成来节省时间
- 您可以获得更一致、更专业的结果

### ⏱️ 预期生成时间
**⚠️ 重要提示**：使用技能生成文档需要执行代码和创建文件，这需要一些时间。请耐心等待，让单元格完成。

**观察到的生成时间：**
- **Excel 文件**：约 2 分钟（包含图表和格式）
- **PowerPoint 演示文稿**：约 1-2 分钟（简单的 2 页演示文稿，包含图表）
- **PDF 文档**：约 40-60 秒（简单的文档）

**预期结果：**
- 运行时单元格将显示 `[*]`
- 您可能会看到 "执行中..." 状态 1-2 分钟
- **不要中断单元格** - 让它完全完成

**💡 建议：**
1. **从简单开始**：使用最小示例来验证您的设置
2. **逐步增加复杂性**：逐步添加功能
3. **耐心等待**：操作通常需要 40 秒到 2 分钟
4. **注意**：非常复杂的文档可能需要更长的时间 - 保持示例集中

## 3. 发现可用技能 {#discovering}

### 列出所有内置技能

让我们发现Anthropic-managed 可用技能：```python
# List all available Anthropic skills
# Note: Skills API requires the skills beta header
client_with_skills_beta = Anthropic(
    api_key=API_KEY, default_headers={"anthropic-beta": "skills-2025-10-02"}
)

skills_response = client_with_skills_beta.beta.skills.list(source="anthropic")

print("Available Anthropic-Managed Skills:")
print("=" * 80)

for skill in skills_response.data:
    print(f"\n📦 Skill ID: {skill.id}")
    print(f"   Title: {skill.display_title}")
    print(f"   Latest Version: {skill.latest_version}")
    print(f"   Created: {skill.created_at}")

    # Get version details
    try:
        version_info = client_with_skills_beta.beta.skills.versions.retrieve(
            skill_id=skill.id, version=skill.latest_version
        )
        print(f"   Name: {version_info.name}")
        print(f"   Description: {version_info.description}")
    except Exception as e:
        print(f"   (Unable to fetch version details: {e})")

print(f"\n\n✓ Found {len(skills_response.data)} Anthropic-managed skills")
```### 理解技能元数据

每个技能都有：
- **skill_id**：唯一标识符（例如，“xlsx”，“pptx”）
- **version**：版本号或“latest”
- **name**：可读名称
- **description**：技能的功能
- **directory**：技能的文件夹结构

### 版本策略

- 对于Anthropic技能使用“latest”（推荐）
- Anthropic会自动更新技能
- 为生产稳定性固定特定版本
- 自定义技能使用纪元时间戳作为版本

### 示例：月度预算电子表格

我们将从两个示例开始——一个简单的单行示例和一个详细的请求。

#### 简单示例（1-2行）
首先，让我们看看技能如何与最小提示一起工作：

```python
# 示例代码
def calculate_budget():
    # 代码逻辑
    pass

{
    "budget": 1000
}

SELECT * FROM budget_table;

请注意，这里的代码示例仅供参考，实际应用时可能需要根据具体情况进行调整。 :::python # Simple prompt - Skills handle the complexity prompt = "Create a quarterly sales report Excel file with revenue data and a chart"#### 详细示例为了获得更多控制，您可以提供具体要求： - 收入和支出类别 - 总计公式 - 基本格式

示例：月度预算电子表格

我们将创建一个简单的预算电子表格，包括： - 收入和支出类别 - 总计公式 - 基本格式

⏱️ 注意：Excel生成通常需要 1-2分钟（包含图表和格式）。在运行过程中单元格将显示 [*] - 请耐心等待！

::: callout-attention
请注意以下重要信息：
- ...
:::
``````python
# Create an Excel budget spreadsheet
excel_response = client.beta.messages.create(  # Note: Using beta.messages for Skills support
    model=MODEL,
    max_tokens=4096,
    container={"skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]},
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
    messages=[
        {
            "role": "user",
            "content": """Create a monthly budget Excel spreadsheet with the following:

Income:
- Salary: $5,000
- Freelance: $1,200
- Investments: $300

Expenses:
- Rent: $1,500
- Utilities: $200
- Groceries: $600
- Transportation: $300
- Entertainment: $400
- Savings: $1,000

Include:
1. Formulas to calculate total income and total expenses
2. A formula for net savings (income - expenses)
3. Format currency values properly
4. Add a simple column chart showing income vs expenses
5. Use professional formatting with headers
""",
        }
    ],
    # Use betas parameter for beta features
    betas=["code-execution-2025-08-25", "files-api-2025-04-14", "skills-2025-10-02"],
)

print("Excel Response:")
print("=" * 80)
for content in excel_response.content:
    if content.type == "text":
        print(content.text)
    elif content.type == "tool_use":
        print(f"\n🔧 Tool: {content.name}")
        if hasattr(content, "input"):
            print(f"   Input preview: {str(content.input)[:200]}...")

print("\n\n📊 Token Usage:")
print(f"   Input: {excel_response.usage.input_tokens}")
print(f"   Output: {excel_response.usage.output_tokens}")
```### 下载Excel文件

现在让我们提取文件_id并下载生成的Excel文件：```python
# Extract file IDs from the response
file_ids = extract_file_ids(excel_response)

if file_ids:
    print(f"✓ Found {len(file_ids)} file(s)\n")

    # Download all files
    results = download_all_files(
        client, excel_response, output_dir=str(OUTPUT_DIR), prefix="budget_"
    )

    # Print summary
    print_download_summary(results)

    # Show file details
    for file_id in file_ids:
        info = get_file_info(client, file_id)
        if info:
            print("\n📄 File Details:")
            print(f"   Filename: {info['filename']}")
            print(f"   Size: {info['size'] / 1024:.1f} KB")
            print(f"   Created: {info['created_at']}")
else:
    print("❌ No files found in response")
    print("\nDebug: Response content types:")
    for i, content in enumerate(excel_response.content):
        print(f"  {i}. {content.type}")
```**✨ 发生了什么？**

1. Claude 使用 `xlsx` 技能创建了一个专业的 Excel 文件
2. 技能处理了所有 Excel 特定的格式和公式
3. 文件是在 Claude 的代码执行环境中创建的
4. 我们从响应中提取了 `file_id`
5. 我们使用 Files API 下载了文件
6. 文件现在已保存在 `outputs/budget_*.xlsx`

在 Excel 中打开文件查看结果！

## 5. 快速入门：PowerPoint {#powerpoint-quickstart}

现在让我们使用 `pptx` 技能创建一个 PowerPoint 演示文稿。

### 示例：收入演示

#### 简单示例（1 行）```python
# Minimal prompt - let Skills handle the details
prompt = "Create an executive summary presentation with 3 slides about Q3 results"
```#### 详细示例
**注意**：有意保持简单（2张幻灯片，1个图表）以最小化生成时间并展示核心功能。

### 示例：简单收入演示

**注意**：有意保持简单（2张幻灯片，1个图表）以最小化生成时间并展示核心功能。```python
# Create a PowerPoint presentation
pptx_response = client.beta.messages.create(
    model=MODEL,
    max_tokens=4096,
    container={"skills": [{"type": "anthropic", "skill_id": "pptx", "version": "latest"}]},
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
    messages=[
        {
            "role": "user",
            "content": """Create a simple 2-slide PowerPoint presentation:

Slide 1: Title slide
- Title: "Q3 2025 Results"
- Subtitle: "Acme Corporation"

Slide 2: Revenue Overview
- Title: "Quarterly Revenue"
- Add a simple column chart showing:
  - Q1: $12M
  - Q2: $13M
  - Q3: $14M

Use clean, professional formatting.
""",
        }
    ],
    betas=["code-execution-2025-08-25", "files-api-2025-04-14", "skills-2025-10-02"],
)

print("PowerPoint Response:")
print("=" * 80)
for content in pptx_response.content:
    if content.type == "text":
        print(content.text)

print("\n\n📊 Token Usage:")
print(f"   Input: {pptx_response.usage.input_tokens}")
print(f"   Output: {pptx_response.usage.output_tokens}")

Download the PowerPoint File

# Download the PowerPoint file
file_ids = extract_file_ids(pptx_response)

if file_ids:
    results = download_all_files(
        client, pptx_response, output_dir=str(OUTPUT_DIR), prefix="q3_review_"
    )

    print_download_summary(results)

    print("\n✅ Open the presentation in PowerPoint or Google Slides to view!")
else:
    print("❌ No files found in response")
```**⏱️ 注意**: PDF生成通常需要**1-2分钟**，对于简单的文档。运行时单元格将显示`[*]` - 请耐心等待！

### 示例：PDF文档

#### 简单示例（1行）```python
# Quick PDF generation
prompt = "Create a professional invoice PDF for $500 consulting services"
```#### 详细示例：收据
**注意**：有意保持简单，以确保格式清晰。

### 示例：简单收据

**注意**：有意保持简单，以确保格式清晰。```python
# Create a PDF receipt
pdf_response = client.beta.messages.create(
    model=MODEL,
    max_tokens=4096,
    container={"skills": [{"type": "anthropic", "skill_id": "pdf", "version": "latest"}]},
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
    messages=[
        {
            "role": "user",
            "content": """Create a simple receipt PDF:

RECEIPT

Acme Corporation
Date: January 15, 2025
Receipt #: RCT-2025-001

Customer: Jane Smith

Items:
- Product A: $50.00
- Product B: $75.00
- Product C: $25.00

Subtotal: $150.00
Tax (8%): $12.00
Total: $162.00

Thank you for your business!

Use simple, clean formatting with clear sections.
""",
        }
    ],
    betas=["code-execution-2025-08-25", "files-api-2025-04-14", "skills-2025-10-02"],
)

print("PDF Response:")
print("=" * 80)
for content in pdf_response.content:
    if content.type == "text":
        print(content.text)

print("\n\n📊 Token Usage:")
print(f"   Input: {pdf_response.usage.input_tokens}")
print(f"   Output: {pdf_response.usage.output_tokens}")

Download and Verify the PDF

# Download the PDF file
file_ids = extract_file_ids(pdf_response)

if file_ids:
    results = download_all_files(
        client, pdf_response, output_dir=str(OUTPUT_DIR), prefix="receipt_"
    )

    print_download_summary(results)

    # Verify PDF integrity
    for result in results:
        if result["success"]:
            file_path = result["output_path"]
            file_size = result["size"]

            # Basic PDF validation
            with open(file_path, "rb") as f:
                header = f.read(5)
                if header == b"%PDF-":
                    print(f"\n✅ PDF file is valid: {file_path}")
                    print(f"   File size: {file_size / 1024:.1f} KB")
                else:
                    print(f"\n⚠️ File may not be a valid PDF: {file_path}")
else:
    print("❌ No files found in response")
```## 7. 故障排除 {#troubleshooting}

### 常见问题和解决方案

### 问题 1：找不到 API 密钥

**错误：**```
ValueError: ANTHROPIC_API_KEY not found
```**解决方案：**
1. 确保父目录中存在 `.env` 文件
2. 检查是否已设置 `ANTHROPIC_API_KEY=sk-ant-api03-...`
3. 在创建/编辑 `.env` 后重启 Jupyter 内核

### 问题 2：容器参数无法识别

**错误：**```
TypeError: Messages.create() got an unexpected keyword argument 'container'
```**解决方案：**
使用 `client.beta.messages.create()` 而不是 `client.messages.create()`：```python
# ✅ Correct - use beta.messages
response = client.beta.messages.create(
    model=MODEL,
    container={"skills": [...]},
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
    messages=[...],
    betas=["code-execution-2025-08-25", "files-api-2025-04-14", "skills-2025-10-02"]
)

# ❌ Incorrect - regular messages doesn't support container
response = client.messages.create(
    model=MODEL,
    container={"skills": [...]},  # Error!
    messages=[...]
)

Issue 3: Skills Beta Requires Code Execution Tool

Error:

BadRequestError: Skills beta requires the code_execution tool to be included in the request.
```**解决方案：**
当使用技能时，您**必须**包含 code_execution 工具：```python
# ✅ Correct
response = client.beta.messages.create(
    model=MODEL,
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
    messages=[...],
    betas=["...", "skills-2025-10-02"]
)

# ❌ Incorrect - missing code_execution tool
response = client.beta.messages.create(
    model=MODEL,
    messages=[...],
    betas=["...", "skills-2025-10-02"]
)

Issue 4: No Files Found in Response

Error: ❌ No files found in response解决方案： 1. 确认请求中包含代码执行工具 2. 验证技能是否已加载（检查响应内容） 3. 确保任务确实需要创建文件 4. 在响应文本中查找错误消息

问题 5：文件下载失败

错误：Error retrieving file: File not found解决方案： 1. 文件在Anthropic的服务器上可能有有限的生命周期 2. 创建文件后立即下载 3. 检查文件_id是否正确从响应中提取 4. 验证Files API测试版是否包含在测试版列表中

Token优化技巧

使用”latest”版本进行Anthropic技能 - 自动优化
批量操作 - 在可能的情况下，在一次对话中创建多个文件
重用容器 - 使用前一次响应中的container.id以避免重新加载技能
具体明确 - 清晰的指令意味着更少的迭代

API速率限制

如果您遇到速率限制： - 实现指数退避重试 - 使用批量处理多个文件 - 考虑升级您的API等级以获得更高的限制

下一步

🎉 恭喜！ 您已经学会了Claude技能的基础知识。

看看技能的实际应用

查看官方公告，了解这些技能如何为Claude的文件创建功能提供动力： - Claude创建文件 - 了解技能如何使Claude能够直接创建和编辑Excel、PowerPoint和PDF文件

继续学习：

笔记本2：金融应用 - 基于金融数据的实际业务用例
笔记本3：自定义技能开发 - 构建您自己的专业技能

支持文章：

📚 使用技能教Claude您的工作方式 - 使用技能的用户指南
🛠️ 如何通过对话使用Claude创建技能 - 交互式技能创建指南

资源：

尝试以下实验：

从简单的单行提示开始，观察技能的实际应用
修改预算示例，包括更多类别
使用您自己的数据创建演示文稿
生成结合文本和表格的PDF报告
在单个请求中使用多个技能

Tip

中文读者提示：本章节的代码和输出为英文原文。如需理解具体实现细节，可参考上方中文导读和代码注释。如有疑问，欢迎在 GitHub Issues 讨论。