MessagesSkills

Agent Skills mit der API verwenden

Erfahre, wie du Agent Skills verwendest, um die Fähigkeiten von Claude über die API zu erweitern.

Agent Skills erweitern die Fähigkeiten von Claude durch organisierte Ordner mit Anweisungen, Skripten und Ressourcen. Diese Anleitung zeigt dir, wie du sowohl vorgefertigte als auch benutzerdefinierte Skills mit der Claude API verwendest.

Die vollständige API-Referenz einschließlich Request-/Response-Schemata und aller Parameter findest du hier:

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

Diese Funktion ist nicht für Zero Data Retention (ZDR) qualifiziert. Daten werden gemäß der standardmäßigen Aufbewahrungsrichtlinie der Funktion gespeichert.

Schnellzugriff

Erste Schritte mit Agent Skills

Erstelle deinen ersten Skill

Benutzerdefinierte Skills erstellen

Best Practices für das Erstellen von Skills

Überblick

Für einen tieferen Einblick in die Architektur und praktische Anwendungen von Agent Skills lies den Engineering-Blogbeitrag: Equipping agents for the real world with Agent Skills.

Skills integrieren sich über das Code-Execution-Tool in die Messages API. Unabhängig davon, ob du vorgefertigte, von Anthropic verwaltete Skills oder selbst hochgeladene benutzerdefinierte Skills verwendest, ist die Integrationsform identisch: Beide erfordern Code-Ausführung und verwenden dieselbe container-Struktur.

Skills verwenden

Skills integrieren sich unabhängig von ihrer Quelle identisch in die Messages API. Du gibst Skills im container-Parameter mit einer skill_id, einem type und optional einer version an, und sie werden in der Code-Execution-Umgebung ausgeführt.

Du kannst 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`
Verwaltung	Vorgefertigt und von Anthropic gepflegt	Hochladen und Verwalten über die Skills API
Verfügbarkeit	Für alle Nutzer verfügbar	Privat für deinen Workspace

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

Voraussetzungen

Um Skills zu verwenden, benötigst du:

Claude API-Key aus der Console
Beta-Header:
- code-execution-2025-08-25 – Aktiviert Code-Ausführung (erforderlich für Skills)
- skills-2025-10-02 – Aktiviert die Skills API
- files-api-2025-04-14 – Zum Hoch-/Herunterladen von Dateien in/aus dem Container
Code-Execution-Tool in deinen Requests aktiviert

Skills in Messages verwenden

Container-Parameter

Skills werden über den container-Parameter in der Messages API angegeben. Du kannst bis zu 8 Skills pro Request einbinden.

Die Struktur ist für Anthropic- und benutzerdefinierte Skills identisch. Gib die erforderlichen Felder type und skill_id an und füge optional version hinzu, um eine bestimmte Version festzulegen:

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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"}],
)

Generierte Dateien herunterladen

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

So funktioniert es:

Skills erstellen Dateien während der Code-Ausführung
Die Response enthält eine file_id für jede erstellte Datei
Verwende die Files API, um den eigentlichen Dateiinhalt herunterzuladen
Speichere lokal oder verarbeite nach Bedarf

Beispiel: Eine Excel-Datei erstellen und herunterladen

client = anthropic.Anthropic()

# Schritt 1: Verwende einen Skill, um eine Datei zu erstellen
response = client.beta.messages.create(
    model="claude-opus-4-8",
    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"}],
)


# Schritt 2: Extrahiere Datei-IDs aus der Antwort
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":
                # konkret typisierte Liste: List[BashCodeExecutionOutputBlock]
                for file in content_item.content:
                    file_ids.append(file.file_id)
    return file_ids


# Schritt 3: Lade die Datei über die Files API herunter
for file_id in extract_file_ids(response):
    file_metadata = client.beta.files.retrieve_metadata(file_id=file_id)
    file_content = client.beta.files.download(file_id=file_id)

    # Schritt 4: Speichere auf der Festplatte
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")

Weitere Files-API-Operationen:

client = anthropic.Anthropic()
file_id = "file_abc123"
# Rufe Datei-Metadaten ab
file_info = client.beta.files.retrieve_metadata(file_id=file_id)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

# Liste alle Dateien auf
files = client.beta.files.list()
for file in files.data:
    print(f"{file.filename} - {file.created_at}")

# Lösche eine Datei
client.beta.files.delete(file_id=file_id)

Vollständige Details zur Files API findest du in der Files-API-Dokumentation.

Multi-Turn-Konversationen

Verwende denselben Container über mehrere Nachrichten hinweg, indem du die Container-ID angibst:

# Erste Anfrage erstellt Container
response1 = client.beta.messages.create(
    model="claude-opus-4-8",
    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"}],
)

# Setze Konversation mit demselben Container fort
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-opus-4-8",
    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"}],
)

Lang laufende Operationen

Skills können Operationen ausführen, die mehrere Turns erfordern. Behandle pause_turn-Stop-Reasons:

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

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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"}],
)

# Behandle pause_turn für lange Operationen
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-opus-4-8",
        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"}],
    )

Die Response kann einen pause_turn-Stop-Reason enthalten, der anzeigt, dass die API eine lang laufende Skill-Operation pausiert hat. Du kannst die Response unverändert in einem nachfolgenden Request zurückgeben, damit Claude seinen Turn fortsetzt, oder den Inhalt ändern, wenn du die Konversation unterbrechen und zusätzliche Anweisungen geben möchtest.

Mehrere Skills verwenden

Kombiniere mehrere Skills in einem einzigen Request, um komplexe Workflows zu bewältigen:

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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"}],
)

Benutzerdefinierte Skills verwalten

Einen Skill erstellen

Ein Skill-Bundle ist ein Verzeichnis, das auf oberster Ebene eine SKILL.md-Datei mit name- und description-YAML-Frontmatter enthält, sowie alle unterstützenden Skripte oder Ressourcen. Siehe Erste Schritte mit Agent Skills in der API, um einen zu erstellen, und die Liste Anforderungen nach den Beispielen für die vollständigen Einschränkungen.

Lade deinen benutzerdefinierten Skill hoch, um ihn in deinem Workspace verfügbar zu machen. Du kannst ein Zip-Archiv oder einzelne Dateiobjekte hochladen; das Python-SDK bietet zusätzlich einen files_from_dir-Helper, der einen Verzeichnispfad akzeptiert.

# Option 1: Einzelne Dateien hochladen (ein --file-Flag pro Datei)
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_skill/SKILL.md \
  --file financial_skill/analyze.py \
  --beta skills-2025-10-02

# Option 2: Ein Zip-Archiv hochladen
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_analysis_skill.zip \
  --beta skills-2025-10-02

Anforderungen:

Muss eine SKILL.md-Datei auf oberster Ebene enthalten
Alle Dateien müssen in ihren Pfaden ein gemeinsames Wurzelverzeichnis angeben
Die Gesamtgröße des Uploads muss unter 30 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

Vollständige Request-/Response-Schemata findest du in der Create Skill API-Referenz.

Skills auflisten

Rufe alle Skills ab, die in deinem Workspace verfügbar sind, einschließlich vorgefertigter Anthropic-Skills und deiner benutzerdefinierten Skills. Verwende den source-Parameter, um nach Skill-Typ zu filtern:

# Liste alle Skills auf
ant beta:skills list

# Liste nur benutzerdefinierte Skills auf
ant beta:skills list --source custom

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

Einen Skill abrufen

Rufe Details zu einem bestimmten Skill ab:

ant beta:skills retrieve \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv

Einen Skill löschen

Um einen Skill zu löschen, musst du zuerst alle seine Versionen löschen:

# Schritt 1: Liste die Versionen auf und lösche dann jede einzelne
ant beta:skills:versions list \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --transform version --raw-output

# Wiederhole dies für jede Versions-ID, die die Liste zurückgegeben hat
ant beta:skills:versions delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --version 20260115.120000 >/dev/null

# Schritt 2: Lösche den Skill
ant beta:skills delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null

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:

Anthropic-Skills:

Versionen verwenden das Datumsformat: 20251013
Neue Versionen werden veröffentlicht, wenn Updates vorgenommen werden
Gib exakte Versionen für Stabilität an

Benutzerdefinierte Skills:

Automatisch generierte Epoch-Zeitstempel: 1759178010641129
Verwende "latest", um immer die neueste Version zu erhalten
Erstelle neue Versionen, wenn du Skill-Dateien aktualisierst

# Erstelle eine neue Version
VERSION_NUMBER=$(ant beta:skills:versions create \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --file updated_skill/SKILL.md \
  --transform version --raw-output)

# Verwende eine bestimmte Version
ant beta:messages create \
  --beta code-execution-2025-08-25 \
  --beta skills-2025-10-02 <<YAML
model: claude-opus-4-8
max_tokens: 4096
container:
  skills:
    - type: custom
      skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
      version: $VERSION_NUMBER
messages:
  - role: user
    content: Use updated Skill
tools:
  - type: code_execution_20250825
    name: code_execution
YAML

# Verwende die neueste Version
ant beta:messages create \
  --beta code-execution-2025-08-25 \
  --beta skills-2025-10-02 <<'YAML'
model: claude-opus-4-8
max_tokens: 4096
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
YAML

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

Wie Skills geladen werden

Wenn du Skills in einem Container angibst:

Metadaten-Erkennung: Claude sieht Metadaten für jeden Skill (Name, Beschreibung) im System-Prompt
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 deine Anfrage relevant sind
Komposition: Mehrere Skills lassen sich für komplexe Workflows kombinieren

Die „progressive disclosure"-Architektur (schrittweise Offenlegung) sorgt für effiziente Kontextnutzung: Claude lädt vollständige Skill-Anweisungen nur bei Bedarf.

Anwendungsfälle

Organisationsweite Skills

Marke & Kommunikation

Unternehmensspezifische Formatierung (Farben, Schriftarten, Layouts) auf Dokumente anwenden
Kommunikation nach organisatorischen Vorlagen generieren
Konsistente Markenrichtlinien über alle Ausgaben hinweg sicherstellen

Projektmanagement

Notizen mit unternehmensspezifischen Formaten strukturieren (OKRs, Entscheidungsprotokolle)
Aufgaben nach Teamkonventionen generieren
Standardisierte Meeting-Zusammenfassungen und Status-Updates erstellen

Geschäftsbetrieb

Unternehmensstandard-Berichte, -Angebote und -Analysen erstellen
Unternehmensspezifische Analyseverfahren ausführen
Finanzmodelle nach organisatorischen Vorlagen generieren

Persönliche Skills

Content-Erstellung

Benutzerdefinierte Dokumentvorlagen
Spezialisierte Formatierung und Gestaltung
Domänenspezifische Content-Generierung

Datenanalyse

Benutzerdefinierte Datenverarbeitungs-Pipelines
Spezialisierte Visualisierungsvorlagen
Branchenspezifische Analysemethoden

Entwicklung & Automatisierung

Code-Generierungsvorlagen
Test-Frameworks
Deployment-Workflows

Beispiel: Finanzmodellierung

Kombiniere Excel- und benutzerdefinierte DCF-Analyse-Skills:

# Erstelle benutzerdefinierten DCF-Analyse-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"),
)

# Verwende mit Excel, um ein Finanzmodell zu erstellen
response = client.beta.messages.create(
    model="claude-opus-4-8",
    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"}],
)
print(response)

Limits und Einschränkungen

Request-Limits

Maximale Skills pro Request: 8
Maximale Skill-Upload-Größe: 30 MB (alle Dateien zusammen)
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

Umgebungseinschränkungen

Skills laufen im Code-Execution-Container mit diesen Einschränkungen:

Kein Netzwerkzugriff: Keine externen API-Aufrufe möglich
Keine Paketinstallation zur Laufzeit: Nur vorinstallierte Pakete verfügbar
Isolierte Umgebung: Container sind isoliert; ein neuer Container wird erstellt, sofern du keine bestehende Container-ID angibst

Siehe Code-Execution-Tool für verfügbare Pakete.

Best Practices

Wann mehrere Skills verwendet werden sollten

Kombiniere Skills, wenn Aufgaben mehrere Dokumenttypen oder Domänen umfassen:

Gute Anwendungsfälle:

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

Vermeide:

Einbinden ungenutzter Skills (beeinträchtigt die Performance)

Strategie zur Versionsverwaltung

Für Produktion:

# Fixiere auf bestimmte Versionen für Stabilität
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "1759178010641129",  # Specific version
        }
    ]
}

Für Entwicklung:

# Verwende latest für die aktive Entwicklung
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "latest",  # Always get newest
        }
    ]
}

Überlegungen zum Prompt-Caching

Beachte bei der Verwendung von Prompt-Caching, dass eine Änderung der Skills-Liste in deinem Container den Cache ungültig macht:

# Erste Anfrage erstellt den Cache
response1 = client.beta.messages.create(
    model="claude-opus-4-8",
    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"}],
)

# Hinzufügen/Entfernen von Skills macht den Cache ungültig
response2 = client.beta.messages.create(
    model="claude-opus-4-8",
    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"}],
)

Für optimale Caching-Performance halte deine Skills-Liste über Requests hinweg konsistent.

Fehlerbehandlung

Behandle Skill-bezogene Fehler elegant:

client = anthropic.Anthropic()

try:
    response = client.beta.messages.create(
        model="claude-opus-4-8",
        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}")
        # Behandle Skill-spezifische Fehler
    else:
        raise

Datenaufbewahrung

Agent Skills sind nicht durch ZDR-Vereinbarungen abgedeckt. Skill-Definitionen und Ausführungsdaten werden gemäß der Standard-Datenaufbewahrungsrichtlinie von Anthropic aufbewahrt.

Informationen zur ZDR-Eignung für alle Funktionen findest du unter API und Datenaufbewahrung.

Nächste Schritte

API-Referenz

Vollständige API-Referenz mit allen Endpunkten

Authoring-Leitfaden

Best Practices für das Schreiben effektiver Skills

Code-Execution-Tool

Erfahre mehr über die Code-Execution-Umgebung

Was this page helpful?

MessagesSkills

Agent Skills mit der API verwenden

Erfahre, wie du Agent Skills verwendest, um die Fähigkeiten von Claude über die API zu erweitern.

Die vollständige API-Referenz einschließlich Request-/Response-Schemata und aller Parameter findest du hier:

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

Diese Funktion ist nicht für Zero Data Retention (ZDR) qualifiziert. Daten werden gemäß der standardmäßigen Aufbewahrungsrichtlinie der Funktion gespeichert.

Schnellzugriff

Erste Schritte mit Agent Skills

Erstelle deinen ersten Skill

Benutzerdefinierte Skills erstellen

Best Practices für das Erstellen von Skills

Überblick

Für einen tieferen Einblick in die Architektur und praktische Anwendungen von Agent Skills lies den Engineering-Blogbeitrag: Equipping agents for the real world with Agent Skills.

Skills verwenden

Du kannst 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`
Verwaltung	Vorgefertigt und von Anthropic gepflegt	Hochladen und Verwalten über die Skills API
Verfügbarkeit	Für alle Nutzer verfügbar	Privat für deinen Workspace

Voraussetzungen

Um Skills zu verwenden, benötigst du:

Claude API-Key aus der Console
Beta-Header:
- code-execution-2025-08-25 – Aktiviert Code-Ausführung (erforderlich für Skills)
- skills-2025-10-02 – Aktiviert die Skills API
- files-api-2025-04-14 – Zum Hoch-/Herunterladen von Dateien in/aus dem Container
Code-Execution-Tool in deinen Requests aktiviert

Skills in Messages verwenden

Container-Parameter

Skills werden über den container-Parameter in der Messages API angegeben. Du kannst bis zu 8 Skills pro Request einbinden.

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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"}],
)

Generierte Dateien herunterladen

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

So funktioniert es:

Skills erstellen Dateien während der Code-Ausführung
Die Response enthält eine file_id für jede erstellte Datei
Verwende die Files API, um den eigentlichen Dateiinhalt herunterzuladen
Speichere lokal oder verarbeite nach Bedarf

Beispiel: Eine Excel-Datei erstellen und herunterladen

client = anthropic.Anthropic()

# Schritt 1: Verwende einen Skill, um eine Datei zu erstellen
response = client.beta.messages.create(
    model="claude-opus-4-8",
    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"}],
)


# Schritt 2: Extrahiere Datei-IDs aus der Antwort
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":
                # konkret typisierte Liste: List[BashCodeExecutionOutputBlock]
                for file in content_item.content:
                    file_ids.append(file.file_id)
    return file_ids


# Schritt 3: Lade die Datei über die Files API herunter
for file_id in extract_file_ids(response):
    file_metadata = client.beta.files.retrieve_metadata(file_id=file_id)
    file_content = client.beta.files.download(file_id=file_id)

    # Schritt 4: Speichere auf der Festplatte
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")

Weitere Files-API-Operationen:

client = anthropic.Anthropic()
file_id = "file_abc123"
# Rufe Datei-Metadaten ab
file_info = client.beta.files.retrieve_metadata(file_id=file_id)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

# Liste alle Dateien auf
files = client.beta.files.list()
for file in files.data:
    print(f"{file.filename} - {file.created_at}")

# Lösche eine Datei
client.beta.files.delete(file_id=file_id)

Vollständige Details zur Files API findest du in der Files-API-Dokumentation.

Multi-Turn-Konversationen

Verwende denselben Container über mehrere Nachrichten hinweg, indem du die Container-ID angibst:

# Erste Anfrage erstellt Container
response1 = client.beta.messages.create(
    model="claude-opus-4-8",
    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"}],
)

# Setze Konversation mit demselben Container fort
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-opus-4-8",
    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"}],
)

Lang laufende Operationen

Skills können Operationen ausführen, die mehrere Turns erfordern. Behandle pause_turn-Stop-Reasons:

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

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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"}],
)

# Behandle pause_turn für lange Operationen
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-opus-4-8",
        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"}],
    )

Mehrere Skills verwenden

Kombiniere mehrere Skills in einem einzigen Request, um komplexe Workflows zu bewältigen:

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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"}],
)

Benutzerdefinierte Skills verwalten

Einen Skill erstellen

# Option 1: Einzelne Dateien hochladen (ein --file-Flag pro Datei)
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_skill/SKILL.md \
  --file financial_skill/analyze.py \
  --beta skills-2025-10-02

# Option 2: Ein Zip-Archiv hochladen
ant beta:skills create \
  --display-title "Financial Analysis" \
  --file financial_analysis_skill.zip \
  --beta skills-2025-10-02

Anforderungen:

Muss eine SKILL.md-Datei auf oberster Ebene enthalten
Alle Dateien müssen in ihren Pfaden ein gemeinsames Wurzelverzeichnis angeben
Die Gesamtgröße des Uploads muss unter 30 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

Vollständige Request-/Response-Schemata findest du in der Create Skill API-Referenz.

Skills auflisten

# Liste alle Skills auf
ant beta:skills list

# Liste nur benutzerdefinierte Skills auf
ant beta:skills list --source custom

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

Einen Skill abrufen

Rufe Details zu einem bestimmten Skill ab:

ant beta:skills retrieve \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv

Einen Skill löschen

Um einen Skill zu löschen, musst du zuerst alle seine Versionen löschen:

# Schritt 1: Liste die Versionen auf und lösche dann jede einzelne
ant beta:skills:versions list \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --transform version --raw-output

# Wiederhole dies für jede Versions-ID, die die Liste zurückgegeben hat
ant beta:skills:versions delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --version 20260115.120000 >/dev/null

# Schritt 2: Lösche den Skill
ant beta:skills delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null

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:

Anthropic-Skills:

Versionen verwenden das Datumsformat: 20251013
Neue Versionen werden veröffentlicht, wenn Updates vorgenommen werden
Gib exakte Versionen für Stabilität an

Benutzerdefinierte Skills:

Automatisch generierte Epoch-Zeitstempel: 1759178010641129
Verwende "latest", um immer die neueste Version zu erhalten
Erstelle neue Versionen, wenn du Skill-Dateien aktualisierst

# Erstelle eine neue Version
VERSION_NUMBER=$(ant beta:skills:versions create \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv \
  --file updated_skill/SKILL.md \
  --transform version --raw-output)

# Verwende eine bestimmte Version
ant beta:messages create \
  --beta code-execution-2025-08-25 \
  --beta skills-2025-10-02 <<YAML
model: claude-opus-4-8
max_tokens: 4096
container:
  skills:
    - type: custom
      skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
      version: $VERSION_NUMBER
messages:
  - role: user
    content: Use updated Skill
tools:
  - type: code_execution_20250825
    name: code_execution
YAML

# Verwende die neueste Version
ant beta:messages create \
  --beta code-execution-2025-08-25 \
  --beta skills-2025-10-02 <<'YAML'
model: claude-opus-4-8
max_tokens: 4096
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
YAML

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

Wie Skills geladen werden

Wenn du Skills in einem Container angibst:

Metadaten-Erkennung: Claude sieht Metadaten für jeden Skill (Name, Beschreibung) im System-Prompt
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 deine Anfrage relevant sind
Komposition: Mehrere Skills lassen sich für komplexe Workflows kombinieren

Die „progressive disclosure"-Architektur (schrittweise Offenlegung) sorgt für effiziente Kontextnutzung: Claude lädt vollständige Skill-Anweisungen nur bei Bedarf.

Anwendungsfälle

Organisationsweite Skills

Marke & Kommunikation

Unternehmensspezifische Formatierung (Farben, Schriftarten, Layouts) auf Dokumente anwenden
Kommunikation nach organisatorischen Vorlagen generieren
Konsistente Markenrichtlinien über alle Ausgaben hinweg sicherstellen

Projektmanagement

Notizen mit unternehmensspezifischen Formaten strukturieren (OKRs, Entscheidungsprotokolle)
Aufgaben nach Teamkonventionen generieren
Standardisierte Meeting-Zusammenfassungen und Status-Updates erstellen

Geschäftsbetrieb

Unternehmensstandard-Berichte, -Angebote und -Analysen erstellen
Unternehmensspezifische Analyseverfahren ausführen
Finanzmodelle nach organisatorischen Vorlagen generieren

Persönliche Skills

Content-Erstellung

Benutzerdefinierte Dokumentvorlagen
Spezialisierte Formatierung und Gestaltung
Domänenspezifische Content-Generierung

Datenanalyse

Benutzerdefinierte Datenverarbeitungs-Pipelines
Spezialisierte Visualisierungsvorlagen
Branchenspezifische Analysemethoden

Entwicklung & Automatisierung

Code-Generierungsvorlagen
Test-Frameworks
Deployment-Workflows

Beispiel: Finanzmodellierung

Kombiniere Excel- und benutzerdefinierte DCF-Analyse-Skills:

# Erstelle benutzerdefinierten DCF-Analyse-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"),
)

# Verwende mit Excel, um ein Finanzmodell zu erstellen
response = client.beta.messages.create(
    model="claude-opus-4-8",
    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"}],
)
print(response)

Limits und Einschränkungen

Request-Limits

Maximale Skills pro Request: 8
Maximale Skill-Upload-Größe: 30 MB (alle Dateien zusammen)
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

Umgebungseinschränkungen

Skills laufen im Code-Execution-Container mit diesen Einschränkungen:

Kein Netzwerkzugriff: Keine externen API-Aufrufe möglich
Keine Paketinstallation zur Laufzeit: Nur vorinstallierte Pakete verfügbar
Isolierte Umgebung: Container sind isoliert; ein neuer Container wird erstellt, sofern du keine bestehende Container-ID angibst

Siehe Code-Execution-Tool für verfügbare Pakete.

Best Practices

Wann mehrere Skills verwendet werden sollten

Kombiniere Skills, wenn Aufgaben mehrere Dokumenttypen oder Domänen umfassen:

Gute Anwendungsfälle:

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

Vermeide:

Einbinden ungenutzter Skills (beeinträchtigt die Performance)

Strategie zur Versionsverwaltung

Für Produktion:

# Fixiere auf bestimmte Versionen für Stabilität
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "1759178010641129",  # Specific version
        }
    ]
}

Für Entwicklung:

# Verwende latest für die aktive Entwicklung
container = {
    "skills": [
        {
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "latest",  # Always get newest
        }
    ]
}

Überlegungen zum Prompt-Caching

Beachte bei der Verwendung von Prompt-Caching, dass eine Änderung der Skills-Liste in deinem Container den Cache ungültig macht:

# Erste Anfrage erstellt den Cache
response1 = client.beta.messages.create(
    model="claude-opus-4-8",
    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"}],
)

# Hinzufügen/Entfernen von Skills macht den Cache ungültig
response2 = client.beta.messages.create(
    model="claude-opus-4-8",
    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"}],
)

Für optimale Caching-Performance halte deine Skills-Liste über Requests hinweg konsistent.

Fehlerbehandlung

Behandle Skill-bezogene Fehler elegant:

client = anthropic.Anthropic()

try:
    response = client.beta.messages.create(
        model="claude-opus-4-8",
        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}")
        # Behandle Skill-spezifische Fehler
    else:
        raise

Datenaufbewahrung

Agent Skills sind nicht durch ZDR-Vereinbarungen abgedeckt. Skill-Definitionen und Ausführungsdaten werden gemäß der Standard-Datenaufbewahrungsrichtlinie von Anthropic aufbewahrt.

Informationen zur ZDR-Eignung für alle Funktionen findest du unter API und Datenaufbewahrung.

Nächste Schritte

API-Referenz

Vollständige API-Referenz mit allen Endpunkten

Authoring-Leitfaden

Best Practices für das Schreiben effektiver Skills

Code-Execution-Tool

Erfahre mehr über die Code-Execution-Umgebung

Was this page helpful?

Schnellzugriff

Überblick

Skills verwenden

Voraussetzungen

Skills in Messages verwenden

Container-Parameter

Generierte Dateien herunterladen

Multi-Turn-Konversationen

Lang laufende Operationen

Mehrere Skills verwenden

Benutzerdefinierte Skills verwalten

Einen Skill erstellen

Skills auflisten

Einen Skill abrufen

Einen Skill löschen

Versionierung

Wie Skills geladen werden

Anwendungsfälle

Organisationsweite Skills

Persönliche Skills

Beispiel: Finanzmodellierung

Limits und Einschränkungen

Request-Limits

Umgebungseinschränkungen

Best Practices

Wann mehrere Skills verwendet werden sollten

Strategie zur Versionsverwaltung

Überlegungen zum Prompt-Caching

Fehlerbehandlung

Datenaufbewahrung

Nächste Schritte

Schnellzugriff

Überblick

Skills verwenden

Voraussetzungen

Skills in Messages verwenden

Container-Parameter

Generierte Dateien herunterladen

Multi-Turn-Konversationen

Lang laufende Operationen

Mehrere Skills verwenden

Benutzerdefinierte Skills verwalten

Einen Skill erstellen

Skills auflisten

Einen Skill abrufen

Einen Skill löschen

Versionierung

Wie Skills geladen werden

Anwendungsfälle

Organisationsweite Skills

Persönliche Skills

Beispiel: Finanzmodellierung

Limits und Einschränkungen

Request-Limits

Umgebungseinschränkungen

Best Practices

Wann mehrere Skills verwendet werden sollten

Strategie zur Versionsverwaltung

Überlegungen zum Prompt-Caching

Fehlerbehandlung

Datenaufbewahrung

Nächste Schritte

Schnellzugriff

Überblick

Skills verwenden

Voraussetzungen

Skills in Messages verwenden

Container-Parameter

Generierte Dateien herunterladen

Multi-Turn-Konversationen

Lang laufende Operationen

Mehrere Skills verwenden

Benutzerdefinierte Skills verwalten

Einen Skill erstellen

Skills auflisten

Einen Skill abrufen

Einen Skill löschen

Versionierung

Wie Skills geladen werden

Anwendungsfälle

Organisationsweite Skills

Persönliche Skills

Beispiel: Finanzmodellierung

Limits und Einschränkungen

Request-Limits

Umgebungseinschränkungen

Best Practices

Wann mehrere Skills verwendet werden sollten

Strategie zur Versionsverwaltung

Überlegungen zum Prompt-Caching

Fehlerbehandlung

Datenaufbewahrung

Nächste Schritte

Schnellzugriff

Überblick

Skills verwenden

Voraussetzungen

Skills in Messages verwenden

Container-Parameter

Generierte Dateien herunterladen

Multi-Turn-Konversationen

Lang laufende Operationen

Mehrere Skills verwenden

Benutzerdefinierte Skills verwalten

Einen Skill erstellen

Skills auflisten

Einen Skill abrufen

Einen Skill löschen

Versionierung

Wie Skills geladen werden

Anwendungsfälle

Organisationsweite Skills

Persönliche Skills

Beispiel: Finanzmodellierung

Limits und Einschränkungen

Request-Limits

Umgebungseinschränkungen

Best Practices

Wann mehrere Skills verwendet werden sollten

Strategie zur Versionsverwaltung

Überlegungen zum Prompt-Caching

Fehlerbehandlung

Datenaufbewahrung

Nächste Schritte