Claude Platform Docs
MessagesSkills

Agent Skills mit der API verwenden

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

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

Erfahre, wie du mit Agent Skills in weniger als 10 Minuten Dokumente mit der Claude API erstellst.

Erfahre, wie du effektive Skills schreibst, die Claude finden und erfolgreich verwenden kann.

Überblick

Skills werden über das „code execution tool“ (Code-Ausführungstool) in die Messages API integriert. Ob du vorgefertigte, von Anthropic verwaltete Skills oder selbst hochgeladene benutzerdefinierte Skills verwendest, die Integration ist identisch: Beide erfordern Code-Ausführung und verwenden dieselbe container-Struktur.

Skills verwenden

Skills werden in der Messages API unabhängig von ihrer Quelle identisch integriert. Du gibst Skills im Parameter container mit einer skill_id, einem type und einer optionalen version an, und sie werden in der Code-Ausführungsumgebung ausgeführt.

Du kannst Skills aus zwei Quellen verwenden:

AspektAnthropic SkillsBenutzerdefinierte Skills
Type-Wertanthropiccustom
Skill-IDsKurznamen: pptx, xlsx, docx, pdfGeneriert: skill_01AbCdEfGhIjKlMnOpQrStUv
VersionsformatDatumsbasiert: 20251013 oder latestVersions-ID: skver_01AbCdEfGhIjKlMnOpQrStUv oder latest
VerwaltungVorgefertigt und gepflegt von AnthropicHochladen und Verwalten über die Skills APIVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren.
VerfügbarkeitFür alle Nutzer verfügbarPrivat für deinen Workspace

Beide Skill-Quellen werden vom List-Skills-EndpunktVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren. zurückgegeben (verwende den Parameter source zum Filtern). Die Integration 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-Ausführungstool in deinen Anfragen aktiviert

Skills erfordern das Code-Ausführungstool, verwende also ein Modell, das in dessen Abschnitt zur API-Unterstützung aufgeführt ist.


Skills in Messages verwenden

Container-Parameter

Skills werden über den Parameter container in der Messages API angegeben. Du kannst bis zu 20 Skills pro Anfrage einbinden.

Die Struktur ist für Anthropic Skills 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.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    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 in der Antwort file_id-Attribute zurück. Du musst die Files API verwenden, um diese Dateien herunterzuladen.

So funktioniert es:

  1. Skills erstellen während der Code-Ausführung Dateien.
  2. Die Antwort enthält für jede erstellte Datei eine file_id innerhalb der Ergebnisblöcke des Code-Ausführungstools (siehe Antwortformat).
  3. Verwende die Files API, um den eigentlichen Dateiinhalt herunterzuladen.
  4. Speichere die Dateien lokal oder verarbeite sie nach Bedarf.

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

Beispiel: Eine Excel-Datei erstellen und herunterladen

client = anthropic.Anthropic()

# Schritt 1: Verwende einen Skill, um eine Datei zu erstellen
response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    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 die 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 Inhaltselement 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.files.retrieve_metadata(file_id=file_id)
    file_content = client.files.download(file_id=file_id)

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

Weitere Operationen der Files API:

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

# Alle Dateien auflisten
for file in client.files.list():
    print(f"{file.filename} - {file.created_at}")

# Eine Datei löschen
client.files.delete(file_id=file_id)

Multi-Turn-Konversationen

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

client = anthropic.Anthropic()

# Die erste Anfrage erstellt den Container
response1 = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    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 enthält 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.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    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 Stop-Reasons vom Typ pause_turn:

client = anthropic.Anthropic()

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

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    container={
        "skills": [
            {
                "type": "custom",
                "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                "version": "latest",
            }
        ]
    },
    messages=messages,
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Behandle pause_turn bei langen Vorgängen
for _ in range(max_retries):
    if response.stop_reason != "pause_turn":
        break

    messages.append({"role": "assistant", "content": response.content})
    response = client.messages.create(
        model="claude-opus-5-5",
        max_tokens=4096,
        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 einer einzigen Anfrage, um komplexe Workflows abzubilden:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    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 YAML-Frontmatter name und description sowie beliebige unterstützende Skripte oder Ressourcen enthält. Unter Best Practices für das Erstellen von Skills erfährst du, wie du einen erstellst, und die Liste Anforderungen nach den Beispielen enthält alle 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 Helfer files_from_dir, der einen Verzeichnispfad akzeptiert, und ant apply in der CLI lädt das Verzeichnis selbst hoch.

Dateien werden über den Dateinamen identifiziert, den du anhängst (das Suffix ;filename= im cURL-Beispiel und die Dateinamen-Argumente in den SDK-Beispielen). Für den Skill aus der Anleitung erstellst du ein Zip mit zip -r financial_skill.zip financial_skill/ und ersetzt damit den Platzhalter example_skill.zip in den Zip-Upload-Optionen.

ant apply financial_skill
financial_skill/SKILL.md
---
name: financial-skill
description: Docs example skill.
---
financial_skill/analyze.py
print("financial analysis helper")

Anforderungen:

  • Muss eine SKILL.md-Datei im Stammverzeichnis des Uploads (oder auf oberster Ebene eines einzelnen umschließenden Ordners) enthalten
  • display_name ist optional: Wenn es weggelassen wird, wird es aus dem name der 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 (unkomprimiert) liegen
  • Anforderungen an das YAML-Frontmatter:
    • name: Maximal 64 Zeichen, nur Kleinbuchstaben/Ziffern/Bindestriche, keine XML-Tags, keine reservierten Wörter (anthropic, claude)
    • description: Maximal 1.024 Zeichen, nicht leer, keine XML-Tags

Vollständige Anfrage-/Antwort-Schemas findest du in der API-Referenz Skill erstellenVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren..

Skills auflisten

Rufe alle für deinen Workspace verfügbaren Skills ab, einschließlich der vorgefertigten Anthropic Skills und deiner benutzerdefinierten Skills. Verwende den Parameter source, um nach Skill-Typ zu filtern:

client = anthropic.Anthropic()

# Alle Skills auflisten
for skill in client.skills.list():
    print(f"{skill.id}: {skill.display_name} (source: {skill.source.type})")

# Nur benutzerdefinierte Skills auflisten
custom_skills = client.skills.list(source="custom")

Optionen für Paginierung und Filterung findest du in der List-Skills-API-ReferenzVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren..

Einen Skill abrufen

Rufe Details zu einem bestimmten Skill ab:

client = anthropic.Anthropic()

skill = client.skills.retrieve(skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv")

print(f"Skill: {skill.display_name}")
print(f"Latest version: {skill.latest_version_id}")
print(f"Created: {skill.created_at}")

Einen Skill löschen

Beim Löschen eines Skills werden auch alle seine Versionen gelöscht.

client = anthropic.Anthropic()

client.skills.delete(skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv")

Versionierung

Skills unterstützen „versioning“ (Versionierung), um Updates sicher zu verwalten:

Anthropic Skills:

  • Versionen verwenden das Datumsformat: 20251013
  • Neue Versionen werden veröffentlicht, sobald Updates erfolgen
  • Gib exakte Versionen an, um Stabilität zu gewährleisten

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.

from anthropic.lib import files_from_dir

client = anthropic.Anthropic()

# Erstelle eine neue Version

new_version = client.skills.versions.create(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    files=files_from_dir("financial_skill"),
)

# Verwende eine bestimmte Version
response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    container={
        "skills": [
            {
                "type": "custom",
                "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
                "version": new_version.id,
            }
        ]
    },
    messages=[{"role": "user", "content": "Use updated Skill"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Verwende die neueste Version
response = client.messages.create(
    model="claude-opus-5-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"}],
)

Alle Details findest du in der Create-Skill-Version-API-ReferenzVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren..


Wie Skills geladen werden

Wenn du Skills in einem Container angibst:

  1. Erkennung von Metadaten: Claude erhält im System-Prompt Metadaten zu jedem Skill (Name, Beschreibung).
  2. Laden der Dateien: Skill-Dateien werden in den Container unter /skills/{skill-name}/ kopiert. Das Verzeichnis entspricht dem Namen des Skills (pptx bei einem Anthropic Skill, der name aus der SKILL.md bei einem benutzerdefinierten Skill), nicht seiner 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 die vollständigen Skill-Anweisungen nur bei Bedarf.


Anwendungsfälle

Skills eignen sich sowohl für organisatorische als auch für persönliche Arbeit. Organisationen nutzen sie, um Dokumente mit Markenformatierung zu versehen, Notizen und Berichte anhand von Unternehmensvorlagen zu strukturieren und unternehmensspezifische Analyseverfahren auszuführen. Einzelpersonen nutzen sie für eigene Dokumentvorlagen, spezialisierte Datenpipelines sowie Konventionen für Codegenerierung oder Deployment.

Beispiel: Finanzmodellierung

Kombiniere den Excel-Skill mit einem benutzerdefinierten Skill für DCF-Analysen. Erstelle zuerst den benutzerdefinierten DCF-Analyse-Skill:

ant apply dcf_skill

Verwende ihn dann zusammen mit dem Excel-Skill, um ein Finanzmodell zu erstellen. Übergib die ID des von dir erstellten Skills als skill_id des benutzerdefinierten Skills:

client = anthropic.Anthropic()

# Benutzerdefinierter DCF-Analyse-Skill (ID aus der Create-Antwort der Skills API)
dcf_skill_id = "skill_01AbCdEfGhIjKlMnOpQrStUv"

# Mit Excel verwenden, um ein Finanzmodell zu erstellen
response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    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 Anzahl an Skills pro Anfrage: 20
  • Maximale Upload-Größe eines Skills: 30 MB (alle Dateien zusammen, unkomprimiert)
  • Anforderungen an das YAML-Frontmatter:
    • name: Maximal 64 Zeichen, nur Kleinbuchstaben/Ziffern/Bindestriche, keine XML-Tags, keine reservierten Wörter (anthropic, claude)
    • description: Maximal 1.024 Zeichen, nicht leer, keine XML-Tags

Einschränkungen der Umgebung

Skills laufen im Code-Ausführungscontainer mit diesen Einschränkungen:

  • Kein Netzwerkzugriff: Es können keine externen API-Aufrufe erfolgen
  • Keine Paketinstallation zur Laufzeit: Nur vorinstallierte Pakete sind verfügbar
  • Isolierte Umgebung: Es wird ein neuer Container erstellt, sofern du keine bestehende Container-ID angibst

Verfügbare Pakete findest du unter Code-Ausführungstool.


Best Practices

Wann du mehrere Skills verwenden solltest

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

Gute Anwendungsfälle:

  • Datenanalyse (Excel) + Erstellung von Präsentationen (PowerPoint)
  • Berichterstellung (Word) + Export nach PDF
  • Benutzerdefinierte Domänenlogik + Dokumentgenerierung

Vermeide:

  • Das Einbinden ungenutzter Skills (beeinträchtigt die Performance)

Strategie für die Versionsverwaltung

Die SDK-Tabs in diesem Abschnitt zeigen den container-Wert, den du in eine Messages-Anfrage einfügst. Die cURL- und CLI-Tabs zeigen die vollständige Anfrage.

Für die Produktion: Lege eine bestimmte Version fest, damit Skill-Updates niemals dein bereitgestelltes Verhalten ändern. Wenn du version weglässt oder auf "latest" setzt, verwenden Anfragen 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 Antwort beim Erstellen einer Version unter Versionierung oder aus der List-Skill-Versions-APIVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren.. Die ID ist immer ein String, setze sie in JSON oder YAML also in Anführungszeichen, auch wenn sie numerisch aussieht.

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

Für die Entwicklung: Verwende latest, um während der Iteration automatisch die neueste Version zu übernehmen.

# 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“ (Prompt-Caching) verwendest, bricht eine Änderung der Skills-Liste in deinem Container den Cache. 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.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    container={
        "skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
    },
    messages=[{"role": "user", "content": "Analyze sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

# Eine geänderte Skills-Liste ([xlsx] statt [xlsx, pptx]) ändert das Präfix: Cache-Miss; eine identische Liste ist ein Cache-Hit
response2 = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    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 solltest du deine Skills-Liste einschließlich ihrer Reihenfolge über alle Anfragen hinweg konsistent halten. Auch das Festlegen von Versionen benutzerdefinierter Skills hilft: 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 kontrolliert:

client = anthropic.Anthropic()

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

Migration von skills-2025-10-02

Die Skills API ist nicht mehr in der Beta und benötigt keinen Beta-Header. Die Migration weg von skills-2025-10-02 ist optional: Anfragen, die ihn senden, funktionieren weiter und geben weiterhin die Beta-Antwortformen zurück, sodass eine bestehende Integration weiter funktioniert, bis du sie änderst. Das Entfernen des Headers stellt diese Anfragen auf die auf dieser Seite dokumentierten Formen um:

Mit skills-2025-10-02Ohne den Header
Skill-Bezeichnungdisplay_title (bis zu 64 Zeichen, eindeutig pro Workspace)display_name (bis zu 255 Zeichen, nicht eindeutig); wird aus dem name der SKILL.md abgeleitet, wenn weggelassen
Zeiger auf die neueste Versionlatest_version, ein Epoch-Mikrosekunden-String wie "1759178010641129"latest_version_id, eine Versions-ID wie "skver_01AbCdEfGhIjKlMnOpQrStUv"; GET /v1/skills/{skill_id}/versions/latest löst sie in einem Aufruf auf
Versionskennung in URLsEpoch-Mikrosekunden-StringVersions-ID (skver_...). Unter der Beta erfasste IDs mit dem Präfix skill_version_ werden als Eingabe akzeptiert.
VersionsobjektEnthält directory (immer gleich dem Skill-name)Kein directory-Feld
sourceEin String, "custom" oder "anthropic"Ein Objekt, zum Beispiel {"type": "custom"}; der Wert für den Beispielkatalog ist "anthropic_example"
List-Responses{ data, has_more, next_page }{ data, next_page }; limit von 1 bis 1.000 (Standard 20)
Reihenfolge der VersionslisteÄlteste zuerstNeueste zuerst, Standard-limit 20. Seiten-Cursor der einen Form sind für die andere nicht gültig.
Löschen eines SkillsGibt einen 400-Fehler zurück, solange eine Version existiertLöscht den Skill und alle seine Versionen
Löschen der einzigen Version eines SkillsErlaubt, hinterlässt einen Skill ohne VersionenGibt einen 400-Fehler zurück; lade zuerst eine Ersatzversion hoch oder lösche den Skill
Upload-LayoutDateien müssen in einem Verzeichnis auf oberster Ebene liegen, dessen Name mit dem Skill-name übereinstimmtSKILL.md darf im Root des Uploads liegen; die gespeicherten Pfade sind in beiden Fällen gleich
Response-TypenCreateSkillResponse, GetSkillResponse und ein Typ pro OperationSkill, SkillVersion, DeletedSkill, DeletedSkillVersion

So migrierst du:

  1. Entferne den Beta-Header. Entferne anthropic-beta: skills-2025-10-02 aus deinen Anfragen. Rufe mit dem SDK client.skills statt client.beta.skills auf; das Beibehalten von client.beta.skills funktioniert nur mit den SDK-Releases, die den Header nicht mehr senden. Frühere Releases senden ihn von client.beta.skills aus, selbst wenn du keine Beta-Namen übergibst.
  2. Benenne Felder um in deinem Code: display_title in display_name und latest_version in latest_version_id. Lies source.type, anstatt source mit einem String zu vergleichen.
  3. Verwende Versions-IDs. Überall, wo du eine Epoch-Mikrosekunden-Version gespeichert hast, speichere stattdessen die id der Version oder verwende latest. Skill-Referenzen in Messages-Requests akzeptieren eine Versions-ID, latest oder (für Anthropic Skills) die Katalogversion.
  4. Überprüfe Löschaufrufe. DELETE /v1/skills/{skill_id} löscht jetzt jede Version zusammen mit dem Skill. Wenn du dich auf die Ablehnung durch die Beta als Schutzmaßnahme verlassen hast, füge deine eigene Prüfung hinzu.

Ein Skill, dessen Versionen unter der Beta alle gelöscht wurden, hat keine aktuelle Version, die zurückgegeben werden könnte: GET /v1/skills/{skill_id} gibt einen 400-Fehler zurück, und der Skill wird in List-Responses ausgelassen, bis du eine Version dafür hochlädst. Du kannst ihn weiterhin löschen.

SDK-Beta-Namespace

Ab Python SDK 1.2.0, TypeScript SDK 0.122.0, Go SDK 1.68.0, Java SDK 2.59.0, PHP SDK 0.45.0, Ruby SDK 1.67.0 und C# SDK 12.44.0 sendet client.beta.skills kein skills-2025-10-02 mehr und gibt dieselben Formen zurück wie client.skills, mit Beta-Typnamen (BetaSkill, BetaSkillVersion, BetaDeletedSkill, BetaDeletedSkillVersion). Es nimmt Beta-Namen über betas für Skills-Funktionen entgegen, die sich in der Beta befinden. In den Beta-Messages-Typen wird der Typ für die Container-Skill-Referenz von BetaSkill in BetaContainerSkill umbenannt (gleiche Felder: type, skill_id, version); BetaSkill bezeichnet jetzt die Skill-Ressource, entsprechend Skill und ContainerSkill in den Nicht-Beta-Typen. Frühere SDK-Releases sind auf die Beta-Formen typisiert; wenn du von diesen Typen abhängst, bleibe bei einem früheren Release, bis du migrierst.

Datenaufbewahrung

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

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

Audit-Protokollierung

Wenn in deiner Organisation die Compliance API aktiviert ist, 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 werden. Vorgänge, die stattfinden, während die Compliance API deaktiviert ist, werden nicht aufgezeichnet und können später nicht wiederhergestellt werden. Richte daher die Compliance API ein, bevor du dich auf diesen „audit trail“ (Prüfpfad) verlässt.

Nächste Schritte

Vollständige API-Referenz mit allen Endpunkten

Erfahre, wie du effektive Skills schreibst, die Claude entdecken und erfolgreich nutzen kann.

Führe Python- und Bash-Code in einem Sandbox-Container aus, um Daten zu analysieren, Dateien zu generieren und Lösungen iterativ zu verbessern.

War diese Seite hilfreich?