Agent Skills mit der API verwenden

Agent Skills erweitern Claudes Fähigkeiten 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.



Schnellzugriff



Überblick

Skills integrieren sich über das Code-Execution-Tool in die Messages API. Ob du vorgefertigte, von Anthropic verwaltete Skills oder selbst hochgeladene benutzerdefinierte Skills verwendest – die Integrationsform ist 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-Ausführungsumgebung ausgeführt.

Du kannst Skills aus zwei Quellen verwenden:

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:

1. Claude API-Key aus der Claude Console
2. Code-Execution-Tool in deinen Requests aktiviert

Skills sind in der Claude API allgemein verfügbar und erfordern keinen anthropic-beta-Header, weder für die Skills API noch für container.skills in Messages-Requests. Die Beispiele in dieser Anleitung senden dennoch den Beta-Header skills-2025-10-02 (plus code-execution-2025-08-25 in Messages-Requests) und verwenden den beta-Namespace der SDKs. Beide Header bleiben gültige Opt-ins, sodass die Beispiele wie geschrieben funktionieren, und du kannst sie in deinen eigenen Requests weglassen.

Skills erfordern das Code-Execution-Tool, verwende daher ein Modell aus dessen Modellkompatibilitätsliste.



Skills in Messages verwenden



Container-Parameter

Skills werden über den container-Parameter in der Messages API angegeben. Du kannst bis zu 20 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-5",
    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:

1. Skills erstellen Dateien während der Code-Ausführung.
2. Die Response enthält eine file_id für jede erstellte Datei, innerhalb von Code-Execution-Tool-Result-Blöcken (siehe Response-Format).
3. Verwende die Files API, um den eigentlichen Dateiinhalt herunterzuladen.
4. Speichere lokal oder verarbeite nach Bedarf.

Um Eingabedateien bereitzustellen, mit denen Skills arbeiten sollen, lade sie mit der Files API hoch und referenziere sie in deinem Request mit einem Container-Upload-Block.

Beispiel: Erstellen und Herunterladen einer Excel-Datei

client = anthropic.Anthropic()

# Schritt 1: Verwende einen Skill, um eine Datei zu erstellen
response = client.beta.messages.create(
    model="claude-opus-5",
    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":
                # jedes Content-Element ist ein bash_code_execution_output-Block mit einer file_id
                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_011CNha8iCJcU1wXNR6q4V8w"
# 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
for file in client.beta.files.list():
    print(f"{file.filename} - {file.created_at}")

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



Multi-Turn-Konversationen

Das container-Objekt der Response enthält die id des Containers und den expires_at-Zeitstempel (siehe Container-Wiederverwendung für Details zur Lebensdauer). Verwende denselben Container über mehrere Nachrichten hinweg wieder, indem du die Container-ID angibst:

client = anthropic.Anthropic()

# Erste Anfrage erstellt den Container
response1 = client.beta.messages.create(
    model="claude-opus-5",
    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 a sample sales dataset and analyze it"}
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Setze die Konversation mit demselben Container fort
messages = [
    {"role": "user", "content": "Create a sample sales dataset and analyze it"},
    {
        # Übernimm den Text des Assistenten; container.id überträgt den Ausführungszustand
        "role": "assistant",
        "content": "\n".join(
            block.text for block in response1.content if block.type == "text"
        ),
    },
    {"role": "user", "content": "What was the total revenue?"},
]

response2 = client.beta.messages.create(
    model="claude-opus-5",
    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:

client = anthropic.Anthropic()

messages = [{"role": "user", "content": "Generate and process a large sample dataset"}]
max_retries = 10

response = client.beta.messages.create(
    model="claude-opus-5",
    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 _ 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-5",
        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:

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    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, plus alle unterstützenden Skripte oder Ressourcen. Siehe Erste Schritte mit Agent Skills in der API, um eines zu erstellen, und die Anforderungen-Liste 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 außerdem einen files_from_dir-Helper, der einen Verzeichnispfad akzeptiert.

Dateien werden anhand des Dateinamens identifiziert, den du anhängst (das ;filename=-Suffix im cURL-Beispiel und die Dateinamen-Argumente in den SDK-Beispielen). Für den Skill aus dem Walkthrough erstelle ein Zip mit zip -r financial_skill.zip financial_skill/ und ersetze damit den Platzhalter example_skill.zip in den Zip-Upload-Optionen.

zip -r financial_skill.zip financial_skill/
ant beta:skills create \
  --file financial_skill.zip \
  --beta skills-2025-10-02

---
name: financial-skill
description: Docs example skill.
---

print("financial analysis helper")

Anforderungen:

• Muss eine SKILL.md-Datei im Upload-Root enthalten (oder auf oberster Ebene eines einzelnen umschließenden Ordners)
• display_name ist optional: Wenn weggelassen, wird er vom name in SKILL.md abgeleitet; ein expliziter Wert darf bis zu 255 Zeichen lang sein und muss innerhalb des Workspace nicht eindeutig sein
• Die gesamte Upload-Größe muss unter 30 MB liegen (unkomprimiert)
• Anforderungen an das YAML-Frontmatter:
  • 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-Schemas findest du in der Create Skill API-Referenz.



Skills auflisten

Rufe alle Skills ab, die für deinen 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

Das Löschen eines Skills entfernt auch alle seine Versionen. Diese Kaskadierung ist ein reines GA-Verhalten, daher rufen diese Beispiele – anders als die anderen Beispiele in dieser Anleitung – direkt die GA-Oberfläche statt des beta-Namespace auf.

ant skills delete \
  --skill-id skill_01AbCdEfGhIjKlMnOpQrStUv >/dev/null



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 Versions-IDs: skver_01AbCdEfGhIjKlMnOpQrStUv
• Verwende "latest", um immer die neueste Version zu erhalten
• Erstelle neue Versionen, wenn du Skill-Dateien aktualisierst

Eine neue Version ist ein vollständiger Snapshot, kein Delta: Lade jedes Mal den vollständigen Dateisatz des Skills hoch. Dateien, die du weglässt, werden nicht übernommen, und der name in der SKILL.md der neuen Version muss mit dem bestehenden Namen des Skills übereinstimmen. Die folgenden Beispiele laden das vollständige financial_skill/-Bundle aus Einen Skill erstellen erneut hoch.

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

# Verwende eine bestimmte Version
ant beta:messages create \
  --beta code-execution-2025-08-25,skills-2025-10-02 <<YAML
model: claude-opus-5
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,skills-2025-10-02 <<YAML
model: claude-opus-5
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:

1. Metadaten-Erkennung: Claude sieht Metadaten für jeden Skill (Name, Beschreibung) im System-Prompt.
2. Datei-Laden: Skill-Dateien werden in den Container unter /skills/{skill-name}/ kopiert. Das Verzeichnis ist der Name des Skills (pptx für einen Anthropic-Skill, der name aus SKILL.md für einen benutzerdefinierten Skill), nicht seine skill_01...-ID.
3. Automatische Verwendung: Claude lädt und verwendet Skills automatisch, wenn sie für deine Anfrage relevant sind.
4. Komposition: Mehrere Skills lassen sich für komplexe Workflows kombinieren.

Claude lädt vollständige Skill-Anweisungen nur bei Bedarf.



Anwendungsfälle

Skills eignen sich sowohl für organisatorische als auch für persönliche Arbeit. Organisationen verwenden sie, um Markenformatierung auf Dokumente anzuwenden, Notizen und Berichte anhand von Unternehmensvorlagen zu strukturieren und unternehmensspezifische Analyseverfahren auszuführen. Einzelpersonen verwenden sie für benutzerdefinierte Dokumentvorlagen, spezialisierte Daten-Pipelines sowie Konventionen für Code-Generierung oder Deployment.



Beispiel: Finanzmodellierung

Kombiniere Excel- und benutzerdefinierte DCF-Analyse-Skills:

from anthropic.lib import files_from_dir

client = anthropic.Anthropic()

# Erstelle einen benutzerdefinierten DCF-Analyse-Skill

dcf_skill = client.beta.skills.create(
    files=files_from_dir("/path/to/dcf_skill"),
)

# Verwende mit Excel, um ein Finanzmodell zu erstellen
response = client.beta.messages.create(
    model="claude-opus-5",
    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",
        }
    ],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
print(response)



Limits und Einschränkungen



Request-Limits

• Maximale Skills pro Request: 20
• Maximale Skill-Upload-Größe: 30 MB (alle Dateien zusammen, unkomprimiert)
• Anforderungen an das YAML-Frontmatter:
  • 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 werden im Code-Execution-Container mit folgenden Einschränkungen ausgeführt:

• Kein Netzwerkzugriff: Externe API-Aufrufe sind nicht möglich
• Keine Paketinstallation zur Laufzeit: Nur vorinstallierte Pakete verfügbar
• Isolierte Umgebung: 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 für die Versionsverwaltung

Die SDK-Tabs in diesem Abschnitt zeigen den container-Wert, der in einen Messages-Request aufgenommen werden soll. Die cURL- und CLI-Tabs zeigen den vollständigen Request.

Für die Produktion: Pinne eine bestimmte Version, damit Skill-Updates dein deploytes Verhalten niemals ändern. Wenn du version weglässt oder auf "latest" setzt, verwenden Requests die neueste Version des Skills, sodass eine von irgendjemandem im Workspace hochgeladene Version sofort ändert, was deine Produktions-Agents ausführen. Die Versions-ID stammt aus der Create-Version-Response in Versionierung oder aus der List Skill Versions API. Die ID ist immer ein String: Setze Epoch-Zeitstempel-IDs in JSON oder YAML in Anführungszeichen.

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

Für die Entwicklung: Verwende latest, um beim Iterieren automatisch die neueste Version zu erhalten.

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



Überlegungen zum Prompt-Caching

Wenn du Prompt-Caching verwendest, führt eine Änderung der Skills-Liste in deinem Container zu einem Cache-Miss. Skills werden in einer festen Reihenfolge in den System-Prompt gerendert, sodass dieselbe Liste dasselbe cachebare Präfix erzeugt:

client = anthropic.Anthropic()

# Skills werden in einer festen, Cache-freundlichen Reihenfolge in den System-Prompt gerendert
response1 = client.beta.messages.create(
    model="claude-opus-5",
    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 sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Das Ändern der Skills-Liste ([xlsx] vs. [xlsx, pptx]) ändert das Präfix: ein Cache-Miss, während eine identische Liste ein Cache-Hit ist
response2 = client.beta.messages.create(
    model="claude-opus-5",
    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",
            },  # prefix change: cache miss
        ]
    },
    messages=[{"role": "user", "content": "Create a presentation"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

Für die beste Caching-Performance halte deine Skills-Liste, einschließlich ihrer Reihenfolge, über Requests hinweg konsistent. Das Pinnen von Versionen benutzerdefinierter Skills hilft ebenfalls: Mit "latest" kann das Veröffentlichen einer neuen Version das gecachte Präfix ungültig machen, wenn sich dadurch die Beschreibung des Skills ändert.



Fehlerbehandlung

Behandle Skill-bezogene Fehler elegant:

client = anthropic.Anthropic()

try:
    response = client.beta.messages.create(
        model="claude-opus-5",
        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äß Anthropics Standard-Datenaufbewahrungsrichtlinie aufbewahrt.

Zur ZDR-Eignung aller Features siehe API und Datenaufbewahrung.



Audit-Logging

Wenn deine Organisation die Compliance API aktiviert hat, zeichnet deren Activity Feed das Erstellen und Löschen von Skills und Skill-Versionen auf, die mit einem Claude API-Key oder über die Claude Console vorgenommen wurden. Operationen, die stattfinden, während die Compliance API deaktiviert ist, werden nicht aufgezeichnet und können später nicht wiederhergestellt werden. Richte die Compliance API daher ein, bevor du dich auf diesen Audit-Trail verlässt.



Nächste Schritte