Erweiterung 1
Skills im Detail
Vertiefung zu Modul 8 · Achsen, Lebenszyklus, Muster
Was dieses Deck ergänzt
Modul 2 zeigt, dass es Skills gibt. Modul 8 zeigt, wie eine SKILL.md aussieht. Hier geht es um das, was danach kommt.
- Die Frontmatter-Felder sind vier Achsen — nicht vier Sorten Skill. Jede lässt sich unabhängig einstellen.
- Ein ausgelöster Skill bleibt im Kontext. Was das für lange Sitzungen bedeutet, ist der wichtigste Punkt des Decks.
- Es gibt Muster mit Namen — Checkliste, Feedback-Loop, Template, bedingter Ablauf.
- Und es gibt Fehler mit Namen. Der häufigste hat nichts mit dem Inhalt zu tun.
# Begleitprojekt: zehn laufende Skills
examples/agent-scaffolding/
.claude/skills/
summarizing-endpoints/ # Vorgabe
drafting-release-notes/ # nur Mensch
java-conventions/ # nur Modell
finding-validations/ # Fork
counting-endpoints/ # Skript
checking-conventions/ # Loop
helper/ # zieht nicht
... und drei weitere
Die vier Achsen
Wer löst aus, wo läuft es, was ist erlaubt, womit läuft es
Vier Achsen, nicht vier Sorten
Die Frontmatter-Felder sortieren sich nach vier Fragen. Ein Skill wird auf jeder Achse einzeln eingestellt — man wählt keinen Typ aus.
| Achse | Frage | Felder |
|---|
| Auslösung | Wer darf ihn starten? | disable-model-invocation · user-invocable · paths |
| Ort | Wo läuft er? | context · agent · background |
| Befugnis | Was darf er dabei? | allowed-tools · disallowed-tools · hooks |
| Ausstattung | Womit läuft er? | model · effort · shell |
Insgesamt 17 Felder, davon ist keines Pflicht. Empfohlen ist nur description — daran entscheidet sich, ob der Skill überhaupt gefunden wird.
checked am 2026-07-29 gegen code.claude.com/docs/en/skills
Achse 1 — wer löst aus
Zwei Felder, drei Zustände. Die Spalte, die überrascht, ist die rechte: die Auslösung entscheidet mit, was überhaupt im Kontext liegt.
| Frontmatter | Mensch | Modell | Was im Kontext liegt |
|---|
| (Vorgabe) | ja | ja | Beschreibung immer, voller Inhalt beim Auslösen |
disable-model-invocation: true | ja | nein | gar nichts, bis ein Mensch ihn ruft |
user-invocable: false | nein | ja | Beschreibung immer, voller Inhalt beim Auslösen |
Ein Skill mit disable-model-invocation kostet im Ruhezustand nichts. Genau das ist das Argument für /deploy, /commit, /release — Abläufe mit Seiteneffekt.
checked am 2026-07-29 gegen code.claude.com/docs/en/skills
Achse 2 — wo es läuft
context: fork macht den Skill-Inhalt zum Prompt eines Subagenten. Der sieht euren Gesprächsverlauf nicht — und sein Suchmüll landet nie bei euch.
agent: bestimmt die Umgebung. Explore ist lesend und lässt CLAUDE.md weg.background: ist standardmäßig true: das Ergebnis kommt als Benachrichtigung. false lässt den Zug warten.- Im Hintergrund gilt ein schmalerer Werkzeugsatz. Braucht der Ablauf mehr, muss
background: false stehen.
- Kein Checkpoint. Änderungen eines Hintergrund-Forks nimmt
/rewind nicht zurück — nur Git.
# finding-validations/SKILL.md
---
name: finding-validations
description: Findet alle Stellen, an
denen eine Buchung geprueft wird ...
context: fork
agent: Explore
background: false
---
# Der Rumpf IST die Aufgabe
Durchsuche dieses Repository ...
checked am 2026-07-29 gegen code.claude.com/docs/en/skills
Achse 3 und 4 — Befugnis und Ausstattung
allowed-tools ist eine Freigabe, keine Einschränkung. Es macht keinen Skill sicherer — es nimmt nur die Rückfrage weg.
- Gilt nur für den auslösenden Zug. Mit der nächsten Nachricht ist die Freigabe weg, der Skill-Inhalt bleibt.
- Alle anderen Werkzeuge bleiben aufrufbar — für sie gelten die normalen Permissions weiter.
- Einschränken geht mit
disallowed-tools — für die Dauer des Skills, auch nur bis zur nächsten Nachricht.
model, effort, shell gelten ebenfalls nur für den Zug und landen nicht in den Settings.
Bei eingecheckten Projekt-Skills greift allowed-tools erst nach dem Workspace-Trust-Dialog. Ein Skill kann sich selbst breite Werkzeugrechte einräumen — deshalb Projekt-Skills lesen, bevor man einem Repository vertraut.
checked am 2026-07-29 gegen code.claude.com/docs/en/permissions
Lebenszyklus im Kontext
Was bleibt, was verfällt, was die Verdichtung übrig lässt
Ein ausgelöster Skill bleibt
Der gerenderte Inhalt tritt als eine Nachricht in die Unterhaltung und bleibt dort für den Rest der Sitzung. Die Datei wird nie wieder gelesen.
- Schreibt Dauer-Anweisungen, keine Schritte. Was für die ganze Aufgabe gelten soll, muss so formuliert sein — ein „zuerst …, dann …" verpufft nach dem ersten Zug.
- Gleicher Inhalt, kein zweites Mal. Wird derselbe Skill erneut ausgelöst und ist der gerenderte Inhalt identisch, kommt nur ein Hinweis dazu.
- Anderer Inhalt, volle Kopie. Andere Argumente oder eine neue Ausgabe eines eingebetteten Kommandos hängen ihn komplett neu an.
Der Inhalt bleibt, die Rechte nicht. allowed-tools verfällt mit eurer nächsten Nachricht — der Skill steht dann noch im Kontext, seine Freigabe nicht mehr.
checked am 2026-07-29 gegen code.claude.com/docs/en/skills
Was die Verdichtung übrig lässt
Bei der automatischen Verdichtung werden ausgelöste Skills wieder angehängt — aber nur teilweise, und nicht alle.
- Je Skill die ersten 5.000 Token der jüngsten Ausführung.
- 25.000 Token für alle zusammen, aufgefüllt vom zuletzt ausgelösten rückwärts.
- Wer viele Skills benutzt hat, verliert die ältesten ganz. Nach der Verdichtung erneut auslösen stellt sie wieder her.
# Und die Skill-LISTE selbst kostet auch
skillListingBudgetFraction: 0.01
# 1 Prozent des Kontextfensters
skillListingMaxDescChars: 1536
# pro Skill, description + when_to_use
Budget gerissen = die am wenigsten
benutzten Skills verlieren ihre
Beschreibung und stehen nur noch
mit Namen da. Auslösbar bleiben sie
— aber das Modell sieht nicht mehr,
was sie tun.
checked am 2026-07-29 gegen code.claude.com/docs/en/settings
Eingebettete Kommandos
Ein Skill kann Shell-Kommandos ausführen, bevor das Modell etwas sieht. Die Ausgabe ersetzt den Platzhalter — das Modell bekommt Daten, nicht den Befehl.
- Ein Durchlauf. Ausgaben werden nicht erneut nach Platzhaltern durchsucht.
- Das Ausrufezeichen muss am Zeilenanfang oder nach einem Leerzeichen stehen. Sonst bleibt es wörtlicher Text und nichts läuft.
- Abschaltbar per Richtlinie mit
disableSkillShellExecution — gebündelte und verwaltete Skills sind ausgenommen.
# einzeilig, inline
- PR-Diff: !`gh pr diff`
# mehrzeilig: Codezaun mit !
```!
node --version
npm --version
git status --short
```
KEY=!`cmd` # laeuft NICHT
checked am 2026-07-29 gegen code.claude.com/docs/en/skills
Aufbau und Freiheitsgrade
Wie groß, wie tief, wie viel Vorschrift
Aufteilen, aber nur eine Ebene tief
Große Referenzdateien kosten nichts, solange sie nicht gelesen werden. Verschachtelte Verweise kosten Verlässlichkeit.
- Rumpf unter 500 Zeilen. Darüber aufteilen.
- Alle Verweise direkt aus der SKILL.md — genau eine Ebene. Bei tieferer Verschachtelung liest das Modell Zieldateien womöglich nur an und arbeitet mit Lücken.
- Referenzdateien über 100 Zeilen bekommen ein Inhaltsverzeichnis, damit der Umfang auch beim Anlesen sichtbar ist.
- Nach Domäne aufteilen, nicht nach
doc1, doc2.
# gut: eine Ebene
SKILL.md
reference/finance.md
reference/sales.md
examples.md
# schlecht: drei Ebenen
SKILL.md
overview.md
details.md
actual.md
Freiheitsgrade
Wie genau ein Skill vorschreibt, richtet sich nach der Zerbrechlichkeit der Aufgabe — nicht nach Geschmack.
- Hoch: Prosa. Mehrere Wege sind richtig, die Entscheidung hängt vom Kontext ab. Beispiel Code-Review.
- Mittel: Skript mit Parametern. Ein bevorzugtes Muster gibt es, Abweichung ist erlaubt.
- Niedrig: exakter Befehl. Zerbrechliche Abläufe mit fester Reihenfolge. Beispiel Datenbank-Migration: „genau dieses Kommando, keine zusätzlichen Flags".
Das Bild aus der Doku: eine schmale Brücke mit Abgründen braucht ein Geländer und genaue Anweisungen. Ein offenes Feld ohne Hindernisse braucht eine Richtung und Vertrauen.
Muster, die tragen
Checkliste, Feedback-Loop, Template, bedingter Ablauf
Workflow mit Checkliste
Bei mehrschrittigen Abläufen wird die Checkliste in die Antwort kopiert und abgehakt. Das hält den Ablauf zusammen — und macht ihn für euch prüfbar.
- Klare Schritte verhindern, dass Prüfschritte übersprungen werden. Das ist der eigentliche Zweck, nicht die Optik.
- Funktioniert auch ohne Code — das Doku-Beispiel ist eine Recherche-Synthese mit fünf Schritten.
- Ihr seht den Fortschritt und könnt eingreifen, bevor der letzte Schritt läuft.
## checking-conventions/SKILL.md
Uebertrage diese Checkliste und
hake sie ab:
```
Fortschritt:
- [ ] Schritt 1: Pruefer laufen lassen
- [ ] Schritt 2: Verstoesse beheben
- [ ] Schritt 3: Pruefer erneut
- [ ] Schritt 4: erst weiter, wenn gruen
```
Der Feedback-Loop
Prüfen, beheben, erneut prüfen — und erst weitermachen, wenn es grün ist. Das ist das Muster mit dem größten Qualitätsgewinn pro Zeile Skill.
- Der Prüfer ist die Wahrheit, nicht die Einschätzung des Modells. Ein Skript, ein Exit-Code.
- Die Abbruchbedingung muss dastehen. Ohne „erst wenn 0 Verstöße" endet der Loop nach einem Durchlauf.
- Meldungen ausführlich halten — Datei, Zeile, erwartete Form. Wer nur „ungültig" meldet, erzwingt Raten.
- Auch ohne Code möglich: dann ist eine Stilrichtlinie der Prüfer und das Modell vergleicht.
$ validate-conventions.py src/main/java
FEHL Booking.java:18 Geldbetrag als
'double' deklariert: 'price'.
Erwartet: 'private BigDecimal price;'
plus Import 'java.math.BigDecimal'.
Getter und Setter mitziehen.
FEHL BookingService.java:16 Ausgabe
ueber 'System.out' in src/main.
2 Verstoesse # Exit 1
Template und bedingter Ablauf
Zwei kleinere Muster: eine feste Ausgabeform, wenn die Form zählt — und ein Entscheidungspunkt, wenn zwei Wege möglich sind.
- Template streng oder flexibel. „Benutze genau diese Struktur" für Berichte und Datenformate; „das ist ein sinnvoller Standard" da, wo Anpassung hilft.
- Bedingter Ablauf trennt am Anfang und schickt in genau einen Zweig. Wichtig: die Zweige in eigene Dateien, dann wird nur der zutreffende gelesen.
- Beispielpaare aus Eingabe und Ausgabe wirken stärker als jede Beschreibung des gewünschten Stils.
# changing-endpoints/SKILL.md
Schritt 1: Art der Aenderung bestimmen
- Neuer Endpunkt: lies create.md
- Bestehender: lies edit.md
Bist du unsicher, pruefe mit Grep, ob
der Pfad schon vorkommt.
# nur EINE der beiden Dateien
# landet im Kontext
Code und Anti-Patterns
Mitgelieferte Skripte — und warum ein Skill nicht zieht
Mitgelieferte Skripte
Ein fertiges Skript ist verlässlicher als erzeugter Code, kostet keine Token für die Erzeugung und liefert jedes Mal dasselbe.
- Lösen statt weiterreichen. Fehler im Skript behandeln, nicht dem Modell überlassen.
- Keine unbegründeten Konstanten.
TIMEOUT = 47 — warum 47? Wenn ihr es nicht wisst, weiß es das Modell auch nicht.
- Sagt, ob ausführen oder lesen. „Führe
x.py aus" gegen „siehe x.py für den Algorithmus" — das ist ein Unterschied.
- Plan, prüfen, ausführen bei Stapel- und riskanten Änderungen: erst eine prüfbare Zwischendatei, dann anwenden.
# Die Freigabe an der richtigen Stelle
---
allowed-tools: Bash(${CLAUDE_SKILL_DIR}
/scripts/check.py *)
---
Fuehre ${CLAUDE_SKILL_DIR}/scripts
/check.py aus.
# DIESELBE Variable an BEIDEN Stellen
# => Regel passt auf den Befehl
# => kein Freigabedialog
checked am 2026-07-29 gegen code.claude.com/docs/en/skills
Anti-Patterns
Sieben Fehler mit Namen. Sie stehen alle in der Doku — und alle sieben stecken absichtlich im Skill helper des Begleitprojekts.
| Fehler | Warum er schadet |
|---|
| Vage Beschreibung | der Skill wird nicht gefunden. Der einzige, der ihn unsichtbar macht. |
| Verschachtelte Verweise | Zieldateien werden nur angelesen, Information fehlt |
| Windows-Pfade mit Backslash | funktioniert auf keinem Unix-System |
| Viele Optionen ohne Vorgabe | das Modell wählt beliebig statt richtig |
| Zeitabhängige Angaben | veraltet zwangsläufig. Altes in einen eigenen Abschnitt |
| Unbegründete Konstanten | niemand kann den Wert anpassen, auch das Modell nicht |
| Wechselnde Begriffe | „Feld", „Box", „Element" für dasselbe — erschwert das Befolgen |
Warum der Skill nicht zieht
Fast immer liegt es an description und name — nicht am Inhalt. Die Auswahl trifft das Modell allein anhand dieser zwei Zeilen.
- Was er tut UND wann er anzuwenden ist gehören beide in die Beschreibung. „Helps with code" trifft auf alles zu und damit auf nichts.
- Dritte Person. Die Beschreibung landet im System-Prompt; „ich kann dir helfen" stört die Auswahl.
- Auslösende Begriffe nennen — die Wörter, die eure Leute wirklich tippen.
- Namen in Verlaufsform:
processing-pdfs, nicht helper, utils, tools.
Coordinator Mode ist keine Skill-Variante, sondern eine Umgebung: ein Skill mit disable-model-invocation läuft dort nicht. Der Coordinator lädt keine Skill-Inhalte, und Worker dürfen ihn nicht aufrufen.
checked am 2026-07-29 gegen Claude Code 2.1.220
Vor dem Teilen
Die Doku hat eine Checkliste. Das ist der Rest des Decks in prüfbarer Form — und der Grund, ein verify.sh zu schreiben.
- Beschreibung nennt was und wann, mit den auslösenden Begriffen.
- Rumpf unter 500 Zeilen, Verweise eine Ebene tief, Beispiele konkret.
- Skripte behandeln Fehler, ohne Voodoo-Konstanten, mit Schrägstrichen im Pfad.
- Erst Evaluationen, dann Dokumentation — mindestens drei Fälle, an denen sich messen lässt, ob der Skill etwas verbessert.
- Eine Instanz baut, eine andere benutzt. Beobachtet wird die zweite: findet sie die Information, hält sie die Regeln ein?
# examples/agent-scaffolding/verify.sh
OK nur dokumentierte Felder
OK Verweise eine Ebene tief
OK Skripte ausfuehrbar
OK Pruefer meldet Verstoesse
# Was verify.sh NICHT kann:
ob der Skill im Gespraech zieht.
Das entscheidet das Modell an der
Beschreibung — und das kann nur
ein Mensch beobachten.
Erweiterung 1 in fünf Sätzen
Was von diesem Deck hängenbleiben soll.
- Vier Achsen, kein Typ. Wer löst aus, wo läuft es, was ist erlaubt, womit — jede Achse einzeln einstellbar.
- Ein ausgelöster Skill bleibt die ganze Sitzung im Kontext und wird nie neu gelesen. Dauer-Anweisungen schreiben, keine Schrittfolgen.
- Die Rechte verfallen, der Inhalt nicht.
allowed-tools gilt für einen Zug — und ist eine Freigabe, keine Einschränkung.
- Der Feedback-Loop bringt den größten Qualitätsgewinn, wenn der Prüfer ein Exit-Code ist und die Abbruchbedingung dasteht.
- Zieht ein Skill nicht, liegt es an der Beschreibung. Nicht am Inhalt, nicht an den Pfaden, nicht am Modell.
Glossar Glossar
Frontmatter
Der Kopfteil einer Datei zwischen zwei Zeilen aus drei Bindestrichen, in YAML geschrieben. Trägt die Einstellungen eines Skills, Subagenten oder einer Regel — nicht seinen Inhalt.
YAML (YAML Ain't Markup Language)
Textformat für Konfiguration, das Einrückung statt Klammern benutzt. Format des Frontmatter in Skills und Subagenten.
Progressive Disclosure
Aufbauprinzip für Skills: die SKILL.md ist ein Inhaltsverzeichnis, die Einzelheiten stehen in Begleitdateien und werden erst gelesen, wenn sie gebraucht werden. Ungelesene Dateien kosten keinen Kontext.
Coordinator Mode
Sitzungsmodus, in dem eine koordinierende Instanz Arbeit an Worker verteilt. Sie lädt selbst keine Skill-Inhalte; nur vom Menschen aufrufbare Skills sind dort nicht verwendbar.
Feedback-Loop
Ablaufmuster: prüfen, Fehler beheben, erneut prüfen, und erst bei bestandener Prüfung weitermachen. Der Prüfer ist ein Skript mit Exit-Code, nicht die Einschätzung des Modells.
© 2026 CGS IT Solutions GmbH
Alle Rechte vorbehalten
Diese Schulungsunterlagen sind urheberrechtlich geschützt. Vervielfältigung,
Weitergabe oder kommerzielle Nutzung — auch in Auszügen — nur mit
ausdrücklicher schriftlicher Genehmigung der CGS IT Solutions GmbH.
cgsit-claude-training · Erweiterung 1 · Skills · v0.10.0
