Konfiguration und mehrteilige Skills

Konfiguration und mehrteilige Skills

Wichtigste Erkenntnisse

• Jedes Frontmatter-Feld ist in Claude Code optional, und nur description wird empfohlen. allowed-tools und model gehören zu den nützlichsten Ergänzungen
• Eine gute Beschreibung beantwortet zwei Fragen: Was macht der Skill? Wann soll Claude ihn verwenden?
• allowed-tools genehmigt die aufgelisteten Tools vorab, solange der Skill aktiv ist, sodass Claude sie nutzen kann, ohne nachzufragen, und es schränkt Claude nicht auf diese Tools ein
• Progressive Offenlegung: Halte SKILL.md unter 500 Zeilen und verlinke auf unterstützende Dateien (Referenzen, Skripte, Assets), die Claude nur bei Bedarf liest
• Skripte werden ausgeführt, ohne ihren Inhalt in den Kontext zu laden — nur die Ausgabe verbraucht Tokens, was den Kontext effizient hält

Ein einfacher Skill funktioniert bereits mit nur einem Namen und einer Beschreibung, aber es gibt mehrere fortgeschrittene Techniken, die deine Skills in Claude Code deutlich effektiver machen können. Lass uns die wichtigsten Felder, bewährte Methoden für Beschreibungen, Tool-Berechtigungen und die Strukturierung größerer Skills durchgehen.

Skill-Metadatenfelder

Der offene Standard für Agent Skills definiert die Kernfelder im SKILL.md-Frontmatter, und Claude Code fügt viele eigene hinzu, wie zum Beispiel model. In Claude Code sind alle Felder optional, und nur description wird empfohlen. Diese vier sind ein guter Ausgangspunkt (die Frontmatter-Referenz listet den Rest auf):

• name (optional) — Identifiziert deinen Skill. Standardmäßig der Verzeichnisname. Wenn du den Skill zu Claude.ai oder der Claude API hochlädst, ist es erforderlich und auf Kleinbuchstaben, Zahlen und Bindestriche beschränkt, bis zu 64 Zeichen.
• description (empfohlen) — Teilt Claude mit, wann der Skill zu verwenden ist. Wenn du den Skill zu Claude.ai oder der Claude API hochlädst, ist es erforderlich und auf 1.024 Zeichen begrenzt. Dies ist das wichtigste Feld, weil Claude es für den Abgleich verwendet.
• allowed-tools (optional) — Genehmigt die aufgelisteten Tools vorab, sodass Claude sie nutzen kann, ohne um Erlaubnis zu fragen, solange der Skill aktiv ist.
• model (optional) — Gibt an, welches Claude-Modell für den Skill verwendet werden soll.

Effektive Beschreibungen schreiben

Sei bei deinen Anweisungen explizit. Wenn dir jemand sagen würde „deine Aufgabe ist es, bei Dokumenten zu helfen", wüsstest du nicht, was zu tun ist — und Claude denkt genauso.

Eine gute Beschreibung beantwortet zwei Fragen:

1. Was macht der Skill?
2. Wann soll Claude ihn verwenden?

Wenn dein Skill nicht auslöst, wenn du es erwartest, versuche, weitere Schlüsselwörter hinzuzufügen, die dem entsprechen, wie du deine Anfragen tatsächlich formulierst. Die Beschreibung ist das, was Claude verwendet, um zu entscheiden, ob ein Skill relevant ist, daher ist die Sprache entscheidend.

Tools mit allowed-tools vorab genehmigen

Manchmal verlässt sich ein Skill jedes Mal, wenn er ausgeführt wird, auf dieselbe Handvoll Tools, und du möchtest nicht jeden Aufruf manuell genehmigen. Das Feld allowed-tools genehmigt die aufgelisteten Tools vorab, sodass Claude sie ohne Erlaubnisaufforderung für den Rest des Zuges verwenden kann, der den Skill ausgelöst hat. Die Genehmigung erlischt, sobald du deine nächste Nachricht sendest.



In diesem Beispiel ist das Feld allowed-tools auf Read, Grep, Glob, Bash gesetzt. Wenn dieser Skill aktiv ist, kann Claude diese vier Tools verwenden, ohne um Erlaubnis zu fragen. Es verliert dadurch keinen Zugriff auf etwas anderes: Wenn die Anweisungen des Skills dazu führen, dass Claude eine Datei bearbeitet oder schreibt, läuft das wie bei jedem anderen Tool-Aufruf über deine normalen Berechtigungseinstellungen. Eine Warnung: Bash allein aufzulisten, genehmigt Shell-Befehle generell vorab, also reserviere das für Skills, denen du vertraust, oder grenze es auf ein Muster wie Bash(git status *) ein.

---
name: codebase-onboarding
description: Helps new developers understand the system works.
allowed-tools: Read, Grep, Glob, Bash
model: sonnet
---

Wenn du allowed-tools vollständig weglässt, wird nichts vorab genehmigt, und Claude verwendet für jedes Tool sein normales Berechtigungsmodell. Um das Gegenteil zu tun und Tools zu entziehen, während ein Skill aktiv ist, verwende ein separates Claude Code-Frontmatter-Feld, disallowed-tools, das die von dir aufgelisteten Tools aus der Menge entfernt, die Claude verwenden kann.

Progressive Offenlegung

Skills teilen sich Claudes Kontextfenster mit deiner Konversation. Wenn Claude einen Skill aktiviert, lädt es den Inhalt dieser SKILL.md in den Kontext. Aber manchmal benötigst du Referenzen, Beispiele oder Hilfsskripte, von denen der Skill abhängt.

Alles in eine einzige 2.000-Zeilen-Datei zu pressen, hat zwei Probleme: Es beansprucht viel Platz im Kontextfenster, und es macht keinen Spaß, es zu pflegen.

Progressive Offenlegung löst dieses Problem. Behalte die wesentlichen Anweisungen in SKILL.md und platziere detailliertes Referenzmaterial in separaten Dateien, die Claude nur bei Bedarf liest.

Der offene Standard schlägt vor, dein Skill-Verzeichnis wie folgt zu organisieren:

• scripts/ — Ausführbarer Code
• references/ — Zusätzliche Dokumentation
• assets/ — Bilder, Vorlagen oder andere Datendateien

Verlinke dann in SKILL.md mit klaren Anweisungen, wann sie zu laden sind, auf die unterstützenden Dateien:



In diesem Beispiel liest Claude architecture-guide.md nur, wenn jemand nach der Systemarchitektur fragt. Wenn jemand fragt, wo eine Komponente hinzugefügt werden soll, lädt es diese Datei nie. Es ist wie ein Inhaltsverzeichnis im Kontextfenster zu haben, statt des gesamten Dokuments.

Eine gute Faustregel: Halte SKILL.md unter 500 Zeilen. Wenn du das überschreitest, überlege, ob der Inhalt in separate Referenzdateien aufgeteilt werden sollte.

Skripte effizient nutzen

Skripte in deinem Skill-Verzeichnis können ausgeführt werden, ohne ihren Inhalt in den Kontext zu laden. Das Skript wird ausgeführt, und nur die Ausgabe verbraucht Tokens. Die wichtigste Anweisung, die du in deine SKILL.md aufnehmen solltest, ist, Claude zu sagen, das Skript auszuführen, nicht es zu lesen.

Dies ist besonders nützlich für:

• Umgebungsvalidierung
• Datentransformationen, die konsistent sein müssen
• Operationen, die als getesteter Code zuverlässiger sind als generierter Code

Reflexion zur Lektion

• Denke an einen Skill, den du entwickeln möchtest und der mehrere Dateien umfasst. Wie würdest du SKILL.md gegenüber den unterstützenden Referenzdateien strukturieren?
• Für einen Skill, den dein Team gemeinsam nutzt: Welche Tools würdest du mit allowed-tools vorab genehmigen, und bei welchen würdest du lieber möchten, dass Claude weiterhin nachfragt?

Was kommt als Nächstes

In der nächsten Lektion vergleichen wir Skills mit den anderen Möglichkeiten, Claude Code anzupassen — CLAUDE.md, Subagenten, Hooks und MCP-Server —, damit du für jede Situation das richtige Tool auswählen kannst.