Introduction to Claude Skills (original) (raw)

Introduction to Claude Skills

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. Setup & Installation
  2. Understanding Skills
  3. Discovering Available Skills
  4. Quick Start: Excel
  5. Quick Start: PowerPoint
  6. Quick Start: PDF
  7. Troubleshooting

Before starting, make sure you have:

Environment Setup (First Time Only)

If you haven't set up your environment yet, follow these steps:

Step 1: Create Virtual Environment

# 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\Scripts\activate     # On Windows

Step 2: Install Dependencies

# With venv activated, install requirements
pip install -r requirements.txt

Step 3: Select Kernel in VSCode/Jupyter

In VSCode:

  1. Open this notebook
  2. Click the kernel picker in the top-right (e.g., "Python 3.11.x")
  3. Select "Python Environments..."
  4. Choose the ./venv/bin/python interpreter

In Jupyter:

  1. From the Kernel menu → Change Kernel
  2. Select the kernel matching your venv

Step 4: Configure API Key

# Copy the example file
cp .env.example .env
 
# Edit .env and add your API key:
# ANTHROPIC_API_KEY=sk-ant-api03-...

Run the cell below to verify your environment is set up correctly:

If you see any ❌ or ⚠️ warnings above, please complete the setup steps before continuing.

If anthropic SDK version is too old (needs 0.71.0 or later):

pip install anthropic>=0.71.0

Then restart the Jupyter kernel to pick up the new version.

Now let's load the API key and configure the client:

⚠️ Important: Create a .env file in the skills directory:

# Copy the example file
cp ../.env.example ../.env

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

Let's verify our API connection works:

Skills are organized packages of instructions, executable code, and resources that give Claude specialized capabilities for specific tasks. Think of them as "expertise packages" that Claude can discover and load dynamically.

📖 Read our engineering blog post on Equipping agents for the real world with Skills

After learning about MCPs (Model Context Protocol) and tools, you might wonder why Skills are important:

Progressive Disclosure Architecture

Skills use a three-tier loading model:

Progressive Disclosure - How Skills Load

  1. Metadata (name: 64 chars, description: 1024 chars): Claude sees skill name and description
  2. Full Instructions (<5k tokens): Loaded when skill is relevant
  3. Linked Files: Additional resources loaded only if needed

Progressive Disclosure Stages

This keeps operations efficient while providing deep expertise on demand. Initially, Claude sees just the metadata from the YAML frontmatter of SKILL.md. Only when a skill is relevant does Claude load the full contents, including any helper scripts and resources.

Type Description Example
Anthropic-Managed Pre-built skills maintained by Anthropic xlsx, pptx, pdf, docx
Custom User-defined skills for specific workflows Brand guidelines, financial models

Skills Conceptual Overview

Skills Conceptual Diagram

This diagram illustrates:

How Skills Work with Code Execution

Skills require the code execution tool to be enabled. Here's the typical workflow:

# 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"]
)

What happens:

  1. Claude receives your request with the xlsx skill loaded
  2. Claude uses code execution to create the file
  3. The response includes a file_id for the created file
  4. You use the Files API to download the file

Important: Beta API

⚠️ Note: When using Skills, you MUST include the code_execution tool in your request.

Skills dramatically reduce token usage compared to providing instructions in prompts:

Approach Token Cost Performance
Manual instructions 5,000-10,000 tokens/request Variable quality
Skills (metadata only) Minimal (just name/description) Expert-level
Skills (full load) ~5,000 tokens when skill is used Expert-level

The Big Win: You can pack multiple skills into your prompt without bloating it. Each skill only costs you the metadata (name + description) until you actually use it.

Example: Creating an Excel file with formatting

Additional Benefits:

⏱️ Expected Generation Times

⚠️ IMPORTANT: Document generation with Skills requires code execution and file creation, which takes time. Be patient and let cells complete.

Observed generation times:

What to expect:

💡 Recommendations:

  1. Start simple: Begin with minimal examples to verify your setup
  2. Gradually increase complexity: Add features incrementally
  3. Be patient: Operations typically take 40 seconds to 2 minutes
  4. Note: Very complex documents may take longer - keep examples focused

3. Discovering Available Skills

Let's discover what Anthropic-managed skills are available:

Each skill has:

Example: Monthly Budget Spreadsheet

We'll start with two examples - a simple one-liner and a detailed request.

Simple Example (1-2 lines)

First, let's see how Skills work with a minimal prompt:

# Simple prompt - Skills handle the complexity
prompt = "Create a quarterly sales report Excel file with revenue data and a chart"

For more control, you can provide specific requirements:

Example: Monthly Budget Spreadsheet

We'll create a simple budget spreadsheet with:

⏱️ Note: Excel generation typically takes 1-2 minutes (with charts and formatting). The cell will show [*] while running - be patient!

Now let's extract the file_id and download the generated Excel file:

✨ What just happened?

  1. Claude used the xlsx skill to create a professional Excel file
  2. The skill handled all Excel-specific formatting and formulas
  3. The file was created in Claude's code execution environment
  4. We extracted the file_id from the response
  5. We downloaded the file using the Files API
  6. The file is now saved in outputs/budget_*.xlsx

Open the file in Excel to see the results!

5. Quick Start: PowerPoint

Now let's create a PowerPoint presentation using the pptx skill.

Example: Revenue Presentation

# Minimal prompt - let Skills handle the details
prompt = "Create an executive summary presentation with 3 slides about Q3 results"

Note: This is intentionally kept simple (2 slides, 1 chart) to minimize generation time and demonstrate the core functionality.

Example: Simple Revenue Presentation

Note: This is intentionally kept simple (2 slides, 1 chart) to minimize generation time and demonstrate the core functionality.

Download the PowerPoint File

⏱️ Note: PDF generation typically takes 1-2 minutes for simple documents. The cell will show [*] while running - be patient!

# Quick PDF generation
prompt = "Create a professional invoice PDF for $500 consulting services"

Detailed Example: Receipt

Note: This is intentionally kept simple to ensure clean formatting.

Note: This is intentionally kept simple to ensure clean formatting.

Download and Verify the PDF

Common Issues and Solutions

Issue 1: API Key Not Found

Error:

ValueError: ANTHROPIC_API_KEY not found

Solution:

  1. Ensure .env file exists in the parent directory
  2. Check that ANTHROPIC_API_KEY=sk-ant-api03-... is set
  3. Restart the Jupyter kernel after creating/editing .env

Issue 2: Container Parameter Not Recognized

Error:

TypeError: Messages.create() got an unexpected keyword argument 'container'

**Solution:**Use client.beta.messages.create() instead of client.messages.create():

# ✅ 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=[...]
)

Error:

BadRequestError: Skills beta requires the code_execution tool to be included in the request.

**Solution:**When using Skills, you MUST include the code_execution tool:

# ✅ 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

Solution:

  1. Check that code execution tool is included in the request
  2. Verify the skill was loaded (check response content)
  3. Ensure the task actually requires file creation
  4. Look for error messages in the response text

Issue 5: File Download Failed

Error:

Error retrieving file: File not found

Solution:

  1. Files may have a limited lifetime on Anthropic's servers
  2. Download files immediately after creation
  3. Check file_id is correctly extracted from response
  4. Verify Files API beta is included in betas list

  1. Use "latest" version for Anthropic skills - automatically optimized
  2. Batch operations - Create multiple files in one conversation when possible
  3. Reuse containers - Use container.id from previous responses to avoid reloading skills
  4. Be specific - Clear instructions mean fewer iterations

If you encounter rate limits:

🎉 Congratulations! You've learned the basics of Claude Skills.

Check out the official announcement to see how these Skills power Claude's file creation capabilities:

  1. Start with simple one-line prompts to see Skills in action
  2. Modify the budget example to include more categories
  3. Create a presentation with your own data
  4. Generate a PDF report combining text and tables
  5. Use multiple skills together in a single request