Agent Skills erweitern Claudes Fähigkeiten durch organisierte Ordner mit Anweisungen, Skripten und Ressourcen. Diese Anleitung zeigt Ihnen, wie Sie sowohl vorgefertigte als auch benutzerdefinierte Skills mit der Claude API verwenden.
Für die vollständige API-Referenz einschließlich Request/Response-Schemas und aller Parameter siehe:

Übersicht

Für einen tieferen Einblick in die Architektur und reale Anwendungen von Agent Skills lesen Sie unseren Engineering-Blog: Equipping agents for the real world with Agent Skills.
Skills integrieren sich mit der Messages API über das Code-Ausführungs-Tool. Ob Sie vorgefertigte Skills verwenden, die von Anthropic verwaltet werden, oder benutzerdefinierte Skills, die Sie hochgeladen haben, ist die Integrationsform identisch – beide erfordern Code-Ausführung und verwenden die gleiche container-Struktur.

Skills verwenden

Skills integrieren sich unabhängig von der Quelle identisch in die Messages API. Sie geben Skills im container-Parameter mit einer skill_id, einem type und einer optionalen version an, und sie werden in der Code-Ausführungsumgebung ausgeführt. Sie können Skills aus zwei Quellen verwenden:
AspektAnthropic SkillsBenutzerdefinierte Skills
Type-Wertanthropiccustom
Skill-IDsKurznamen: pptx, xlsx, docx, pdfGeneriert: skill_01AbCdEfGhIjKlMnOpQrStUv
VersionsformatDatumsbasiert: 20251013 oder latestEpoch-Zeitstempel: 1759178010641129 oder latest
VerwaltungVorgefertigt und von Anthropic gepflegtHochladen und Verwalten über Skills API
VerfügbarkeitFür alle Benutzer verfügbarPrivat für Ihren Workspace
Beide Skill-Quellen werden vom List Skills Endpoint zurückgegeben (verwenden Sie den source-Parameter zum Filtern). Die Integrationsform und die Ausführungsumgebung sind identisch – der einzige Unterschied ist, woher die Skills kommen und wie sie verwaltet werden.

Voraussetzungen

Um Skills zu verwenden, benötigen Sie:
  1. Anthropic API-Schlüssel aus der Console
  2. Beta-Header:
    • code-execution-2025-08-25 - Aktiviert Code-Ausführung (erforderlich für Skills)
    • skills-2025-10-02 - Aktiviert Skills API
    • files-api-2025-04-14 - Zum Hochladen/Herunterladen von Dateien zum/vom Container
  3. Code-Ausführungs-Tool in Ihren Anfragen aktiviert

Skills in Messages verwenden

Container-Parameter

Skills werden mit dem container-Parameter in der Messages API angegeben. Sie können bis zu 8 Skills pro Anfrage einschließen. Die Struktur ist für sowohl Anthropic als auch benutzerdefinierte Skills identisch – geben Sie den erforderlichen type und die skill_id an, und schließen Sie optional version ein, um an eine bestimmte Version gebunden zu sein:
import anthropic

client = anthropic.Anthropic()

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

Heruntergeladene generierte Dateien

Wenn Skills Dokumente erstellen (Excel, PowerPoint, PDF, Word), geben sie file_id-Attribute in der Antwort zurück. Sie müssen die Files API verwenden, um diese Dateien herunterzuladen. Wie es funktioniert:
  1. Skills erstellen Dateien während der Code-Ausführung
  2. Die Antwort enthält file_id für jede erstellte Datei
  3. Verwenden Sie die Files API, um den tatsächlichen Dateiinhalt herunterzuladen
  4. Speichern Sie lokal oder verarbeiten Sie nach Bedarf
Beispiel: Erstellen und Herunterladen einer Excel-Datei
import anthropic

client = anthropic.Anthropic()

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

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

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

    # Step 4: Save to disk
    file_content.write_to_file(file_metadata.filename)
    print(f"Downloaded: {file_metadata.filename}")
Zusätzliche Files API-Operationen:
# Get file metadata
file_info = client.beta.files.retrieve_metadata(
    file_id=file_id,
    betas=["files-api-2025-04-14"]
)
print(f"Filename: {file_info.filename}, Size: {file_info.size_bytes} bytes")

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

# Delete a file
client.beta.files.delete(
    file_id=file_id,
    betas=["files-api-2025-04-14"]
)
Für vollständige Details zur Files API siehe die Files API-Dokumentation.

Multi-Turn-Konversationen

Verwenden Sie denselben Container über mehrere Nachrichten hinweg wieder, indem Sie die Container-ID angeben:
# First request creates container
response1 = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"}
        ]
    },
    messages=[{"role": "user", "content": "Analyze this sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

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

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

Langwierige Operationen

Skills können Operationen ausführen, die mehrere Turns erfordern. Behandeln Sie pause_turn Stop-Gründe:
messages = [{"role": "user", "content": "Process this large dataset"}]
max_retries = 10

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

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

    messages.append({"role": "assistant", "content": response.content})
    response = client.messages.create(
        model="claude-sonnet-4-5-20250929",
        max_tokens=4096,
        betas=["code-execution-2025-08-25", "skills-2025-10-02"],
        container={
            "id": response.container.id,
            "skills": [
                {"type": "custom", "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv", "version": "latest"}
            ]
        },
        messages=messages,
        tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
    )
Die Antwort kann einen pause_turn Stop-Grund enthalten, der anzeigt, dass die API eine langwierige Skill-Operation unterbrochen hat. Sie können die Antwort in einer nachfolgenden Anfrage unverändert zurückgeben, um Claude seinen Turn fortsetzen zu lassen, oder Sie können den Inhalt ändern, wenn Sie das Gespräch unterbrechen und zusätzliche Anleitung geben möchten.

Mehrere Skills verwenden

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

Benutzerdefinierte Skills verwalten

Einen Skill erstellen

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

client = anthropic.Anthropic()

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

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

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

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

print(f"Created skill: {skill.id}")
print(f"Latest version: {skill.latest_version}")
Anforderungen:
  • Muss eine SKILL.md-Datei auf der obersten Ebene enthalten
  • Alle Dateien müssen ein gemeinsames Stammverzeichnis in ihren Pfaden angeben
  • Die Gesamtgröße des Uploads muss unter 8 MB liegen
  • YAML-Frontmatter: name (maximal 64 Zeichen), description (maximal 1024 Zeichen)
Für vollständige Request/Response-Schemas siehe die Create Skill API Reference.

Skills auflisten

Rufen Sie alle Skills ab, die in Ihrem Workspace verfügbar sind, einschließlich sowohl vorgefertigter Anthropic Skills als auch Ihrer benutzerdefinierten Skills. Verwenden Sie den source-Parameter zum Filtern nach Skill-Typ:
# List all Skills
skills = client.beta.skills.list(
    betas=["skills-2025-10-02"]
)

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

# List only custom Skills
custom_skills = client.beta.skills.list(
    source="custom",
    betas=["skills-2025-10-02"]
)
Siehe die List Skills API Reference für Paginierungs- und Filteroptionen.

Einen Skill abrufen

Rufen Sie Details zu einem bestimmten Skill ab:
skill = client.beta.skills.retrieve(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    betas=["skills-2025-10-02"]
)

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

Einen Skill löschen

Um einen Skill zu löschen, müssen Sie zunächst alle seine Versionen löschen:
# Step 1: Delete all versions
versions = client.beta.skills.versions.list(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    betas=["skills-2025-10-02"]
)

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

# Step 2: Delete the Skill
client.beta.skills.delete(
    skill_id="skill_01AbCdEfGhIjKlMnOpQrStUv",
    betas=["skills-2025-10-02"]
)
Der Versuch, einen Skill mit vorhandenen Versionen zu löschen, gibt einen 400-Fehler zurück.

Versionierung

Skills unterstützen Versionierung, um Updates sicher zu verwalten: Von Anthropic verwaltete Skills:
  • Versionen verwenden Datumsformat: 20251013
  • Neue Versionen werden veröffentlicht, wenn Updates vorgenommen werden
  • Geben Sie exakte Versionen für Stabilität an
Benutzerdefinierte Skills:
  • Automatisch generierte Epoch-Zeitstempel: 1759178010641129
  • Verwenden Sie "latest", um immer die neueste Version zu erhalten
  • Erstellen Sie neue Versionen beim Aktualisieren von Skill-Dateien
# Create a new version
from anthropic.lib import files_from_dir

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

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

# Use latest version
response = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02"],
    container={
        "skills": [{
            "type": "custom",
            "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
            "version": "latest"
        }]
    },
    messages=[{"role": "user", "content": "Use latest Skill version"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)
Siehe die Create Skill Version API Reference für vollständige Details.

Wie Skills geladen werden

Wenn Sie Skills in einem Container angeben:
  1. Metadaten-Erkennung: Claude sieht Metadaten für jeden Skill (Name, Beschreibung) in der System-Eingabeaufforderung
  2. Datei-Laden: Skill-Dateien werden in den Container unter /skills/{directory}/ kopiert
  3. Automatische Verwendung: Claude lädt und verwendet Skills automatisch, wenn sie für Ihre Anfrage relevant sind
  4. Komposition: Mehrere Skills kombinieren sich für komplexe Workflows
Die progressive Disclosure-Architektur gewährleistet eine effiziente Kontextnutzung – Claude lädt nur vollständige Skill-Anweisungen, wenn nötig.

Anwendungsfälle

Organisatorische Skills

Marke & Kommunikation
  • Wenden Sie unternehmensweite Formatierung (Farben, Schriftarten, Layouts) auf Dokumente an
  • Generieren Sie Kommunikationen nach organisatorischen Vorlagen
  • Stellen Sie sicher, dass Markenrichtlinien konsistent über alle Ausgaben hinweg sind
Projektmanagement
  • Strukturieren Sie Notizen mit unternehmensweiten Formaten (OKRs, Entscheidungsprotokolle)
  • Generieren Sie Aufgaben nach Team-Konventionen
  • Erstellen Sie standardisierte Meeting-Zusammenfassungen und Status-Updates
Geschäftsbetrieb
  • Erstellen Sie unternehmensstandard-Berichte, Vorschläge und Analysen
  • Führen Sie unternehmensweite analytische Verfahren aus
  • Generieren Sie Finanzmodelle nach organisatorischen Vorlagen

Persönliche Skills

Content-Erstellung
  • Benutzerdefinierte Dokumentvorlagen
  • Spezialisierte Formatierung und Styling
  • Domänenspezifische Content-Generierung
Datenanalyse
  • Benutzerdefinierte Datenverarbeitungs-Pipelines
  • Spezialisierte Visualisierungsvorlagen
  • Branchenspezifische analytische Methoden
Entwicklung & Automatisierung
  • Code-Generierungs-Vorlagen
  • Test-Frameworks
  • Deployment-Workflows

Beispiel: Finanzmodellierung

Kombinieren Sie Excel und benutzerdefinierte DCF-Analyse Skills:
# Create custom DCF analysis Skill
from anthropic.lib import files_from_dir

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

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

Grenzen und Einschränkungen

Request-Grenzen

  • Maximale Skills pro Anfrage: 8
  • Maximale Skill-Upload-Größe: 8 MB (alle Dateien kombiniert)
  • YAML-Frontmatter-Grenzen: name 64 Zeichen, description 1024 Zeichen

Umgebungseinschränkungen

Skills werden im Code-Ausführungs-Container mit diesen Einschränkungen ausgeführt:
  • Kein Netzwerkzugriff - Kann keine externen API-Aufrufe tätigen
  • Keine Runtime-Paketinstallation - Nur vorinstallierte Pakete verfügbar
  • Isolierte Umgebung - Jede Anfrage erhält einen frischen Container
Siehe die Code-Ausführungs-Tool-Dokumentation für verfügbare Pakete.

Best Practices

Wann mehrere Skills verwendet werden

Kombinieren Sie Skills, wenn Aufgaben mehrere Dokumenttypen oder Domänen betreffen: Gute Anwendungsfälle:
  • Datenanalyse (Excel) + Präsentationserstellung (PowerPoint)
  • Berichtsgenerierung (Word) + Export zu PDF
  • Benutzerdefinierte Domänenlogik + Dokumentgenerierung
Vermeiden Sie:
  • Einschließen ungenutzter Skills (beeinträchtigt die Leistung)

Versionsverwaltungsstrategie

Für Produktion:
# Pin to specific versions for stability
container={
    "skills": [{
        "type": "custom",
        "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
        "version": "1759178010641129"  # Specific version
    }]
}
Für Entwicklung:
# Use latest for active development
container={
    "skills": [{
        "type": "custom",
        "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv",
        "version": "latest"  # Always get newest
    }]
}

Überlegungen zum Prompt Caching

Beachten Sie beim Verwenden von Prompt Caching, dass das Ändern der Skills-Liste in Ihrem Container den Cache bricht:
# First request creates cache
response1 = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25", "skills-2025-10-02", "prompt-caching-2024-07-31"],
    container={
        "skills": [
            {"type": "anthropic", "skill_id": "xlsx", "version": "latest"}
        ]
    },
    messages=[{"role": "user", "content": "Analyze sales data"}],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

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

Fehlerbehandlung

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

Nächste Schritte