Seit Anthropic im Oktober 2025 das Konzept vorgestellt hat, sind Claude Skills zu einem der meistgesuchten Claude-Themen im deutschsprachigen Raum geworden: Der Suchbegriff “Claude Skills” kommt laut aktuellen Keyword-Daten auf rund 8.100 monatliche Suchanfragen in Deutschland. Das öffentliche Repository anthropics/skills auf GitHub zählt mittlerweile 176.867 Sterne und 20.936 Forks. Dieser Guide zeigt Schritt für Schritt, wie du eine eigene SKILL.md schreibst, sie lokal testest und anschließend in Claude Code, claude.ai oder über die API produktiv einsetzt.

Was sind Claude Skills?

Ein Claude Skill ist im Kern ein Ordner: eine Datei namens SKILL.md mit YAML-Kopfzeilen, ergänzt um beliebig viele Zusatzdateien wie Skripte, Vorlagen oder Referenzdokumente. Ein Anthropic-Guide zur Skill-Entwicklung bringt es kurz auf den Punkt: “A skill is a set of instructions – packaged as a simple folder – that teaches Claude how to handle specific tasks or workflows.” Claude liest diesen Ordner nicht komplett auf einmal, sondern lädt ihn stufenweise nach, sobald eine Aufgabe dazu passt. Anthropic beschreibt das Prinzip in einem Engineering-Beitrag so: “This led us to create Agent Skills: organized folders of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks.”

In der offiziellen Dokumentation zu Managed Agents heißt es ergänzend: “Skills are reusable, filesystem-based resources that give your agent domain-specific expertise: workflows, context, and best practices that turn a general-purpose agent into a specialist.” Der Unterschied zu einem simplen System-Prompt liegt in der Struktur: Ein Skill trennt Metadaten, Anleitung und ausführbaren Code in getrennte Ebenen, die nur bei Bedarf geladen werden. Dadurch bleibt der Kontext schlank, selbst wenn ein Konto Dutzende Skills gleichzeitig installiert hat.

Anthropic liefert bereits vier fertige Skills mit aus: pptx für PowerPoint, xlsx für Excel, docx für Word und pdf für PDF-Dokumente. In der offiziellen Quickstart-Dokumentation beschreibt Anthropic diese Auswahl so: “Pre-built Agent Skills extend Claude’s capabilities with specialized expertise for tasks such as creating documents, analyzing data, and processing files.” Alle vier laufen automatisch mit, sobald in claude.ai oder über die API eine passende Anfrage gestellt wird. Für alles darüber hinaus, etwa firmenspezifische Workflows oder Coding-Konventionen, schreibst du eigene Custom Skills. Genau darum geht es in diesem Tutorial.

Wie ein Skill in der Praxis an einen Agenten angehängt wird, zeigt ein Beispiel aus der offiziellen Dokumentation zu Managed Agents. Dort wird ein Finanzanalyse-Agent definiert, der einen vorgefertigten Excel-Skill mit einem selbst geschriebenen Custom Skill kombiniert:

---
name: Financial Analyst
model: claude-opus-5
skills:
  - type: anthropic
    skill_id: xlsx
  - type: custom
    skill_id: skill_01AbCdEfGhIjKlMnOpQrStUv
    version: latest
---

You are a financial analysis agent.

An diesem kurzen Beispiel wird der Kerngedanke greifbar: Ein Agent bekommt über das skills-Feld genau die Fähigkeiten, die er für seine Rolle braucht, nicht mehr und nicht weniger. Das hält den Kontext schlank und macht gleichzeitig nachvollziehbar, welche Skills in welchem Agenten aktiv sind.

Warum Claude Skills gerade jetzt so gefragt sind

Skills sind kein Nischenfeature geblieben. Laut Anthropics Release Notes werden sie inzwischen über die gesamte Plattform hinweg unterstützt, von claude.ai über Claude Code bis zum Claude Agent SDK und der Developer Platform. Am 15. September 2026, nur wenige Tage vor Redaktionsschluss dieses Artikels, hat Anthropic laut den Release Notes im Claude Help Center eine Salesforce-Integration veröffentlicht, die mit 37 vorgefertigten Sales-Skills ausgeliefert wird. Der Beta-Zugang läuft auf allen bezahlten Plänen, Unternehmen wie GitLab, Siemens und Legora setzen die Integration bereits bei rund 7.000 Vertriebsmitarbeitenden ein.

Auch technisch hat sich die Plattform weiterentwickelt. Die Compliance-API-Endpunkte für Cowork- und Claude-Code-Sitzungen sind laut den aktuellen API-Release-Notes nicht mehr im Beta-Status, sondern allgemein verfügbar. Für Unternehmen mit Audit-Pflichten ist das ein relevanter Unterschied, weil sich Skill-Nutzung damit zentraler protokollieren lässt. Wer selbst Skills bauen will, profitiert zusätzlich von der wachsenden Community: Das GitHub-Repository anthropics/skills sammelt Beispiele, Vorlagen und ein offizielles Cookbook für eigene Entwicklungen.

Für die DACH-Region kommt ein weiterer Faktor hinzu: Die Keyword-Daten zeigen neben dem Hauptbegriff “Claude Skills” auch konkrete Umsetzungsanfragen wie “claude skills installieren” und “claude skills erstellen”. Das deutet darauf hin, dass viele deutschsprachige Nutzer nicht nur über das Konzept lesen wollen, sondern konkret nach einer Schritt-für-Schritt-Anleitung suchen, wie sie in diesem Artikel folgt.

Der praktische Reiz ist einfach zu erklären. Statt bei jedem Chat erneut zu erklären, wie euer Team Changelogs formatiert, welche Excel-Vorlage für Quartalsberichte gilt oder nach welchem Schema Code-Reviews ablaufen, schreibst du diese Regeln einmal in eine SKILL.md. Claude zieht sie danach automatisch heran, sobald eine passende Aufgabe reinkommt.

Ein weiteres Signal für die wachsende Reife der Plattform: Für die Messages API steht laut den aktuellen Release Notes ein neues Beta-Feature bereit, das lange Konversationen auf Anfrage komprimiert, aktiviert über den Beta-Header compact-2026-09-04. Für Agenten, die viele Skills gleichzeitig laden und dadurch lange Sitzungen aufbauen, senkt das die Wahrscheinlichkeit, dass der Kontext vorzeitig voll läuft. Skills und Kontextmanagement entwickeln sich damit sichtbar in dieselbe Richtung: weniger manuell verwaltete Prompts, mehr strukturierte, wiederverwendbare Bausteine.

Voraussetzungen: Accounts, Tools und Versionen

Bevor du loslegst, brauchst du je nach Zielplattform unterschiedliche Zugänge. Für claude.ai müssen Custom Skills laut Anthropic-Dokumentation auf einem Pro-, Max-, Team- oder Enterprise-Plan mit aktivierter Code-Ausführung liegen. Für Claude Code reicht ein lokales Projektverzeichnis, für die API brauchst du einen API-Schlüssel oder eine angemeldete ant-CLI-Sitzung. Die folgende Tabelle fasst zusammen, was du in der Praxis installiert haben solltest.

WerkzeugGeprüfte VersionZweck in diesem Tutorial
Node.js20 LTS oder neuerLaufzeitumgebung für die Claude-Code-CLI
@anthropic-ai/claude-code (npm)2.1.274Claude Code CLI, liest lokale .claude/skills
anthropic (PyPI)1.6.0Python-SDK für die Skills-API
@anthropic-ai/sdk (npm)0.126.0TypeScript/JavaScript-SDK für die Skills-API
Python3.11 oder neuerAusführung von Skript-Ressourcen im Skill
ant CLIaktuelle VersionSkills auflisten, hochladen, Agenten anwenden
Claude.ai-PlanPro, Max, Team oder EnterpriseCustom Skills mit aktivierter Code-Ausführung hochladen

Ein Hinweis vorab: Die genauen Paketversionen ändern sich laufend. Prüfe vor dem Start immer npm view @anthropic-ai/claude-code version beziehungsweise pip index versions anthropic, damit du nicht mit veralteten Ständen arbeitest. Für dieses Tutorial reicht ein einfacher Texteditor, ein Terminal und ein bestehendes Anthropic-Konto.

Wenn du ausschließlich über die API arbeitest, kannst du auf die Claude-Code-Installation verzichten und direkt mit dem Python- oder TypeScript-SDK starten. Für Teams, die Skills sowohl lokal testen als auch später über die API ausrollen wollen, empfiehlt sich trotzdem die volle Kombination aus CLI, SDK und einem aktiven claude.ai-Account, weil sich damit alle drei Wege aus diesem Tutorial parallel nachvollziehen lassen.

Progressive Disclosure: Wie Claude Skills geladen werden

Um Skills sinnvoll zu schreiben, musst du zuerst verstehen, wie Claude sie lädt. Anthropic nennt das Prinzip progressive disclosure und unterteilt jeden Skill in drei Ebenen. Stufe eins ist die Metadatenebene: Nur Name und Beschreibung aus dem YAML-Kopf werden beim Start jeder Sitzung in den Systemprompt geladen. Stufe zwei greift, wenn eine Anfrage zur Beschreibung passt: Claude liest dann den gesamten Textkörper der SKILL.md über das Bash-Werkzeug nach. Stufe drei betrifft zusätzliche Dateien wie Skripte oder Referenzdokumente, die erst geladen werden, wenn der Skill-Text selbst darauf verweist.

Ein Beispiel aus der offiziellen Übersicht zeigt das Prinzip an einem PDF-Skill:

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---

# PDF Processing

## Quick start
Use pdfplumber to extract text from PDFs:

```python
import pdfplumber
with pdfplumber.open("document.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

For advanced form filling, see [FORMS.md](FORMS.md).

Das Feld description ist der wichtigste Teil der ganzen Datei, denn Claude vergleicht genau diesen Text mit deiner Anfrage, um zu entscheiden, ob der Skill überhaupt geladen wird. Eine zu vage Beschreibung führt dazu, dass Claude den Skill übersieht, selbst wenn er inhaltlich passen würde. Deshalb solltest du sowohl beschreiben, was der Skill tut, als auch wann er greifen soll, so wie im Beispiel oben mit “Use when working with PDF files or when the user mentions PDFs”.

Die dritte Stufe zeigt sich im selben Beispiel am Verweis auf FORMS.md. Solange Claude keine komplexere Formularaufgabe bekommt, bleibt diese Datei ungelesen. Erst wenn der Nutzer explizit nach Formularausfüllung fragt, folgt Claude dem Markdown-Link und lädt die Referenzdatei nach. Für dich als Autor bedeutet das: Du kannst einen Skill in einen schlanken Haupttext und beliebig viele Detaildateien aufteilen, ohne dass die Detaildateien den Kontext bei jeder Anfrage belasten. Bei umfangreichen Skills, etwa für komplette Compliance-Workflows, ist das der entscheidende Hebel, um trotzdem unter dem Kontextlimit zu bleiben.

Anleitung: Claude Skills in 12 Schritten einrichten

Die folgenden zwölf Schritte führen dich von der ersten Idee bis zum produktiv genutzten Skill in Claude Code, claude.ai und der API. Rechne für die komplette Strecke inklusive Testen mit rund 60 bis 90 Minuten, je nachdem wie umfangreich dein Skill wird.

Schritt 1: Zugriff und Plan prüfen

Prüfe zuerst, worüber du deinen Skill überhaupt nutzen willst. Für claude.ai brauchst du einen Pro-, Max-, Team- oder Enterprise-Plan mit aktivierter Code-Ausführung unter Einstellungen und dann Features. Für die API reicht laut der offiziellen Quickstart-Dokumentation entweder ein gültiger Claude-API-Schlüssel oder eine angemeldete ant-CLI-Sitzung, ergänzt um ein Client-SDK für deine Sprache oder alternativ curl und jq für direkte HTTP-Aufrufe. Für Claude Code brauchst du weder ein Upload noch eine spezielle Freischaltung, weil Custom Skills dort direkt aus dem Dateisystem gelesen werden. Wer alle drei Wege aus diesem Tutorial durchgehen will, sollte also vorab prüfen, ob Code-Ausführung im eigenen claude.ai-Konto aktiv ist, denn ohne diese Einstellung schlägt der Upload in Schritt 8 fehl.

Schritt 2: Claude Code CLI installieren

Installiere die Claude-Code-CLI global über npm. Die aktuell veröffentlichte Version ist 2.1.274.

npm install -g @anthropic-ai/claude-code
claude --version

Melde dich danach mit deinem Anthropic-Konto an, indem du im Terminal einfach claude aufrufst. Der Login-Flow öffnet automatisch den Browser.

Schritt 3: Projektstruktur für den Skill anlegen

Custom Skills für Claude Code liegen entweder persönlich unter ~/.claude/skills/ oder projektbezogen unter .claude/skills/ im Repository-Root. Lege für dieses Tutorial einen projektbezogenen Skill namens changelog-writer an.

mkdir -p .claude/skills/changelog-writer/scripts
cd .claude/skills/changelog-writer
touch SKILL.md

Schritt 4: SKILL.md mit YAML-Frontmatter schreiben

Öffne die leere SKILL.md und beginne mit dem YAML-Kopf. Halte den Namen kurz und die Beschreibung präzise, denn genau dieser Text entscheidet später über die Erkennung durch Claude.

---
name: changelog-writer
description: Formatiert Commit-Historien als strukturiertes Changelog nach Keep-a-Changelog-Konvention. Nutze diesen Skill, wenn nach einem Changelog, Release Notes oder einer Versionsübersicht gefragt wird.
---

Schritt 5: Instruktionen und Beispielcode ergänzen

Unter dem YAML-Kopf folgt der eigentliche Anleitungstext. Anthropics Best-Practice-Guide rät hier zu größtmöglicher Kürze: Ein Beispiel aus der offiziellen Dokumentation vergleicht eine knapp 50 Token lange Anleitung mit einer 150 Token langen Variante, die denselben Sachverhalt nur umständlicher erklärt. Gehe davon aus, dass Claude Grundwissen bereits mitbringt, und schreibe nur das, was spezifisch für deinen Workflow ist.

# Changelog Writer

## Vorgehen
1. Lies die letzten Commits mit `git log --oneline -n 30`.
2. Gruppiere nach Added, Changed, Fixed, Removed.
3. Schreibe im Markdown-Format nach Keep a Changelog.
4. Verlinke pro Eintrag die Commit-Kurz-ID in Klammern.

Nutze bei Bedarf `scripts/group_commits.py` für die Vorsortierung.

Schritt 6: Zusätzliche Ressourcen bündeln

Skripte, Vorlagen oder Referenzdateien gehören in Unterordner neben die SKILL.md. Sie werden laut Progressive-Disclosure-Prinzip erst geladen, wenn der Haupttext explizit darauf verweist, kosten also im Ruhezustand keinen Kontext. Lege für unser Beispiel ein einfaches Hilfsskript ab.

import subprocess

def group_commits(limit=30):
    raw = subprocess.check_output(
        ["git", "log", "--oneline", "-n", str(limit)]
    ).decode()
    return [line for line in raw.splitlines() if line.strip()]

if __name__ == "__main__":
    for line in group_commits():
        print(line)

Speichere diesen Code unter .claude/skills/changelog-writer/scripts/group_commits.py. Genau nach diesem Muster sind auch die offiziellen Anthropic-Skills aufgebaut: Der PDF-Skill aus dem Abschnitt zu Progressive Disclosure verweist beispielsweise auf eine zusätzliche Datei namens FORMS.md für komplexere Formularaufgaben. Für umfangreichere eigene Skills bietet sich ein eigener references-Ordner an, in dem du längere Nachschlagewerke ablegst, während die SKILL.md selbst kurz und auf den Kernablauf fokussiert bleibt.

Schritt 7: Skill lokal in Claude Code testen

Starte Claude Code im Projektordner und stelle eine Anfrage, die zur Beschreibung deines Skills passt, etwa “Erstelle mir ein Changelog für die letzten Commits”. Claude Code entdeckt projektbezogene Skills automatisch beim Sitzungsstart, ein manuelles Laden ist nicht nötig. Prüfe in der Ausgabe, ob Claude tatsächlich das im Skill vorgegebene Format verwendet und nicht auf eine generische Antwort zurückfällt.

Greift der Skill korrekt, sieht eine typische Ausgabe für unser Beispiel ungefähr so aus:

## [Unreleased]

### Added
- Neue SKILL.md für den changelog-writer-Skill (a3f9c12)
- Hilfsskript group_commits.py zur Commit-Vorsortierung (7b21e04)

### Fixed
- Falsches Datumsformat in der Release-Vorlage korrigiert (e88d331)

### Changed
- README um Abschnitt zu Custom Skills ergänzt (0c4f7aa)

Weicht die Ausgabe stark davon ab, etwa weil Claude die Gruppierung nach Added, Changed, Fixed und Removed ignoriert, liegt das fast immer an einer zu knappen description oder an einer Anfrage, die zu weit vom im Skill hinterlegten Trigger-Text entfernt ist. Formuliere die Testanfrage in diesem Fall näher an der description und prüfe erneut.

Schritt 8: Skill in claude.ai hochladen

Willst du denselben Skill auch im Browser nutzen, packst du den kompletten Ordner als ZIP-Datei und lädst ihn unter Einstellungen und dann Features hoch. Wichtig: Custom Skills in claude.ai sind laut Anthropic-Dokumentation an dein persönliches Konto gebunden, sie werden nicht automatisch organisationsweit geteilt und lassen sich von Admins nicht zentral verwalten.

cd .claude/skills
zip -r changelog-writer.zip changelog-writer

Schritt 9: Skill über die API einbinden

Für die Nutzung über die API lädst du den Skill zunächst über die Skills-API hoch, entweder per ant-CLI oder per HTTP-Aufruf, und referenzierst ihn anschließend im container-Parameter der Messages API. Voraussetzung ist, dass das Code-Ausführungs-Tool aktiviert ist, denn ohne dieses Tool kann Claude keinen Skill-Code ausführen.

ant skills create --file changelog-writer.zip

# Skill danach in einer Anfrage nutzen
response = client.messages.create(
    model="claude-opus-5",
    max_tokens=4000,
    container={
        "skills": [
            {"type": "custom", "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv", "version": "latest"}
        ]
    },
    messages=[
        {"role": "user", "content": "Erstelle ein Changelog für die letzten 20 Commits"}
    ],
    tools=[{"type": "code_execution_20260521", "name": "code_execution"}],
)

Die Skill-ID im Feld skill_id bekommst du als Rückgabewert beim Anlegen des Skills. Anthropic-eigene Skills wie pptx oder xlsx referenzierst du dagegen einfach über ihren Kurznamen und den Typ anthropic. Achte außerdem auf die Version des code_execution-Tools im tools-Array: Die Dokumentation nennt aktuell code_execution_20260521 als Referenzversion, weist aber ausdrücklich darauf hin, dass auch ältere Versionen wie code_execution_20250825 mit Skills funktionieren, solange es sich um eine derzeit unterstützte Tool-Version handelt. Bei eigenen Integrationen lohnt sich ein Blick auf die Seite zum Code-Ausführungs-Tool, um die für dein SDK passende Versionsbezeichnung zu bestätigen.

Schritt 10: Skills direkt aus einem GitHub-Repository laden

Statt Skills manuell hochzuladen, kannst du sie auch aus einem gemounteten GitHub-Repository laden lassen. Dafür muss die Sitzung das Repository über eine github_repository-Ressource einbinden. Claude scannt dann beim Sitzungsstart das Verzeichnis .claude/skills im Repository-Root und findet Skills genau eine Ebene tief.

your-repo/
  .claude/
    skills/
      code-review/
        SKILL.md
      release-process/
        SKILL.md
        scripts/
          run_checks.sh
  src/

Diese Methode funktioniert laut Dokumentation nur in Cloud-Sandboxes, selbst gehostete Sandboxes unterstützen keine GitHub-Repository-Ressourcen. Außerdem braucht der Agent das Read-Werkzeug, um die Skills überhaupt zu entdecken.

Schritt 11: Vorgefertigte Anthropic-Skills kombinieren

Eigene und vorgefertigte Skills lassen sich im selben Aufruf mischen. Willst du zum Beispiel dein Changelog direkt als Word-Dokument exportieren, kombinierst du deinen Custom Skill mit dem Anthropic-Skill docx im selben skills-Array. Beachte dabei das Limit: Eine Sitzung unterstützt laut Anthropic bis zu 500 Skills, gezählt als deduplizierte Menge über alle Agenten der Sitzung hinweg. Je mehr Skills gemountet werden, desto länger dauert der Start der Sandbox, binde also nur ein, was ein Agent für seine konkrete Aufgabe wirklich braucht.

Schritt 12: Skill versionieren und im Team ausrollen

Sobald der Skill zuverlässig funktioniert, gehört er ins Versionskontrollsystem. Für Claude-Code-Skills reicht ein normaler Commit in .claude/skills, damit das gesamte Team dieselbe Version nutzt. Für API-Skills kannst du über das Feld version gezielt eine bestimmte Version anpinnen, statt automatisch immer die neueste zu laden, was bei produktiven Workflows Kontrolle über Änderungen gibt. Committe außerdem Testfälle: Ein paar Beispielanfragen mit erwarteter Ausgabe helfen dabei, Regressionen zu erkennen, wenn jemand später die SKILL.md ändert.

Plane von Anfang an einen kurzen Änderungsprozess ein: Wer darf die SKILL.md bearbeiten, wer testet die Änderung vor dem Merge, und wie wird eine neue Version an alle Nutzer verteilt, die den Skill bereits eingebunden haben? Gerade bei API-Skills mit fest angepinnter Version bleibt eine neue Fassung sonst wirkungslos, bis jemand aktiv das version-Feld in jeder betroffenen Anwendung aktualisiert.

Claude Skills im Plattform-Vergleich

Je nachdem, wo du Skills einsetzt, unterscheiden sich Upload-Weg, Sichtbarkeit und Verwaltung deutlich. Die folgende Übersicht fasst die wichtigsten Unterschiede zusammen.

PlattformWie Skills geladen werdenVerwaltung
claude.aiZIP-Upload unter Einstellungen > FeaturesIndividuell pro Nutzerkonto, nicht organisationsweit
Claude CodeDirekt aus ~/.claude/skills oder .claude/skillsDateisystembasiert, per Git versionierbar
Claude APIUpload über die Skills-API, Referenz im container-ParameterZentral über Skill-IDs, mit Versionierung
GitHub-RepositoryAutomatisches Scannen von .claude/skills bei SitzungsstartÜber Repository-Berechtigungen, nur Cloud-Sandboxes

In der Praxis kombinieren viele Teams mehrere dieser Wege. Ein typisches Muster: Entwickler pflegen Repository-Skills fürs eigene Codebase-Wissen, während dieselbe Organisation zusätzlich API-Skills für unternehmensweite Dokumentenerstellung betreibt und einzelne Mitarbeitende sich persönliche Custom Skills in claude.ai für ihren individuellen Workflow anlegen. Alle drei Wege greifen auf dasselbe SKILL.md-Format zurück, unterscheiden sich aber darin, wer den Skill sieht und wie er aktualisiert wird.

Drei Skill-Typen im Überblick: Anthropic, Custom und Repository

Für die tägliche Arbeit lohnt es sich, die drei Skill-Typen sauber auseinanderzuhalten, weil sie unterschiedlich referenziert werden und unterschiedliche Voraussetzungen für die Sichtbarkeit im Team mitbringen.

  • Anthropic-Skills: Vorgefertigt und in jedem Workspace verfügbar, referenziert über den Typ anthropic und einen Kurznamen wie pptx, xlsx, docx oder pdf.
  • Custom Skills: Selbst geschrieben und hochgeladen, referenziert über eine skill_-ID, die beim Anlegen zurückgegeben wird.
  • Repository-Skills: Liegen im Code selbst unter .claude/skills, brauchen keinen separaten Upload, werden aber nur in Cloud-Sandboxes automatisch erkannt.

Die Wahl hängt stark vom Team ab. Kleine Projekte fahren mit Repository-Skills am einfachsten, weil Änderungen automatisch mit dem Code-Review-Prozess laufen. Größere Organisationen mit mehreren Teams nutzen dagegen oft Custom Skills über die API, weil sich Versionen dort gezielter steuern lassen.

Skills im Claude Agent SDK und in Unternehmensumgebungen

Claude Skills sind nicht auf claude.ai oder die klassische Messages API beschränkt. Laut Anthropics Engineering-Beitrag werden Agent Skills bereits heute über claude.ai, Claude Code, das Claude Agent SDK und die Developer Platform hinweg unterstützt. Für Teams, die eigene Agenten mit dem Agent SDK bauen, bedeutet das: Derselbe Skill-Ordner, den du in Schritt 3 bis 6 dieses Tutorials angelegt hast, lässt sich ohne Anpassung auch in einer SDK-basierten Anwendung wiederverwenden. Es entsteht kein separater Skill-Dialekt pro Plattform, sondern ein gemeinsames Format.

Wie ernst Unternehmen dieses Format inzwischen nehmen, zeigt die Salesforce-Integration vom 15. September 2026. Statt einen einzelnen Skill zu veröffentlichen, hat Anthropic direkt 37 vorgefertigte Sales-Skills mitgeliefert, die Accounts, Opportunities und Pipeline-Daten direkt in Claude verfügbar machen. Laut den Release Notes läuft die Integration im Beta-Modus auf allen bezahlten Plänen und wird bereits von Unternehmen wie GitLab, Siemens und Legora bei schätzungsweise 7.000 Vertriebsmitarbeitenden eingesetzt. Für ein Unternehmen dieser Größenordnung wäre es kaum praktikabel, jede Vertriebsregel manuell in einzelne Prompts zu gießen. Ein Bündel klar abgegrenzter Skills lässt sich dagegen zentral pflegen und bei Bedarf aktualisieren, ohne dass jede Nutzerin und jeder Nutzer die eigenen Prompts anpassen muss.

Für den Enterprise-Einsatz kommt ein weiterer Baustein hinzu: die inzwischen aus der Beta-Phase entlassenen Compliance-API-Endpunkte für Cowork- und Claude-Code-Sitzungen. Sie erlauben es, Sitzungen inklusive der dabei genutzten Skills zentral zu protokollieren, was in regulierten Branchen wie Finanzdienstleistungen oder Gesundheitswesen häufig eine Grundvoraussetzung für den produktiven Einsatz ist. Wer eigene Skills für ein solches Umfeld baut, sollte deshalb von Anfang an dokumentieren, welche Daten ein Skill verarbeitet und über welche Werkzeuge er dabei verfügt, damit diese Angaben bei einer Prüfung sofort verfügbar sind.

Häufige Fehler beim Einrichten eigener Skills

Die meisten Probleme mit eigenen Skills entstehen nicht durch komplizierten Code, sondern durch kleine strukturelle Fehler. Diese sechs Punkte tauchen in der Praxis am häufigsten auf.

  • Zu vage Beschreibung: Wenn das description-Feld nur “hilft bei Dokumenten” sagt statt konkret zu benennen, wann der Skill greifen soll, findet Claude ihn bei passenden Anfragen oft nicht.
  • Verschachtelung zu tief: Repository-Skills werden nur genau eine Ebene unter .claude/skills erkannt. Eine Struktur wie .claude/skills/tools/code-review/SKILL.md wird laut Dokumentation ignoriert.
  • Zu ausführliche Instruktionen: Lange Erklärungen zu Dingen, die Claude bereits weiß, kosten unnötig Kontext und verdrängen wichtigere Informationen aus dem Skill-Text.
  • Fehlendes Code-Ausführungs-Tool: Ohne das Tool code_execution in der Anfrage kann Claude keinen Skill-Code ausführen, selbst wenn der Skill korrekt referenziert wurde.
  • Ungetestete Skripte: Ressourcen wie Python-Skripte werden erst zur Laufzeit ausgeführt. Ein Syntaxfehler fällt oft erst im produktiven Einsatz auf, nicht beim Schreiben.
  • Ungeprüfte Fremd-Repositories: Wer ein fremdes Repository mit unbekannten .claude/skills-Inhalten mountet, lässt Claude fremden Code und fremde Anweisungen ungeprüft laden.
  • Falsche Erwartung an Sichtbarkeit: Ein in claude.ai hochgeladener Custom Skill ist an das eigene Konto gebunden. Wer davon ausgeht, dass Kolleginnen und Kollegen denselben Skill automatisch sehen, wird beim ersten Teamtest überrascht.

Sicherheit: Die Trust-Boundary bei Repository-Skills

Repository-Skills verdienen an dieser Stelle einen eigenen Absatz, weil sie ein reales Sicherheitsrisiko mit sich bringen. Anthropics eigene Dokumentation warnt explizit: Skills aus einem gemounteten Repository sind Agenteninstruktionen, das gemountete Repository wird damit Teil der Vertrauensgrenze des Agenten. Jeder, der ins Repository committen kann, sei es über einen gemergten externen Pull Request, eine kompromittierte Abhängigkeit oder einen einzelnen Mitwirkenden, kann einen Skill hinzufügen oder verändern. Die Plattform lädt diesen Skill beim Sitzungsstart ohne Review-Schritt, und Sitzungswerkzeuge wie Bash oder Web-Fetch geben diesen Anweisungen echte Reichweite im System.

Praktisch bedeutet das: Mounte nur Repositories, denen du vertraust, und wirf vor dem Mounten einen Blick in .claude/skills, besonders wenn das Repository externe Beiträge akzeptiert. Für sensible Projekte lohnt sich eine feste Regel im Team, dass Änderungen an Skill-Dateien immer einen zusätzlichen Review durch eine zweite Person durchlaufen, unabhängig vom normalen Code-Review.

Diese Vorsicht gilt genauso für hochgeladene ZIP-Dateien in claude.ai oder für Custom Skills, die über die API verteilt werden. Auch dort führt ein Skill mit manipuliertem Instruktionstext dazu, dass Claude im Namen des Nutzers Aktionen ausführt, die niemand explizit angefordert hat. Behandle SKILL.md-Dateien deshalb mit derselben Sorgfalt wie Produktionscode, inklusive Code-Review, Versionskontrolle und einer klaren Zuständigkeit dafür, wer Änderungen freigeben darf. Ein einfacher, aber wirksamer Schutzmechanismus: Lass dir bei jedem neuen Skill-Pull-Request explizit die geänderten Zeilen in SKILL.md anzeigen, statt nur den Diff der begleitenden Skripte zu prüfen, denn genau im Instruktionstext verstecken sich die riskantesten Änderungen.

Fortgeschrittene Tipps für Profis

Wenn die Grundlagen sitzen, lohnen sich ein paar Kniffe aus der Praxis. Erstens: Setze auf unterschiedliche Freiheitsgrade je nach Aufgabe. Für Aufgaben mit vielen gültigen Lösungswegen reichen textbasierte Heuristiken, für fragile oder variable Abläufe solltest du dagegen präzisere Schritt-für-Schritt-Anleitungen schreiben. Anthropics Best-Practice-Guide nennt das explizit “matching the level of specificity to the task’s fragility and variability”.

Zweitens: Nutze Verweise statt Wiederholungen. Wenn mehrere Skills dieselbe Hilfsfunktion brauchen, etwa eine gemeinsame Formatierungsregel, verweise per Markdown-Link auf eine gemeinsame Referenzdatei statt den Text mehrfach zu kopieren. Drittens: Prüfe bei API-Skills regelmäßig, welche Version der code_execution-Tools du verwendest. Anthropics Beispiele nutzen aktuell code_execution_20260521, ältere Versionen wie code_execution_20250825 funktionieren laut Dokumentation aber ebenfalls mit Skills, solange es sich um eine aktuelle Tool-Version handelt.

Viertens: Baue dir eine kleine Testsammlung mit fünf bis zehn typischen Anfragen pro Skill und prüfe nach jeder Änderung an der SKILL.md, ob die Antworten noch dem erwarteten Muster folgen. Das kostet am Anfang etwas Zeit, verhindert aber, dass ein gut funktionierender Skill durch eine kleine Textänderung plötzlich unzuverlässig wird.

Fünftens: Trenne Skills nach Zuständigkeit statt einen einzigen riesigen Skill für ein ganzes Team zu bauen. Ein Skill für Changelogs, ein zweiter für API-Dokumentation und ein dritter für Release-Checklisten lassen sich unabhängig voneinander pflegen, testen und versionieren. Das deckt sich mit der Beobachtung aus der Skill-Struktur im GitHub-Repository code-review und release-process, die bewusst als zwei getrennte Skills mit jeweils eigener SKILL.md angelegt sind, statt beide Themen in eine Datei zu packen.

Fehlerbehebung: Die häufigsten Probleme gelöst

Auch bei sorgfältiger Vorbereitung tauchen beim ersten eigenen Skill typische Stolperfallen auf. Die gute Nachricht: Fast alle lassen sich mit denselben zwei Werkzeugen eingrenzen, die auch beim normalen Debugging helfen, nämlich einer Testanfrage in isolierter Umgebung und einem genauen Blick in die Verzeichnisstruktur. Diese Tabelle zeigt die häufigsten Fehlerbilder mit Ursache und Lösung.

ProblemWahrscheinliche UrsacheLösung
Claude nutzt den Skill niedescription-Feld zu allgemein formuliertdescription konkretisieren, Trigger-Formulierungen wie “Nutze, wenn…” ergänzen
Skill wird in Claude Code nicht gefundenFalscher Pfad oder falsche OrdnertiefePrüfen, ob SKILL.md exakt unter .claude/skills/name/ liegt
Skill funktioniert lokal, aber nicht über die APIcode_execution-Tool fehlt in der Anfragetools-Array um ein code_execution-Tool ergänzen
Upload in claude.ai schlägt fehlCode-Ausführung im Konto nicht aktiviertIn den Einstellungen Code-Ausführung aktivieren, Plan prüfen
Repository-Skill wird nicht erkanntSandbox ist selbst gehostet statt Cloud-basiertCloud-Sandbox verwenden, self-hosted unterstützt keine Repository-Skills
Skript im Skill bricht mit Fehler abUngetesteter Code oder fehlende AbhängigkeitSkript isoliert lokal ausführen, bevor er in den Skill-Ordner kommt
Antwort wirkt inkonsistent mit der AnleitungZu lange oder widersprüchliche Instruktionen im TextkörperText kürzen, Reihenfolge der Schritte prüfen, Widersprüche entfernen
Sandbox-Start dauert spürbar längerZu viele gleichzeitig gemountete SkillsNur Skills mounten, die die konkrete Aufgabe wirklich braucht
Zwei Skills widersprechen sichÜberlappende description-Felder bei mehreren SkillsDescriptions klarer voneinander abgrenzen, Zuständigkeiten eindeutig aufteilen

Bleibt ein Problem trotz dieser Checkliste bestehen, hilft es meist, die SKILL.md testweise auf ein Minimalbeispiel zu reduzieren, ähnlich dem PDF-Beispiel aus dem Abschnitt zu Progressive Disclosure, und von dort aus schrittweise wieder aufzubauen. So lässt sich fast immer eingrenzen, ob das Problem an der description, an fehlenden Tools oder an der Ordnerstruktur liegt.

Komplettes Beispielprojekt: Ein eigener Skill von Null bis Produktion

Zum Abschluss ein vollständiges Beispiel, das alle Schritte dieses Tutorials zusammenführt. Ziel ist ein Skill namens api-doc-writer, der aus Python-Funktionssignaturen automatisch eine Markdown-Dokumentation im Stil deines Teams erzeugt.

mkdir -p .claude/skills/api-doc-writer/scripts
cat > .claude/skills/api-doc-writer/SKILL.md << 'EOF'
---
name: api-doc-writer
description: Erzeugt Markdown-API-Dokumentation aus Python-Funktionssignaturen im Team-Stil. Nutze diesen Skill, wenn nach API-Dokumentation, Docstrings oder einer Funktionsreferenz gefragt wird.
---

# API Doc Writer

## Vorgehen
1. Lies die Zieldatei und extrahiere alle öffentlichen Funktionen.
2. Formatiere jede Funktion als:
   ### funktionsname(parameter)
   Kurzbeschreibung, Parameter-Tabelle, Rückgabewert.
3. Nutze `scripts/extract_signatures.py`, um Signaturen automatisiert zu extrahieren.
4. Sortiere Funktionen alphabetisch innerhalb jeder Datei.
EOF

cat > .claude/skills/api-doc-writer/scripts/extract_signatures.py << 'EOF'
import ast
import sys

def extract_signatures(path):
    with open(path) as f:
        tree = ast.parse(f.read())
    for node in ast.walk(tree):
        if isinstance(node, ast.FunctionDef) and not node.name.startswith("_"):
            args = [a.arg for a in node.args.args]
            print(f"{node.name}({', '.join(args)})")

if __name__ == "__main__":
    extract_signatures(sys.argv[1])
EOF

Teste den Skill direkt danach in Claude Code mit einer Anfrage wie "Dokumentiere die öffentlichen Funktionen in utils.py". Für eine Datei mit einer einzelnen Funktion def calculate_total(items, tax_rate): liefert der Skill in etwa folgende Ausgabe:

### calculate_total(items, tax_rate)

Berechnet die Gesamtsumme einer Liste von Positionen inklusive Steuer.

| Parameter | Beschreibung |
|-----------|--------------|
| items | Liste der Einzelpositionen |
| tax_rate | Steuersatz als Dezimalzahl |

Rückgabewert: Gesamtsumme inklusive Steuer als float.

Läuft das Ergebnis zuverlässig, committest du den kompletten Ordner ins Repository, damit das gesamte Team denselben Skill nutzt.

git add .claude/skills/api-doc-writer
git commit -m "Add api-doc-writer Claude Skill"
git push

Willst du denselben Skill zusätzlich über die API nutzen, packst du den Ordner als ZIP, lädst ihn über die Skills-API hoch und referenzierst die zurückgegebene Skill-ID im container-Parameter, genau wie in Schritt 9 gezeigt. Damit steht ein Skill, der lokal in Claude Code, im Team über Git und zentral über die API funktioniert.

Häufig gestellte Fragen

Was kostet die Nutzung von Claude Skills?

Für die Metadaten eines Skills fallen laut Anthropics Dokumentation nur geringe Kontextkosten an, da beim Start lediglich Name und Beschreibung geladen werden. Sobald ein Skill vollständig geladen und mit Code-Ausführung genutzt wird, zählen die dabei verbrauchten Tokens regulär zu deinem API- beziehungsweise Plan-Kontingent. Eine separate Lizenzgebühr für Skills selbst gibt es nicht, entscheidend ist allein, wie viele Tokens durch Metadaten, geladenen Skill-Text und die eigentliche Code-Ausführung entstehen. Wer mehrere umfangreiche Skills parallel einsetzt, sollte deshalb regelmäßig die Tokenauslastung prüfen, besonders wenn viele Skills gleichzeitig in einer einzigen Sitzung gemountet sind.

Kann ich Claude Skills auf Deutsch schreiben?

Ja. Sowohl das description-Feld als auch der Instruktionstext können in jeder Sprache verfasst werden, die Claude versteht, einschließlich Deutsch. Wichtig ist nur, dass die Sprache konsistent zu den Anfragen bleibt, die den Skill auslösen sollen.

Wie viele Skills kann ich gleichzeitig verwenden?

Eine Sitzung unterstützt laut Anthropic bis zu 500 Skills, gezählt als deduplizierte Menge über alle Agenten der Sitzung hinweg. In der Praxis lohnt es sich aber, deutlich weniger gleichzeitig zu mounten, weil jeder zusätzliche Skill den Start der Sandbox verlangsamt. Als Faustregel hat sich bewährt, pro Agent nur die Skills einzubinden, die für dessen konkrete Rolle relevant sind, so wie im Financial-Analyst-Beispiel weiter oben, das bewusst nur einen Excel-Skill und einen einzigen Custom Skill kombiniert statt einer breiten Sammlung.

Funktionieren Custom Skills auch ohne Code-Ausführung?

Reine Textanleitungen ohne begleitende Skripte lassen sich auch ohne aktiviertes Code-Ausführungs-Tool nutzen. Sobald ein Skill aber Skripte enthält, die tatsächlich ausgeführt werden sollen, wie in unserem Beispielprojekt, braucht die Anfrage zwingend das code_execution-Tool.

Was ist der Unterschied zwischen einem Skill und einem klassischen Prompt?

Ein klassischer Prompt wird bei jeder Anfrage neu formuliert und komplett in den Kontext geladen. Ein Skill dagegen liegt dauerhaft als Datei vor, wird nur bei passender Anfrage automatisch nachgeladen und kann zusätzlich Skripte und Referenzdateien mitbringen, die ein reiner Prompt nicht abbilden kann. Wiederkehrende Workflows lassen sich damit einmal sauber dokumentieren, statt sie bei jedem neuen Chat erneut zu erklären.

Sind meine Custom Skills in claude.ai für Kollegen sichtbar?

Nein. Laut Anthropics Dokumentation sind Custom Skills in claude.ai individuell an das jeweilige Nutzerkonto gebunden. Sie werden nicht automatisch organisationsweit geteilt und lassen sich von Administratoren nicht zentral verwalten. Für teamweite Nutzung eignen sich Repository-Skills oder API-Skills deutlich besser.

Wo finde ich fertige Beispiele für eigene Skills?

Das öffentliche Repository anthropics/skills auf GitHub sammelt offizielle Beispiele und ein Cookbook für eigene Entwicklungen. Die Projektbeschreibung selbst fasst den Zweck knapp zusammen: "Skills are folders of instructions, scripts, and resources that Claude loads dynamically to improve performance on specialized tasks." Mit 176.867 Sternen und 20.936 Forks gehört das Repository zu den meistbeachteten Anthropic-Projekten überhaupt und ist ein guter Ausgangspunkt, um bestehende Skills als Vorlage zu kopieren statt bei null zu starten.

Kann ich einen Skill für mehrere Claude-Modelle gleichzeitig nutzen?

Ein Skill ist modellunabhängig aufgebaut, solange das jeweilige Modell Tools und Code-Ausführung unterstützt. In den Beispielen der offiziellen Dokumentation wird aktuell claude-opus-5 verwendet, die SKILL.md selbst enthält aber keine modellspezifischen Angaben. Du kannst denselben Skill-Ordner also grundsätzlich mit unterschiedlichen Modellen referenzieren, solltest das Verhalten bei einem Modellwechsel aber trotzdem einmal gegentesten, weil sich die Interpretation der Instruktionen je nach Modell leicht unterscheiden kann.