Agent Skills mit der API verwenden

Agent Skills erweitern Claudes Fähigkeiten durch organisierte Ordner mit Anweisungen, Skripten und Ressourcen. Diese Anleitung zeigt Ihnen, wie Sie sowohl vorgefertigte als auch benutzerdefinierte Skills mit der Claude API verwenden.

Für die vollständige API-Referenz einschließlich Request/Response-Schemas und aller Parameter siehe:

Skill Management API Reference - CRUD-Operationen für Skills
Skill Versions API Reference - Versionsverwaltung

Quick Links

Erste Schritte mit Agent Skills

Erstellen Sie Ihren ersten Skill

Benutzerdefinierte Skills erstellen

Best Practices zum Verfassen von Skills

Übersicht

Für einen tieferen Einblick in die Architektur und reale Anwendungen von Agent Skills lesen Sie unseren Engineering-Blog: Equipping agents for the real world with Agent Skills.

Skills integrieren sich über das Code-Ausführungs-Tool mit der Messages API. Ob Sie vorgefertigte Skills verwenden, die von Anthropic verwaltet werden, oder benutzerdefinierte Skills, die Sie hochgeladen haben, ist die Integrationsform identisch – beide erfordern Code-Ausführung und verwenden die gleiche container-Struktur.

Skills verwenden

Skills integrieren sich unabhängig von der Quelle identisch in die Messages API. Sie geben Skills im container-Parameter mit einer skill_id, einem type und einer optionalen version an, und sie werden in der Code-Ausführungsumgebung ausgeführt.

Sie können Skills aus zwei Quellen verwenden:

Aspekt	Anthropic Skills	Benutzerdefinierte Skills
Type-Wert	`anthropic`	`custom`
Skill-IDs	Kurznamen: `pptx`, `xlsx`, `docx`, `pdf`	Generiert: `skill_01AbCdEfGhIjKlMnOpQrStUv`
Versionsformat	Datumsbasiert: `20251013` oder `latest`	Epoch-Zeitstempel: `1759178010641129` oder `latest`

Beide Skill-Quellen werden vom List Skills-Endpunkt zurückgegeben (verwenden Sie den source-Parameter zum Filtern). Die Integrationsform und die Ausführungsumgebung sind identisch – der einzige Unterschied ist, woher die Skills stammen und wie sie verwaltet werden.

Voraussetzungen

Um Skills zu verwenden, benötigen Sie:

Anthropic API-Schlüssel aus der Console
Beta-Header:
- code-execution-2025-08-25 - Aktiviert Code-Ausführung (erforderlich für Skills)
- skills-2025-10-02 - Aktiviert Skills API
- files-api-2025-04-14 - Zum Hochladen/Herunterladen von Dateien zum/vom Container
Code-Ausführungs-Tool in Ihren Anfragen aktiviert

Skills in Messages verwenden

Container-Parameter

Skills werden mit dem container-Parameter in der Messages API angegeben. Sie können bis zu 8 Skills pro Anfrage einschließen.

Die Struktur ist für Anthropic und benutzerdefinierte Skills identisch – geben Sie den erforderlichen type und die skill_id an und schließen Sie optional version ein, um an eine bestimmte Version gebunden zu sein:

Heruntergeladene generierte Dateien

Wenn Skills Dokumente erstellen (Excel, PowerPoint, PDF, Word), geben sie file_id-Attribute in der Antwort zurück. Sie müssen die Files API verwenden, um diese Dateien herunterzuladen.

So funktioniert es:

Skills erstellen Dateien während der Code-Ausführung
Die Antwort enthält file_id für jede erstellte Datei
Verwenden Sie die Files API, um den tatsächlichen Dateiinhalt herunterzuladen
Speichern Sie lokal oder verarbeiten Sie nach Bedarf

Beispiel: Erstellen und Herunterladen einer Excel-Datei

Zusätzliche Files API-Operationen:

Für vollständige Details zur Files API siehe die Files API-Dokumentation.

Mehrteilige Konversationen

Verwenden Sie denselben Container über mehrere Nachrichten hinweg, indem Sie die Container-ID angeben:

Langfristige Operationen

Skills können Operationen durchführen, die mehrere Durchläufe erfordern. Behandeln Sie pause_turn-Stoppgründe:

Die Antwort kann einen pause_turn-Stoppgrund enthalten, der anzeigt, dass die API eine langfristige Skill-Operation unterbrochen hat. Sie können die Antwort in einer nachfolgenden Anfrage unverändert bereitstellen, um Claude seinen Durchlauf fortsetzen zu lassen, oder Sie können den Inhalt ändern, wenn Sie das Gespräch unterbrechen und zusätzliche Anleitung geben möchten.

Mehrere Skills verwenden

Kombinieren Sie mehrere Skills in einer einzigen Anfrage, um komplexe Workflows zu bewältigen:

Benutzerdefinierte Skills verwalten

Einen Skill erstellen

Laden Sie Ihren benutzerdefinierten Skill hoch, um ihn in Ihrem Workspace verfügbar zu machen. Sie können entweder einen Verzeichnispfad oder einzelne Dateiobjekte hochladen.

Anforderungen:

Muss eine SKILL.md-Datei auf der obersten Ebene enthalten
Alle Dateien müssen ein gemeinsames Stammverzeichnis in ihren Pfaden angeben
Die Gesamtgröße des Uploads muss unter 8 MB liegen
YAML-Frontmatter-Anforderungen:
- name: Maximal 64 Zeichen, nur Kleinbuchstaben/Zahlen/Bindestriche, keine XML-Tags, keine reservierten Wörter ("anthropic", "claude")
- description: Maximal 1024 Zeichen, nicht leer, keine XML-Tags

Für vollständige Request/Response-Schemas siehe die Create Skill API-Referenz.

Skills auflisten

Rufen Sie alle Skills ab, die für Ihren Workspace verfügbar sind, einschließlich vorgefertigter Anthropic Skills und Ihrer benutzerdefinierten Skills. Verwenden Sie den source-Parameter zum Filtern nach Skill-Typ:

Siehe die List Skills API-Referenz für Paginierungs- und Filteroptionen.

Einen Skill abrufen

Rufen Sie Details zu einem bestimmten Skill ab:

Einen Skill löschen

Um einen Skill zu löschen, müssen Sie zuerst alle seine Versionen löschen:

Der Versuch, einen Skill mit vorhandenen Versionen zu löschen, gibt einen 400-Fehler zurück.

Versionierung

Skills unterstützen Versionierung, um Updates sicher zu verwalten:

Von Anthropic verwaltete Skills:

Versionen verwenden Datumsformat: 20251013
Neue Versionen werden als Updates veröffentlicht
Geben Sie genaue Versionen für Stabilität an

Benutzerdefinierte Skills:

Automatisch generierte Epoch-Zeitstempel: 1759178010641129
Verwenden Sie "latest", um immer die neueste Version zu erhalten
Erstellen Sie neue Versionen beim Aktualisieren von Skill-Dateien

Siehe die Create Skill Version API-Referenz für vollständige Details.

Wie Skills geladen werden

Wenn Sie Skills in einem Container angeben:

Metadaten-Erkennung: Claude sieht Metadaten für jeden Skill (Name, Beschreibung) in der Systemaufforderung
Datei-Laden: Skill-Dateien werden in den Container unter /skills/{directory}/ kopiert
Automatische Verwendung: Claude lädt und verwendet Skills automatisch, wenn sie für Ihre Anfrage relevant sind
Komposition: Mehrere Skills arbeiten zusammen für komplexe Workflows

Die progressive Offenlegungsarchitektur gewährleistet eine effiziente Kontextnutzung – Claude lädt vollständige Skill-Anweisungen nur bei Bedarf.

Anwendungsfälle

Organisatorische Skills

Marke & Kommunikation

Wenden Sie unternehmensspezifische Formatierung (Farben, Schriftarten, Layouts) auf Dokumente an
Generieren Sie Kommunikationen nach Organisationsvorlagen
Stellen Sie sicher, dass Markenrichtlinien in allen Ausgaben konsistent sind

Projektmanagement

Strukturieren Sie Notizen mit unternehmensspezifischen Formaten (OKRs, Entscheidungsprotokolle)
Generieren Sie Aufgaben nach Team-Konventionen
Erstellen Sie standardisierte Besprechungsnotizen und Statusaktualisierungen

Geschäftsbetrieb

Erstellen Sie unternehmensstandard-Berichte, Vorschläge und Analysen
Führen Sie unternehmensspezifische analytische Verfahren durch
Generieren Sie Finanzmodelle nach Organisationsvorlagen

Persönliche Skills

Inhaltserstellung

Benutzerdefinierte Dokumentvorlagen
Spezialisierte Formatierung und Gestaltung
Domänenspezifische Inhaltsgenerierung

Datenanalyse

Benutzerdefinierte Datenverarbeitungs-Pipelines
Spezialisierte Visualisierungsvorlagen
Branchenspezifische analytische Methoden

Entwicklung & Automatisierung

Code-Generierungsvorlagen
Test-Frameworks
Bereitstellungs-Workflows

Beispiel: Finanzmodellierung

Kombinieren Sie Excel und benutzerdefinierte DCF-Analyse-Skills:

Limits und Einschränkungen

Anfrage-Limits

Maximale Skills pro Anfrage: 8
Maximale Skill-Upload-Größe: 8 MB (alle Dateien zusammen)
YAML-Frontmatter-Anforderungen:
- name: Maximal 64 Zeichen, nur Kleinbuchstaben/Zahlen/Bindestriche, keine XML-Tags, keine reservierten Wörter
- description: Maximal 1024 Zeichen, nicht leer, keine XML-Tags

Umgebungseinschränkungen

Skills werden im Code-Ausführungs-Container mit diesen Einschränkungen ausgeführt:

Kein Netzwerkzugriff - Können keine externen API-Aufrufe tätigen
Keine Laufzeit-Paketinstallation - Nur vorinstallierte Pakete verfügbar
Isolierte Umgebung - Jede Anfrage erhält einen neuen Container

Siehe die Code-Ausführungs-Tool-Dokumentation für verfügbare Pakete.

Best Practices

Wann mehrere Skills verwendet werden sollten

Kombinieren Sie Skills, wenn Aufgaben mehrere Dokumenttypen oder Domänen betreffen:

Gute Anwendungsfälle:

Datenanalyse (Excel) + Präsentationserstellung (PowerPoint)
Berichtsgenerierung (Word) + Export zu PDF
Benutzerdefinierte Domänenlogik + Dokumentgenerierung

Vermeiden Sie:

Einschließen ungenutzter Skills (beeinträchtigt die Leistung)

Versionsverwaltungsstrategie

Für Produktion:

# Pin to specific versions for stability
container={
    "skills": [{
        "type": "custom",
        "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
        "version": "1759178010641129"  # Specific version
    }]
}

Für Entwicklung:

# Use latest for active development
container={
    "skills": [{
        "type": "custom",
        "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
        "version": "latest"  # Always get newest
    }]
}

Prompt-Caching-Überlegungen

Beachten Sie bei Verwendung von Prompt-Caching, dass das Ändern der Skills-Liste in Ihrem Container den Cache bricht:

Für beste Caching-Leistung halten Sie Ihre Skills-Liste über Anfragen hinweg konsistent.

Fehlerbehandlung

Behandeln Sie Skill-bezogene Fehler elegant:

Nächste Schritte

API-Referenz

Vollständige API-Referenz mit allen Endpunkten

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {
                "type": "anthropic",
                "skill_id": "pptx",
                "version": "latest"
            }
        ]
    },
    messages=[{
        "role": "user",
        "content": "Create a presentation about renewable energy"
    }],
    tools=[{
        "type": "code_execution_20250825",
        "name": "code_execution"
    }]
)

import anthropic

client = anthropic.Anthropic()

# Step 1: Use a Skill to create a file
response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"}
        ]
    },
    messages=[{
        "role": "user",
        "content": "Create an Excel file with a simple budget spreadsheet"
    }],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

# Step 2: Extract file IDs from the response
def extract_file_ids(response):
    file_ids = []
    for item in response.content:
        if item.type == 'bash_code_execution_tool_result':
            content_item = item.content
            if content_item.type == 'bash_code_execution_result':
                for file in content_item.content:
                    if hasattr(file, 'file_id'):
                        file_ids.append(file.file_id)
    return file_ids

# Step 3: Download the file using Files API
for file_id in extract_file_ids(response):
    file_metadata = client.beta.files.retrieve_metadata(
        file_id=file_id,
        betas=["files-api-2025-04-14"]
    )
    file_content = client.beta.files.download(
        file_id=file_id,
        betas=["files-api-2025-04-14"]
    )

    # Step 4: Save to disk
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")

# Get file metadata
file_info = client.beta.files.retrieve_metadata(
    file_id=file_id,
    betas=["files-api-2025-04-14"]
)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

# List all files
files = client.beta.files.list(betas=["files-api-2025-04-14"])
for file in files.data:
    print(f"{file.filename} - {file.created_at}")

# Delete a file
client.beta.files.delete(
    file_id=file_id,
    betas=["files-api-2025-04-14"]
)

# First request creates container
response1 = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"}
        ]
    },
    messages=[{"role": "user", "content": "Analyze this sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

# Continue conversation with same container
messages = [
    {"role": "user", "content": "Analyze this sales data"},
    {"role": "assistant", "content": response1.content},
    {"role": "user", "content": "What was the total revenue?"}
]

response2 = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "id": response1.container.id,  # Reuse container
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"}
        ]
    },
    messages=messages,
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

messages = [{"role": "user", "content": "Process this large dataset"}]
max_retries = 10

response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {"type": "custom", "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv", "version": "latest"}
        ]
    },
    messages=messages,
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

# Handle pause_turn for long operations
for i in range(max_retries):
    if response.stop_reason != "pause_turn":
        break

    messages.append({"role": "assistant", "content": response.content})
    response = client.beta.messages.create(
        model="claude-sonnet-4-5-20250929",
        max_tokens=4096,
        betas=["code-execution-2025-08-25", "skills-2025-10-02"],
        container={
            "id": response.container.id,
            "skills": [
                {"type": "custom", "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv", "version": "latest"}
            ]
        },
        messages=messages,
        tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
    )

response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {
                "type": "anthropic",
                "skill_id": "xlsx",
                "version": "latest"
            },
            {
                "type": "anthropic",
                "skill_id": "pptx",
                "version": "latest"
            },
            {
                "type": "custom",
                "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                "version": "latest"
            }
        ]
    },
    messages=[{
        "role": "user",
        "content": "Analyze sales data and create a presentation"
    }],
    tools=[{
        "type": "code_execution_20250825",
        "name": "code_execution"
    }]
)

import anthropic

client = anthropic.Anthropic()

# Option 1: Using files_from_dir helper (Python only, recommended)
from anthropic.lib import files_from_dir

skill = client.beta.skills.create(
    display_title="Financial Analysis",
    files=files_from_dir("/path/to/financial_analysis_skill"),
    betas=["skills-2025-10-02"]
)

# Option 2: Using a zip file
skill = client.beta.skills.create(
    display_title="Financial Analysis",
    files=[("skill.zip", open("financial_analysis_skill.zip", "rb"))],
    betas=["skills-2025-10-02"]
)

# Option 3: Using file tuples (filename, file_content, mime_type)
skill = client.beta.skills.create(
    display_title="Financial Analysis",
    files=[
        ("financial_skill/SKILL.md", open("financial_skill/SKILL.md", "rb"), "text/markdown"),
        ("financial_skill/analyze.py", open("financial_skill/analyze.py", "rb"), "text/x-python"),
    ],
    betas=["skills-2025-10-02"]
)

print(f"Created skill: {skill.id}")
print(f"Latest version: {skill.latest_version}")

# List all Skills
skills = client.beta.skills.list(
    betas=["skills-2025-10-02"]
)

for skill in skills.data:
    print(f"{skill.id}: {skill.display_title} (source: {skill.source})")

# List only custom Skills
custom_skills = client.beta.skills.list(
    source="custom",
    betas=["skills-2025-10-02"]
)

skill = client.beta.skills.retrieve(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    betas=["skills-2025-10-02"]
)

print(f"Skill: {skill.display_title}")
print(f"Latest version: {skill.latest_version}")
print(f"Created: {skill.created_at}")

# Step 1: Delete all versions
versions = client.beta.skills.versions.list(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    betas=["skills-2025-10-02"]
)

for version in versions.data:
    client.beta.skills.versions.delete(
        skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
        version=version.version,
        betas=["skills-2025-10-02"]
    )

# Step 2: Delete the Skill
client.beta.skills.delete(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    betas=["skills-2025-10-02"]
)

# Create a new version
from anthropic.lib import files_from_dir

new_version = client.beta.skills.versions.create(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    files=files_from_dir("/path/to/updated_skill"),
    betas=["skills-2025-10-02"]
)

# Use specific version
response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [{
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": new_version.version
        }]
    },
    messages=[{"role": "user", "content": "Use updated Skill"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

# Use latest version
response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [{
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "latest"
        }]
    },
    messages=[{"role": "user", "content": "Use latest Skill version"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

# Create custom DCF analysis Skill
from anthropic.lib import files_from_dir

dcf_skill = client.beta.skills.create(
    display_title="DCF Analysis",
    files=files_from_dir("/path/to/dcf_skill"),
    betas=["skills-2025-10-02"]
)

# Use with Excel to create financial model
response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
            {"type": "custom", "skill_id": dcf_skill.id, "version": "latest"}
        ]
    },
    messages=[{
        "role": "user",
        "content": "Build a DCF valuation model for a SaaS company with the attached financials"
    }],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

# First request creates cache
response1 = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02", "prompt-caching-2024-07-31"],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"}
        ]
    },
    messages=[{"role": "user", "content": "Analyze sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

# Adding/removing Skills breaks cache
response2 = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02", "prompt-caching-2024-07-31"],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"},
            {"type": "anthropic", "skill_id": "pptx", "version": "latest"}  # Cache miss
        ]
    },
    messages=[{"role": "user", "content": "Create a presentation"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

try:
    response = client.beta.messages.create(
        model="claude-sonnet-4-5-20250929",
        max_tokens=4096,
        betas=["code-execution-2025-08-25", "skills-2025-10-02"],
        container={
            "skills": [
                {"type": "custom", "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv", "version": "latest"}
            ]
        },
        messages=[{"role": "user", "content": "Process data"}],
        tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
    )
except anthropic.BadRequestError as e:
    if "skill" in str(e):
        print(f"Skill error: {e}")
        # Handle skill-specific errors
    else:
        raise