> So schreiben Sie einen Claude Skill: Verzeichnisaufbau, Frontmatter-Felder und Grenzen, progressives Laden, auslösende Beschreibungen, Skripte und Tests. > > Web page: https://balazscsorba.com/de/blog/claude-skills-guide · Language: Deutsch · Also available in: [English](https://balazscsorba.com/blog/claude-skills-guide.md) · [Magyar](https://balazscsorba.com/hu/blog/claude-skills-guide.md) > Author: Balázs Csorba · Published: 2026-10-20 · Keywords: claude skills, claude code skills, claude skill erstellen, skill.md format, agent skills spezifikation, claude skill frontmatter felder, skill-beschreibung auslösen, progressive disclosure bei skills, claude skills vs mcp vergleich, skills api anleitung, eigene slash-commands als skills [Blog](https://balazscsorba.com/de/blog)/[KI-Agenten](https://balazscsorba.com/de/blog/category/agents) # Claude Skills: So schreiben Sie eine SKILL.md, die zum richtigen Zeitpunkt lädt So schreiben Sie einen Claude Skill: Verzeichnisaufbau, Frontmatter-Felder und Grenzen, progressives Laden, auslösende Beschreibungen, Skripte und Tests. [Balázs Csorba](https://balazscsorba.com/de/about)·20\. Oktober 2026·12 Min. Lesezeit - Claude skills - SKILL.md - [Claude Code](https://balazscsorba.com/de/blog/tag/claude-code) - Agent Skills - Progressive disclosure ![Claude Skills: Ein offener Werkzeugkasten mit stehenden Mappen, eine Mappe mit einem Blatt ist herausgezogen.](https://balazscsorba.com/images/blog/claude-skills-guide/cover.webp?v=28589f7ab8) ## Das Wichtigste in Kürze - Ein Skill ist ein Ordner, dessen Frontmatter in SKILL.md Claude sagt, wann er zu verwenden ist; Anleitung und beiliegende Dateien werden später geladen, nur wenn eine Aufgabe sie braucht. - Der Name hat 1 bis 64 Zeichen aus Kleinbuchstaben, Ziffern und Bindestrichen; die Beschreibung darf 1.024 Zeichen lang sein und soll sagen, was der Skill tut und wann er verwendet wird. - Claude Code ignoriert unbekannte Frontmatter-Felder still, claude.ai-Uploads und die Skills API weisen sie dagegen zurück; prüfen Sie die Datei deshalb auf der Oberfläche, auf der Sie sie einsetzen. - Schreiben Sie die Beschreibung in der dritten Person mit den Wörtern, die Nutzer tatsächlich eingeben; die Auflistung kürzt lange Texte bei 1.536 Zeichen, stellen Sie den Anwendungsfall also an den Anfang. - Testen Sie jeden Skill in frischen Sitzungen mit und ohne Skill, und beginnen Sie mit mindestens drei Auswertungen für die gefundenen Lücken. Auf dieser Seite 1. [Was ist ein Skill, und worin unterscheidet er sich von einem Prompt?](https://balazscsorba.com/#what-is-a-skill) 2. [Was enthält ein Skill-Verzeichnis?](https://balazscsorba.com/#skill-directory-layout) 3. [Welche Frontmatter-Felder gibt es, und welche Grenzen gelten?](https://balazscsorba.com/#frontmatter-fields-and-limits) 4. [Wie hält progressives Laden Skills schlank?](https://balazscsorba.com/#progressive-disclosure) 5. [Wie muss die Beschreibung formuliert sein, damit der Skill greift?](https://balazscsorba.com/#writing-the-description) 6. [Wo liegen Skills, und welche Sitzungen laden sie?](https://balazscsorba.com/#where-skills-live) 7. [Wie funktionieren Aufruf, Argumente und Werkzeugberechtigungen?](https://balazscsorba.com/#invocation-arguments-and-permissions) 8. [Wie sollten Skripte und Referenzdateien beiliegen?](https://balazscsorba.com/#bundling-scripts-and-references) 9. [Wie testen und verbessern Sie einen Skill?](https://balazscsorba.com/#testing-and-iterating) 10. [Quellen](https://balazscsorba.com/#sources) Diesen Artikel anhören 0:00 Ein Claude Skill ist ein Ordner mit einer Datei `SKILL.md` im Stammverzeichnis. Die Datei beginnt mit YAML-Frontmatter, das beschreibt, was der Skill tut und wann er verwendet werden soll, gefolgt von Anweisungen in Markdown. Claude liest das Frontmatter beim Start, lädt die Anweisungen, sobald eine Anfrage zum Skill passt, und öffnet beiliegende Dateien nur, wenn ein Schritt sie braucht. Claude Code, die Claude API und claude.ai unterstützen Skills auf Basis dieses Formats; Claude Code ergänzt Felder, die über den offenen Standard Agent Skills hinausgehen. Das Thema ist stark nachgefragt. In den Ahrefs-Daten, die SkillGild ausgewertet hat, erreichen „claude skills“ und „claude code skills“ jeweils etwa 10.000 Suchanfragen pro Monat in den USA, Stand des Exports vom 6. Oktober 2026. Warum sich Skills lohnen, erklärt der Beitrag zum [Workflow mit Skills für Coding-Agenten](https://balazscsorba.com/de/blog/coding-agent-skills-workflow) bereits. Dieser Leitfaden behandelt die Erstellung: den Verzeichnisaufbau, jedes Frontmatter-Feld mit seinen Grenzen, wie die Beschreibung darüber entscheidet, wann ein Skill geladen wird, wo Skills liegen, wie Argumente und Werkzeugberechtigungen funktionieren und wie Sie einen Skill testen. Jede Grenze stammt aus der Claude-Dokumentation oder dem offenen Standard, auf den sie sich bezieht. ## Was ist ein Skill, und worin unterscheidet er sich von einem Prompt? Ein Skill ist eine wiederverwendbare Ressource auf Dateibasis, die Claude fachspezifisches Wissen gibt. Ein Prompt ist eine Anleitung auf Gesprächsebene für eine einzelne Aufgabe. Ein Skill wird bei Bedarf geladen, sodass dieselbe Anleitung nicht in jedes Gespräch kopiert werden muss ([Übersicht Agent Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)). Für die Wahl zwischen Skills, Projektregeln und MCP-Werkzeugen lesen Sie den [Beitrag zur Entscheidungsmatrix](https://balazscsorba.com/de/blog/agents-md-skills-mcp-cli-decision-matrix). Das Interesse hat sich von Erklärungen zur Praxis verschoben. SkillGild berichtet, dass das Suchvolumen für „claude skills“ nach dem Start von Agent Skills im Oktober 2025 stark stieg, im Januar 2026 seinen Höhepunkt erreichte und seitdem um etwa 62 Prozent gefallen ist. Weiter gewachsen sind die praktischen Suchen: „how to create a claude skill“ und ihre Varianten ergeben zusammen etwa 10.200 Suchanfragen pro Monat ([SkillGild-Analyse](https://dev.to/skillgild/the-state-of-claude-skills-in-2026-what-38000-searches-say-248n)). In meinem eigenen Setup liegen etwa 20 Agenten-Skills in `~/.agents/skills`, und `jev-decide` ist einer davon. ## Was enthält ein Skill-Verzeichnis? Nur `SKILL.md` ist Pflicht. Der offene Standard definiert drei optionale Verzeichnisse: `scripts/` für ausführbaren Code, `references/` für Dokumentation, die Claude bei Bedarf liest, und `assets/` für Vorlagen, Bilder und Datendateien. Ein Skill kann außerdem weitere Dateien und Verzeichnisse enthalten ([Spezifikation Agent Skills](https://agentskills.io/specification)). ![Ordnerstruktur eines Skills namens pdf-processing mit SKILL.md, Referenzdateien und einem Skript.](https://balazscsorba.com/images/blog/claude-skills-guide/calc-7-de.webp?v=6123cd1274) SKILL.md ist Pflicht und enthält Frontmatter und Überblick; FORMS.md und REFERENCE.md werden nur gelesen, wenn die Aufgabe sie braucht. scripts/fill\_form.py läuft über Bash, und sein Code gelangt nie in den Kontext. Drei Regeln aus der Dokumentation prägen den Aufbau. Halten Sie jede Referenzdatei fokussiert, denn Agenten laden sie bei Bedarf, und kleinere Dateien verbrauchen weniger Kontext. Halten Sie Dateiverweise nur eine Ebene tief von `SKILL.md`: Verweist eine referenzierte Datei auf eine weitere, kann Claude sie nur teilweise lesen, und Informationen fehlen dann. Schreiben Sie Pfade mit Schrägstrichen, auch unter Windows, und benennen Sie Dateien nach ihrem Inhalt, etwa `form_validation_rules.md` statt `doc2.md` ([Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)). ## Welche Frontmatter-Felder gibt es, und welche Grenzen gelten? Der offene Standard verlangt zwei Felder, `name` und `description`; alle übrigen sind optional. Claude Code behandelt jedes Feld als optional, empfiehlt `description` und ergänzt Felder für Aufruf, Argumente und Subagenten. Die Tabelle nennt die Felder, die Sie am häufigsten brauchen, mit den Grenzen aus Spezifikation und Dokumentation. Feld Pflicht? Wofür Grenzen `name` Ja im Standard; in Claude Code optional Kennung; in Claude Code der Befehlsname, Standard ist der Verzeichnisname 1 bis 64 Zeichen: Kleinbuchstaben, Ziffern, Bindestriche; kein Bindestrich vorn oder hinten, keine doppelten; keine reservierten Wörter wie „anthropic“ oder „claude“ `description` Ja im Standard; in Claude Code empfohlen Was der Skill tut und wann Claude ihn verwenden soll 1 bis 1.024 Zeichen; keine XML-Tags `when_to_use` Nein Zusätzliche Auslösephrasen oder Beispielanfragen, an die Beschreibung angehängt Zählt zur Obergrenze von 1.536 Zeichen in der Auflistung (Claude Code) `license` Nein Name der Lizenz oder beiliegende Lizenzdatei Kurz halten (Spezifikation) `compatibility` Nein Umgebungsanforderungen: Produkte, Systempakete, Netzwerkzugang Bis 500 Zeichen (Spezifikation) `metadata` Nein Schlüssel-Wert-Zuordnung für eigene Werkzeuge Zeichenketten als Schlüssel und Werte (Spezifikation) `allowed-tools` Nein Werkzeuge, die der Skill ohne Berechtigungsabfrage nutzen darf Im Standard experimentell; durch Leerzeichen getrennt `disable-model-invocation` Nein `true`: nur Sie können den Skill aufrufen Nur Claude Code; Standard `false` `user-invocable` Nein `false`: der Skill fehlt im /-Menü, nur Claude ruft ihn auf Nur Claude Code; Standard `true` `argument-hint` Nein Hinweis für die Autovervollständigung, etwa `[issue-number]` Nur Claude Code Die Namensregeln sind streng: 1 bis 64 Zeichen aus Kleinbuchstaben, Ziffern und Bindestrichen, ohne Bindestrich am Anfang oder Ende und ohne doppelte Bindestriche. Die Spezifikation verlangt außerdem, dass der Name dem übergeordneten Verzeichnis entspricht. Claude Code ist großzügiger: Ein Verzeichnis `deploy-staging` mit `name: deploy` wird als `/deploy` aufgerufen, das Feld legt also den Befehlsnamen fest ([Claude Code Dokumentation](https://code.claude.com/docs/en/skills)). Zwei Details verursachen die meisten stillen Fehler. Claude Code ignoriert ein unbekanntes Feld ohne Fehlermeldung, ein falsch geschriebenes `allowed-tools` bewirkt also nichts. Das Frontmatter wird nur gelesen, wenn die öffnende Zeile `---` die erste Zeile der Datei ist; lässt sich das YAML nicht parsen, lädt der Skill ohne Metadaten und Claude kann ihn nicht über seine Beschreibung finden. Die Referenzbibliothek der Spezifikation, aufgerufen als `skills-ref validate ./my-skill`, prüft Frontmatter und Namensregeln. **Dieselbe Datei, zwei Ergebnisse** Dasselbe Frontmatter kann an einer Stelle bestehen und an einer anderen scheitern. Uploads auf claude.ai, die Skills API und das Packaging-Skript akzeptieren nur `name`, `description`, `license`, `compatibility`, `metadata` und `allowed-tools`. Jeder andere Schlüssel führt zu einem Fehler wie `Unexpected key(s) in SKILL.md frontmatter: argument-hint`. Claude Code akzeptiert seine eigenen Zusatzfelder, dieselbe Datei funktioniert also lokal und schlägt beim Upload fehl ([Claude Code Dokumentation](https://code.claude.com/docs/en/skills)). ## Wie hält progressives Laden Skills schlank? Claude lädt einen Skill in drei Stufen, und jede Stufe kostet nur Kontext, wenn sie gebraucht wird. Die Metadaten, etwa 100 Token pro Skill, werden beim Start geladen. Der Text von `SKILL.md`, empfohlen unter 5.000 Token, wird geladen, sobald der Skill ausgelöst wird. Beiliegende Dateien kosten nichts, bis eine Aufgabe sie liest oder ausführt ([Übersicht Agent Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)). ![Drei Ladestufen eines Skills: Metadaten beim Start, Anleitung beim Auslösen, Ressourcen erst bei Bedarf.](https://balazscsorba.com/images/blog/claude-skills-guide/diagram-17.webp?v=45d8bcc3ec) Bis ein Skill ausgelöst wird, belegen nur Name und Beschreibung den Kontext; jede spätere Stufe kommt nur hinzu, wenn eine Aufgabe sie braucht. Installierte Skills sind also günstig, lange Skills nicht. Halten Sie den Text unter 500 Zeilen und verlagern Sie Details in Referenzdateien, wie Spezifikation und Best-Practices-Leitfaden beide empfehlen. Die [Engineering-Veröffentlichung von Anthropic zu Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) behandelt Architektur und reale Einsätze ausführlicher. In langen Sitzungen zählen zwei Verhaltensweisen. Claude Code liest die Datei in späteren Runden nicht erneut; eine Regel, die für die ganze Aufgabe gelten muss, gehört daher in dauerhafte Anweisungen. Nach einer Verdichtung des Gesprächs hängt Claude Code den jeweils letzten Aufruf jedes Skills wieder an und behält die ersten 5.000 Token jedes Skills innerhalb eines gemeinsamen Budgets von 25.000 Token. Stellen Sie die wichtigsten Anweisungen deshalb an den Anfang ([Claude Code Dokumentation](https://code.claude.com/docs/en/skills)). Die Skill-Auflistung hat ein eigenes Budget, bemessen mit 1 Prozent des Kontextfensters des Modells. Wenn viele Skills es überschreiten, kürzt Claude Code zuerst die Beschreibungen der am seltensten aufgerufenen Skills; der kombinierte Text aus `description` und `when_to_use` wird unabhängig davon bei 1.536 Zeichen abgeschnitten. ## Wie muss die Beschreibung formuliert sein, damit der Skill greift? Die Beschreibung ist der einzige Teil eines Skills, den Claude liest, bevor er entscheidet, den Rest zu laden. Sie muss also sagen, was der Skill tut und wann er verwendet werden soll. Schreiben Sie in der dritten Person und verwenden Sie die Wörter, die ein Nutzer tatsächlich eintippt. Claude wählt unter potenziell 100 oder mehr Skills anhand dieser Beschreibungen aus, jede braucht also genug Details für diese Wahl ([Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)). Die Regel zur dritten Person gibt es, weil die Beschreibung in den Systemprompt eingefügt wird und eine uneinheitliche Perspektive die Auffindbarkeit beeinträchtigen kann. Die Beispiele des Leitfadens zeigen den Unterschied. „Processes Excel files and generates reports“ funktioniert; „I can help you process Excel files“ und „You can use this to process Excel files“ nicht. Vage Zeilen wie „Helps with documents“, „Processes data“ oder „Does stuff with files“ geben Claude nichts zum Abgleichen. Das PDF-Beispiel nennt Aktionen und Auslöser: „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.“ Wenn ein Skill nicht greift, prüfen Sie, ob die Beschreibung die Wörter enthält, die Nutzer sagen, bestätigen Sie mit der Frage nach den verfügbaren Skills, dass er aufgelistet ist, formulieren Sie die Anfrage neu und rufen Sie ihn als `/skill-name` auf, um einen Namensfehler auszuschließen. Stellen Sie den zentralen Anwendungsfall an den Anfang, denn die Auflistung kürzt lange Texte. Dieselbe Regel gilt für Werkzeuge von Agenten; siehe [Werkzeuge für KI-Agenten entwerfen](https://balazscsorba.com/de/blog/agent-tool-design-descriptions-errors). ## Wo liegen Skills, und welche Sitzungen laden sie? Wo ein Skill gespeichert ist, entscheidet, welche Sitzungen ihn laden. Ein persönlicher Skill in `~/.claude/skills/` lädt in jedem Projekt auf diesem Rechner. Ein Projekt-Skill in `.claude/skills/` lädt im jeweiligen Repository; committen Sie ihn, damit das Team ihn erhält. Ein Plugin-Skill lädt überall, wo das Plugin aktiviert ist. Claude Code liest Projekt-Skills aus dem Verzeichnis, in dem Sie starten, und aus jedem übergeordneten Verzeichnis bis zur Wurzel des Repositorys. Ort Pfad Geladen in Unternehmen `.claude/skills//SKILL.md` in the managed settings directory Alle Nutzer auf Rechnern, auf denen die Organisation es einrichtet Persönlich `~/.claude/skills//SKILL.md` Alle Projekte auf diesem Rechner, nicht aber Cowork- oder Cloud-Sitzungen Projekt `.claude/skills//SKILL.md` Sitzungen in diesem Repository; committen, damit das Team ihn erhält Unterverzeichnis `/.claude/skills//SKILL.md` Sitzungen, die in diesem Unterverzeichnis oder darunter starten Plugin `/skills//SKILL.md` Überall, wo das Plugin aktiviert ist, als `/plugin-name:skill-name` claude.ai-Konto Für das Konto aktivierte Skills Cowork-, Cloud- und Terminal-Sitzungen mit diesem Konto Verschachtelte Skills laden, sobald Claude zum ersten Mal eine Datei in ihrem Unterverzeichnis liest oder bearbeitet, und Änderungen während einer Sitzung wirken ohne Neustart. Zwei Ordnernamen sind reserviert: `synced` und `anthropic-skills`. **Persönliche Skills sind für Cloud-Sitzungen unsichtbar** Cowork- und Cloud-Sitzungen lesen `~/.claude/skills/` auf Ihrem Rechner nicht. Eine geplante Cloud-Aufgabe, die einen Skill aufruft, der nur dort liegt, meldet, dass der Skill nicht gefunden wurde. Aktivieren Sie den Skill stattdessen für Ihr claude.ai-Konto oder committen Sie ihn für Cloud-Sitzungen außerhalb von Projekt-Threads in das Verzeichnis `.claude/skills/` des Repositorys ([Claude Code Dokumentation](https://code.claude.com/docs/en/skills)). Die anderen Oberflächen haben eigene Regeln. Auf claude.ai laden Sie eine ZIP-Datei unter Settings > Features hoch; dafür sind ein Pro-, Max-, Team- oder Enterprise-Tarif mit aktivierter Codeausführung nötig, und die Skills gehören jedem Nutzer selbst, nicht der Organisation. Die Claude API nimmt Skills über die Endpunkte `/v1/skills` entgegen und teilt sie im gesamten Workspace. Skills werden nicht zwischen den Oberflächen synchronisiert, laden Sie jeden Skill also dort hoch, wo Sie ihn nutzen wollen ([Übersicht Agent Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)). ## Wie funktionieren Aufruf, Argumente und Werkzeugberechtigungen? Standardmäßig können Sie und Claude einen Skill aufrufen. `disable-model-invocation: true` macht einen Skill nur manuell aufrufbar, `user-invocable: false` nur von Claude, `allowed-tools` erlaubt Werkzeuge für den Zug, der den Skill aufruft, und `context: fork` führt ihn in einem Subagenten aus. Das Beispiel unten nutzt drei Funktionen: einen `argument-hint`, vorab erlaubte Git-Befehle und den Platzhalter `$ARGUMENTS`. Markdown ``` --- name: summarize-changes description: Summarizes uncommitted changes and flags risks. Use when the user asks what changed, wants a commit message, or asks to review their diff. argument-hint: [focus-area] allowed-tools: Bash(git diff *) Bash(git status *) --- ## Current changes !`git diff HEAD` ## Instructions Summarize the changes above in two or three bullet points. Focus area, if one was given: $ARGUMENTS List the risks you notice, such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes. ``` Argumente kommen über `$ARGUMENTS` an oder über `$0`, `$1` und so weiter für einzelne Positionen. Setzen Sie einen mehrteiligen Wert in Anführungszeichen, damit er als ein Argument gilt: `/my-skill "hello world" second` setzt `$0` auf `hello world`. Hat der Skill keinen Platzhalter für Ihre Eingabe, hängt Claude Code sie als `ARGUMENTS: ` an, damit Claude sie trotzdem sieht. `allowed-tools` erteilt die Erlaubnis nur für den Zug, der den Skill aufruft; sie erlischt, sobald Sie Ihre nächste Nachricht senden. Das Feld schränkt die Werkzeuge nicht ein: Ihre Berechtigungseinstellungen gelten weiterhin für alles, was die Liste nicht nennt. Das Vertrauen des Arbeitsbereichs ist für das Feld nicht erforderlich, ein `allowed-tools` eines Projekt-Skills gilt also auch in einem Ordner, dem Sie nie vertraut haben. Prüfen Sie dieses Feld bei jedem Skill, den Sie aus einem Repository übernehmen. Die Shell-Injektionszeile im Beispiel führt `git diff HEAD` aus, bevor Claude den Skill sieht, und die Ausgabe ersetzt den Platzhalter. Eingefügte Befehle fragen nicht nach, werden aber vorab gegen Ihre Berechtigungsregeln geprüft. Außerhalb des Auto-Modus bricht der Aufruf ab, wenn die Prüfung eines Befehls nicht „erlaubt“ ergibt, und ein fehlgeschlagener Befehl bricht den ganzen Skill ab, nicht nur seine Zeile. Deshalb erlaubt das Beispiel die Git-Befehle vorab. `context: fork` startet einen Subagenten vom Typ aus `agent` und übergibt ihm den Skill als Prompt. Der Subagent kennt Ihren Gesprächsverlauf nicht, der Skill muss also für sich allein funktionieren. Laut Dokumentation passt die Einstellung nur für Skills mit klaren Anweisungen; ein Skill nur mit Richtlinien liefert nichts Brauchbares. Geforkte Skills laufen im Hintergrund, außer Sie setzen `background: false`. Welche Skills Claude aufrufen darf, regeln Berechtigungsregeln: `Skill(commit)` trifft genau einen Skill, `Skill(deploy *)` einen Namen mit beliebigen Argumenten. Wenn Sie das Werkzeug Skill unter `/permissions` verweigern, sind alle Skills deaktiviert. ## Wie sollten Skripte und Referenzdateien beiliegen? Legen Sie ein Skript bei, wenn das Ergebnis jedes Mal gleich sein muss, und lassen Sie Claude es ausführen statt es zu lesen. Claude führt beiliegende Skripte über bash aus und sieht nur deren Ausgabe ([Übersicht Agent Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)). Der Best-Practices-Leitfaden setzt die Latte: Behandeln Sie den Fehlerfall, statt scheitern zu lassen und Claude raten zu lassen, und begründen Sie jede Konstante. Ein Timeout von 30 Sekunden mit einem Kommentar zum Grund ist dokumentiert; eine Zahl ohne Erklärung ist eine „Voodoo-Konstante“. Die Spezifikation ergänzt, dass Skripte in sich geschlossen sein oder ihre Abhängigkeiten dokumentieren, hilfreiche Fehlermeldungen ausgeben und Grenzfälle abfangen sollten ([Spezifikation](https://agentskills.io/specification)). Verweisen Sie auf das Skript mit `${CLAUDE_SKILL_DIR}`, das auf das Verzeichnis mit der `SKILL.md` des Skills expandiert. Verwenden Sie dieselbe Variable in den Anweisungen und in `allowed-tools`; dann läuft das Skript ohne Berechtigungsabfrage. Die Dokumentation zeigt dieses Muster: Markdown ``` --- name: render-chart description: Render a chart from a CSV file allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/render.sh *) --- Run `${CLAUDE_SKILL_DIR}/scripts/render.sh ` to render the chart. ``` Wo ein Skill läuft, bestimmt, was er erreicht. In der Claude API haben Skills keinen Netzwerkzugang und können zur Laufzeit keine Pakete installieren; alle Abhängigkeiten müssen also schon vorhanden sein. Auf claude.ai hängt der Netzwerkzugang von den Einstellungen des Nutzers und des Administrators ab. In Claude Code hat ein Skill denselben Netzwerkzugang wie jedes andere Programm auf dem Rechner, globale Paketinstallationen sind aber nicht empfohlen. Behandeln Sie einen Skill wie installierte Software. Verwenden Sie nur Skills, die Sie selbst geschrieben oder von Anthropic bezogen haben, prüfen Sie jede beiliegende Datei, und seien Sie besonders vorsichtig bei Skills, die externe Inhalte abrufen, denn abgerufener Text kann Anweisungen enthalten. Die Übersicht warnt außerdem, dass selbst vertrauenswürdige Skills kompromittiert werden können, wenn sich ihre externen Abhängigkeiten ändern. ## Wie testen und verbessern Sie einen Skill? Testen Sie zwei Dinge getrennt: ob Claude den Skill bei den richtigen Prompts lädt und ob die Ausgabe stimmt, wenn er geladen wird. Dass ein Skill auslöst, zeigt nur das Erste. Führen Sie einige realistische Prompts in frischen Sitzungen aus, mit dem Skill und ohne, denn Restkontext aus dem Schreiben des Skills verdeckt Lücken ([Claude Code Dokumentation](https://code.claude.com/docs/en/skills)). Der Best-Practices-Leitfaden verlangt Auswertungen vor der Dokumentation. Ermitteln Sie, wo Claude ohne den Skill scheitert, schreiben Sie mindestens drei Auswertungen für diese Lücken, halten Sie eine Ausgangsbasis fest und ergänzen Sie dann die kleinste Menge an Anweisungen, die sie besteht. Testen Sie mit jedem Modell, das Sie einsetzen wollen. Die Checkliste des Leitfadens nennt Haiku, Sonnet und Opus und weist darauf hin, dass ein Skill, der für Opus genügt, bei Haiku mehr Details braucht. Für einen persönlichen oder Projekt-Skill setzen Sie ihn in `skillOverrides` auf `"off"`, um den Vergleichslauf ohne Skill zu erhalten. Das Plugin skill-creator automatisiert die Schleife: Es speichert Fälle in `evals/evals.json`, startet jeden in einem eigenen Subagenten, bewertet Prüfungen in `grading.json`, fasst Trefferquote und Token in `benchmark.json` zusammen und kann die Beschreibung mit Prompts abstimmen, die den Skill auslösen sollten oder nicht. Sein Format unterscheidet sich von dem, das `claude plugin eval` für Plugins verwendet. Die [Anleitung zur Auswertung auf agentskills.io](https://agentskills.io/skill-creation/evaluating-skills) beschreibt den Iterationsablauf. Zwei Befehle finden Probleme, die sonst schwer zu sehen sind. `claude plugin validate` meldet SKILL.md-Dateien, deren Frontmatter nicht lesbar ist (Claude Code ab Version 2.1.233). `/skill-doctor` zeigt, was jeder Skill in der Auflistung kostet, und markiert Skills, die nie aufgerufen werden (ab Version 2.1.252). Beobachten Sie zuletzt, wie Claude den Skill nutzt. Der Best-Practices-Leitfaden nennt vier Signale: ungewöhnliche Lesereihenfolgen, Verweise, denen Claude nicht folgt, eine Referenzdatei, die bei jeder Aufgabe gelesen wird, und beiliegende Dateien, die nie geöffnet werden. Jedes davon weist auf eine strukturelle Korrektur hin, etwa einen expliziteren Verweis oder eine Datei, die in `SKILL.md` wandert. Wenn Sie Skills oder Agenten-Workflows für ein Team bauen, sehen Sie sich meine [Arbeit im Bereich KI-Engineering](https://balazscsorba.com/de/expertise/ai-engineer) an. ## Quellen 1. [Claude Code documentation: skills](https://code.claude.com/docs/en/skills) 2. [Agent Skills overview, Claude API documentation](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) 3. [Skill authoring best practices, Claude API documentation](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) 4. [Agent Skills specification](https://agentskills.io/specification) 5. [Evaluating skill output quality, Agent Skills documentation](https://agentskills.io/skill-creation/evaluating-skills) 6. [Equipping agents for the real world with Agent Skills, Anthropic engineering blog](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) 7. [The state of Claude skills in 2026, SkillGild analysis of Ahrefs data](https://dev.to/skillgild/the-state-of-claude-skills-in-2026-what-38000-searches-say-248n) ## Häufige Fragen Worin unterscheidet sich ein Claude Skill von einem Prompt? Ein Prompt ist eine Anleitung für ein Gespräch oder eine Aufgabe. Ein Skill ist ein Ordner, den Claude bei Bedarf lädt: Name und Beschreibung stehen immer bereit, der Text von SKILL.md wird beim Auslösen geladen, und beiliegende Dateien nur, wenn eine Aufgabe sie liest. Welche Felder braucht eine SKILL.md? Der offene Standard Agent Skills verlangt name und description. Der Name hat 1 bis 64 Zeichen aus Kleinbuchstaben, Ziffern und Bindestrichen. Die Beschreibung hat 1 bis 1.024 Zeichen und sagt, was der Skill tut und wann er verwendet wird. Claude Code macht alle Felder optional und ergänzt Felder für Aufruf, Argumente und Subagenten. Wo sollte eine Skill-Datei gespeichert werden? Ein persönlicher Skill liegt unter ~/.claude/skills//SKILL.md und gilt in jedem Projekt auf diesem Rechner; ein Projekt-Skill unter .claude/skills/ wird über das Repository geteilt. Plugin-Skills laden überall, wo das Plugin aktiviert ist. Auf claude.ai laden Sie eine ZIP-Datei unter Settings > Features hoch; die API nutzt die Endpunkte /v1/skills. Warum wird mein Skill nicht ausgelöst? Prüfen Sie, ob die Beschreibung die Wörter enthält, die Nutzer tatsächlich eingeben, fragen Sie Claude, welche Skills verfügbar sind, formulieren Sie die Anfrage neu und rufen Sie den Skill mit /skill-name auf. Ein fehlerhafter Frontmatter-Block lässt den Skill ohne Beschreibung zurück; führen Sie deshalb claude plugin validate auf dem Skill-Ordner aus. Soll ein Skill ein Skript aufrufen oder die Logik selbst enthalten? Deterministische Schritte gehören in ein beiliegendes Skript, das Claude ausführt, Urteilsentscheidungen in die Anweisungen. Claude führt das Skript über bash aus und sieht nur die Ausgabe, das spart Kontext und liefert wiederholbare Ergebnisse. Erlauben Sie das Skript in allowed-tools, damit der Lauf nicht an einer Berechtigungsabfrage hängen bleibt. Geschrieben von Balázs Csorba Senior Fullstack & AI Engineer in der Steiermark – über 10 Jahre Vue, Nuxt, Node.js und PHP, heute baue ich Werkzeuge für KI-Agenten. [KI-Entwicklung & MCP-Server →](https://balazscsorba.com/de/expertise/ai-engineer)[Über mich →](https://balazscsorba.com/de/about) ## Weitere Artikel - [Claude in OpenCode: der Claude-Agent-Provider, API-Keys und die anderen Wege](https://balazscsorba.com/de/blog/claude-in-opencode) - [Claude Code Review ist allgemein verfügbar: wie das Review arbeitet und was es kostet](https://balazscsorba.com/de/blog/claude-code-review) - [Top 20 Wege, Tokens bei Coding-Agents zu sparen: rtk, lean-ctx, Serena und mehr, nach Belegen gerankt](https://balazscsorba.com/de/blog/token-saving-tools-coding-agents-top-20) - [Die Agentenschleife erklärt: wie Coding-Agenten laufen und wie man sie stoppt](https://balazscsorba.com/de/blog/agent-loop-explained) ## Klingt nach dem, was du suchst? Erzähl mir von deinem Projekt oder deiner Stelle – ich freue mich, von dir zu hören. [Kontakt aufnehmen](mailto:contact@balazscsorba.com) [Auf LinkedIn vernetzen](https://www.linkedin.com/in/balazs-csorba)