Erweiterung 1
Skills im Detail
Vertiefung zu Modul 8 · Konfiguration, Lebenszyklus, Muster
Eine Zeile Frontmatter entscheidet das Verhalten
Vier Skills aus dem Begleitprojekt, jeder mit einer anderen Zeile im Frontmatter.
Links steht, was man hinschreibt — rechts, was man beobachten kann.
# laeuft in EIGENEM Kontext, Ergebnis
# kommt zurueck, Suchmuell bleibt drin
context: fork
agent: Explore
# nur der MENSCH darf starten
disable-model-invocation: true
# EINE Datei, zwei Zeilen: nur das MODELL
# darf, und nur bei passenden Dateien
user-invocable: false
paths: ["src/**/*.java"]
# SCRIPT runs without a permission prompt
allowed-tools: Bash(${CLAUDE_SKILL_DIR}
/scripts/count-endpoints.py *)
- Fork —
finding-validations. /context vor und nach dem Lauf: die durchsuchten Dateien fehlen im Hauptkontext.
- Nur Mensch —
drafting-release-notes. Für alles mit Seiteneffekt.
- Nur Modell und pfadgebunden —
java-conventions, eine Datei mit beiden Zeilen. Hintergrundwissen, das als Kommando keinen Sinn ergibt und erst beim Anfassen einer Java-Datei lädt.
- Skript —
counting-endpoints. Läuft ohne Rückfrage; Zeile entfernen und es wird gefragt.
checked am 2026-07-29 gegen docs/en/skills
Konfiguration
Parameter nach Aufgabengebiet
Parameter nach Aufgabengebiet
17 Felder, keines Pflicht.
Sortiert nach dem, was man erreichen will — nicht alphabetisch.
| Aufgabengebiet |
Felder |
| Gefunden werden | description · when_to_use · name |
| Auslösung steuern | disable-model-invocation · user-invocable · paths |
| Anderswo laufen lassen | context: fork · agent · background |
| Werkzeuge freigeben | allowed-tools · disallowed-tools |
| Verhalten erzwingen | hooks |
| Argumente annehmen | argument-hint · arguments |
| Ausstattung wählen | model · effort · shell |
Empfohlen ist genau ein Feld: description.
Daran entscheidet sich, ob der Skill überhaupt gefunden wird — alles andere regelt nur, was danach passiert.
checked am 2026-07-29 gegen docs/en/skills
Wer darf auslösen
Zwei Felder, drei Zustände.
Die rechte Spalte überrascht: die Auslösung entscheidet mit, was überhaupt im Kontext liegt.
(nichts gesetzt)
Mensch Modell Beschreibung immer
voller Inhalt beim Auslösen
disable-model-invocation
Mensch Modell gar nichts,
bis ein Mensch ihn ruft
user-invocable: false
Mensch Modell Beschreibung immer
voller Inhalt beim Auslösen
Frontmatterwas im Kontext liegt
Ein Skill mit disable-model-invocation kostet im Ruhezustand nichts — nicht einmal seine Beschreibung liegt im Kontext.
Genau das ist das Argument für /deploy, /commit, /release.
checked am 2026-07-29 gegen docs/en/skills
allowed-tools ist eine Freigabe
Es macht keinen Skill sicherer — es nimmt die Rückfrage weg.
Und es gilt nur für den auslösenden Zug.
# counting-endpoints/SKILL.md
---
allowed-tools: Bash(${CLAUDE_SKILL_DIR}
/scripts/count-endpoints.py *)
---
Fuehre ${CLAUDE_SKILL_DIR}/scripts
/count-endpoints.py aus.
# DIESELBE Variable an BEIDEN Stellen:
# die Regel passt auf den Befehl,
# so: no permission prompt.
- 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.
- Einschränken geht mit
disallowed-tools, ebenfalls nur bis zur nächsten Nachricht.
- Braucht Version 2.1.129 oder neuer — davor bleibt die Regel eine wörtliche Zeichenkette und passt nie.
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 docs/permissions
Lebenszyklus im Kontext
Was bleibt, was verfällt, was /compact übrig lässt
Ein Skill bleibt in der Sitzung
Der ausgelöste Inhalt tritt als eine Nachricht in die Unterhaltung und bleibt die ganze Sitzung.
Die Datei wird nie wieder gelesen.
- Schreibt Dauer-Anweisungen, keine Schrittfolgen. Ein „zuerst …, dann …" verpufft nach dem ersten Zug.
- Der Inhalt bleibt, die Rechte nicht.
allowed-tools verfällt mit eurer nächsten Nachricht.
- Gleicher Inhalt, kein zweites Mal. Nur bei anderen Argumenten oder neuer Skript-Ausgabe wird er voll neu angehängt.
- Nach
/compact zurückgeholt — aber gekürzt, siehe rechts.
die Unterhaltung, von oben nach unten
1System · CLAUDE.md
2eure Nachricht
3Skill-Inhalt — tritt einmal ein
4Antwort, Tool-Calls, …
…der Skill-Inhalt bleibt oben stehen
nnach /compact: erste 5.000 Token je Skill, 25.000 gesamt, jüngster zuerst
Systemder SkillVerlauf
checked am 2026-07-29 gegen docs/en/skills
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.
# einzeilig, inline
- PR-Diff: !`gh pr diff`
# mehrzeilig: Code Fence mit !
```!
git status --short
git log --oneline -5
```
KEY=!`cmd` # laeuft NICHT --
# das ! muss am Zeilenanfang oder
# nach einem Leerzeichen stehen
- Ein Durchlauf. Ausgaben werden nicht erneut nach Platzhaltern durchsucht.
- Das ist Vorverarbeitung, nicht etwas, das das Modell ausführt und freigeben müsste.
- Abschaltbar per Richtlinie mit
disableSkillShellExecution — gebündelte Skills sind ausgenommen.
checked am 2026-07-29 gegen 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.
eine Ebene
SKILL.md
finance.md
sales.md
examples.md
drei Ebenen
SKILL.md
overview.md
details.md
actual.md
hier steht es wirklich
der RumpfReferenzdatei
- Rumpf unter 500 Zeilen, darüber aufteilen.
- Alle Verweise direkt aus der SKILL.md. Bei tieferer Verschachtelung liest das Modell Zieldateien womöglich nur an und arbeitet mit Lücken.
- Referenzdateien über 100 Zeilen bekommen ein Inhaltsverzeichnis.
- Nach Domäne aufteilen, nicht nach
doc1, doc2.
Freiheitsgrade
Wie genau ein Skill vorschreibt, richtet sich nach der Zerbrechlichkeit der Aufgabe — nicht nach Geschmack.
# HOCH -- viele Wege sind richtig
1. Struktur des Codes ansehen
2. Auf Randfaelle pruefen
3. Lesbarkeit vorschlagen
# MITTEL -- Muster mit Parametern
def report(data, format="markdown",
charts=True):
# NIEDRIG -- genau dieser Befehl
python scripts/migrate.py \
--verify --backup
Keine zusaetzlichen Flags.
- Hoch: Entscheidung hängt vom Kontext ab. Beispiel Code-Review.
- Mittel: ein bevorzugtes Muster gibt es, Abweichung ist erlaubt.
- Niedrig: zerbrechlich, feste Reihenfolge. Beispiel Datenbank-Migration.
Das Bild: schmale Brücke mit Abgründen braucht ein Geländer, offenes Feld braucht eine Richtung.
Muster, die tragen
Checkliste, Feedback-Loop, bedingter Ablauf, Template
Workflow mit Checkliste
Bei mehrschrittigen Abläufen wird die Checkliste in die Antwort kopiert und abgehakt.
Das verhindert, dass Prüfschritte übersprungen werden.
## checking-conventions/SKILL.md
Uebertrage diese Checkliste und
hake sie ab:
```
Fortschritt:
- [ ] 1: Pruefer laufen lassen
- [ ] 2: Verstoesse beheben
- [ ] 3: Pruefer erneut
- [ ] 4: weiter, wenn gruen
```
- Der Zweck ist nicht die Optik, sondern dass kein Schritt entfällt.
- Funktioniert auch ohne Code — das Doku-Beispiel ist eine Recherche-Synthese in fünf Schritten.
- Ihr seht den Fortschritt und könnt eingreifen, bevor der letzte Schritt läuft.
Der Feedback-Loop
Das Muster der Doku in drei Worten: prüfen, beheben, wiederholen.
Es steht im Rumpf des Skills — als nummerierte Schritte mit einer eigenen Abbruchbedingung.
bis 0 Verstöße
Prüfer laufen lassen
Datei, Zeile,
erwartete Form
EINEN beheben
zurück — Prüfer erneut
Exit 0 — erst jetzt weiter
mvn -o test
Schrittdie Schleife
- Schritt 3 ist der Loop. Ohne ihn ist das eine Liste, die einmal durchläuft — der häufigste Fehler beim Nachbauen.
- Der Prüfer ist die Wahrheit, nicht die Einschätzung des Modells. Ein Skript, ein Exit-Code.
- Er muss kein Skript sein. Auch eine Stilrichtlinie taugt als Prüfer — dann liest und vergleicht das Modell. Das Muster bleibt dasselbe.
- Meldungen ausführlich halten — Datei, Zeile, erwartete Form. Wer nur „ungültig" meldet, erzwingt Raten.
Im Begleitprojekt belegt: erster Lauf 2 Verstöße, Exit 1 — nach zwei Änderungen 0 Verstöße, Exit 0.
Der Skill meldet am Ende, wie viele Durchläufe er gebraucht hat.
checked am 2026-07-30 gegen best-practices
Bedingter Ablauf
Zwei Wege, ein Entscheidungspunkt am Anfang — und die Zweige in eigenen Dateien.
Nur der zutreffende wird gelesen.
# changing-endpoints/SKILL.md
Schritt 1: Art der Aenderung
bestimmen.
- Neuer Endpunkt: lies create.md
- Bestehender: lies edit.md
Unsicher? Pruefe mit Grep, ob der
Pfad schon vorkommt.
Schritt 2: dem Ablauf der
gelesenen Datei folgen.
- Der Gewinn ist Kontext, nicht Ordnung: wer beide Zweige in die SKILL.md schreibt, lädt immer beide.
- Der Entscheidungspunkt braucht ein Kriterium, nicht nur eine Frage — hier der Grep.
- Im Transkript ist sichtbar, welche Datei gelesen wurde. Das ist der Beobachtungsweg im Begleitprojekt.
Vorlage und Ergebnis
Wenn die Form zählt, gibt man sie vor.
Links die Vorlage im Skill, rechts was dabei herauskommt.
# reviewing-with-template/SKILL.md
Benutze genau diese Vorlage.
Keine zusaetzlichen Abschnitte.
```markdown
# Review: <Dateiname>
## Einschaetzung
<ein Satz>
## Befunde
| Zeile | Schwere | Befund |
## Was gut ist
- <ein bis drei Punkte>
```
Schwere: kritisch | warnung | hinweis
Nichts anderes.
# und so sieht die Antwort aus
# Review: Booking.java
## Einschaetzung
Fachlich klar, aber der Geldbetrag
ist als Gleitkommazahl abgelegt.
## Befunde
| 18 | kritisch | double fuer Geld |
| 30 | hinweis | Setter ohne Pruefung |
## Was gut ist
- Namen sagen, was gemeint ist
- keine Fachlogik in der Resource
Streng formulieren, wenn die Form weiterverarbeitet wird („benutze genau diese Vorlage").
Weich formulieren, wenn Anpassung hilft („das ist ein sinnvoller Standard, urteile nach Lage").
Code und Anti-Patterns
Mitgelieferte Skripte — und warum ein Skill nicht zieht
Mitgelieferte Skripte
Eine Ausnahme, die das Skript nach oben durchlässt, wird zum Rätsel für das Modell.
Behandelt sie da, wo ihr wisst, was sie bedeutet.
# schlecht: reicht die Ausnahme weiter
def pruefe(pfad):
# let the agent figure it out
return open(pfad).read()
# Das Modell sieht dann nur:
PermissionError: [Errno 13] ...
# und muss raten, ob das ein Befund,
# ein Aufruffehler oder ein Bug ist.
# gut: die Ausnahme WIRD ein Befund
try:
zeilen = pfad.read_text().splitlines()
except OSError as e:
return [{"regel": "unlesbar",
"datei": str(pfad),
"erwartet": str(e)}]
- Eine unlesbare Datei ist ein Befund, kein Absturz. Sie landet in derselben Struktur wie jeder andere Befund — der Aufrufer braucht keinen Sonderfall.
- Keine unbegründeten Konstanten.
TIMEOUT = 47 — wenn ihr den Wert nicht kennt, kennt das Modell ihn auch nicht.
- Sagt, ob ausführen oder lesen. „Führe
x.py aus" gegen „siehe x.py für den Algorithmus".
- Plan, prüfen, ausführen bei Stapel- und riskanten Änderungen: erst eine prüfbare Zwischendatei.
checked am 2026-07-30 gegen best-practices
Rückgabe-Vertrag und Aufrufer
Ein Skript, das ein Skill aufruft, braucht eine zugesagte Rückgabe.
Sonst muss der Aufrufer Text lesen und rät bei jeder Änderung neu.
# tools/check-conventions.py --json
{
"gate": "conventions",
"exit": 1, # 0 sauber 1 Verstoss 2 Aufruf
"geprueft": 26,
"verstoesse": [{
"regel": "mandant",
"datei": "...SeminarRepository.java",
"zeile": 19,
"gefunden": "list(\"startDate > ?1\"...)",
"erwartet": "der Mandant gehoert in
JEDE Abfrage"
}]
}
# auch bei exit 2 gueltiges JSON,
# dann mit Feld "fehler"
# checking-conventions/SKILL.md
allowed-tools: Bash(python3 tools
/check-conventions.py *)
---
1. `python3 tools/check-conventions.py
--json`
2. Bei "exit": 2 ist es ein Aufruf-
fehler: melde `fehler`, halte an.
3. Arbeite `verstoesse[]` ab. Je Eintrag:
- oeffne `datei` an `zeile`
- vergleiche mit `gefunden`
- setze `erwartet` um
- nach `regel` unterscheiden:
mandant | geld | logging
4. Erst weiter, wenn "exit": 0.
Der Vertrag steht im Kopfkommentar des Skripts — dort sucht ihn, wer ihn braucht.
Beides liegt echt im Übungsprojekt cgsit-claude-training-ext; alle drei Exit-Codes sind dort durchgespielt.
checked am 2026-07-30 gegen ext-Uebungsprojekt
Anti-Patterns
Sieben Fehler mit Namen.
Alle sieben stecken absichtlich im Skill helper des Begleitprojekts — er ist das Material der Übung.
| 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.
# zieht nicht
description: Helps with code.
# zieht unzuverlaessig -- sagt WAS,
# aber nicht WANN
description: Prueft die Java-
Konventionen dieses Repositories.
# zieht
description: Prueft die Java-
Konventionen und behebt Verstoesse
gegen die Regeln zu Geldbetraegen
und Logging. Zu benutzen bei
Aufraeumarbeiten, vor einem Commit,
oder wenn nach Konventionen gefragt
wird.
- Was er tut UND wann er anzuwenden ist. Der zweite Satz entscheidet.
- Dritte Person. Die Beschreibung landet im System-Prompt; „ich kann dir helfen" stört die Auswahl.
- Die Wörter nennen, die eure Leute tippen — nicht nur die Fachsprache des Skills.
- Namen in Verlaufsform:
processing-pdfs, nicht helper, utils, tools.
checked am 2026-07-29 gegen ext-01-Uebung
Vor dem Teilen
Die Checkliste der Doku, in prüfbarer Form — und der Grund, ein verify.sh zu schreiben statt eine Liste abzuhaken.
$ bash examples/agent-scaffolding/verify.sh
OK nur dokumentierte Frontmatter-Felder
OK Verweise eine Ebene tief
OK keine Windows-Pfade
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.
- Maschinell prüfbar: Feldnamen, Verweistiefe, Pfadform, Ausführbarkeit, Rumpflänge.
- Nur beobachtbar: ob die Beschreibung greift. Dafür eine Aufgabe in Alltagssprache, ohne den Namen zu nennen.
- Erst Evaluationen, dann Dokumentation — drei Fälle, an denen messbar ist, ob der Skill etwas verbessert.
- Eine Instanz baut, eine andere benutzt. Beobachtet wird die zweite.
Erweiterung 1 in fünf Sätzen
Was von diesem Deck hängenbleiben soll.
- Eine Zeile Frontmatter ändert das Verhalten. Wer auslöst, wo es läuft, was erlaubt ist — alles 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.
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.
Exit-Code
Die Zahl, mit der ein Programm endet: 0 heißt in Ordnung, alles andere heißt Fehler. Sie ist das Signal, an dem ein Skill erkennt, ob er noch einen Durchlauf braucht.
© 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.11.5
