Agent Skills

Ein Skill bündelt eine Anleitung, die du sonst immer wieder in den Chat kopieren würdest, in einer Datei. Gegenüber einem Prompt-Schnipsel gewinnst du drei Dinge: Der Rumpf belegt erst dann Kontext, wenn der Skill tatsächlich läuft; er kann Live-Daten aus der Shell mitbringen; und du legst fest, ob du ihn aufrufst, Claude oder beide. Dieses Modul geht die Bausteine der Reihe nach durch — vom Ladeverhalten über das Frontmatter bis zu den Skills, die schon an Bord sind.

Was Claude wann von einem Skill sieht

Claude sieht zunächst nur die Kurzfassung: Name und description jedes Skills stehen in einer Auflistung, die in jedem Turn mitreist. Erst beim Aufruf wandert der gerenderte Inhalt von SKILL.md als eine einzelne Nachricht in die Konversation — und bleibt dort für den Rest der Session stehen. Weitere Dateien aus dem Skill-Verzeichnis liest Claude einzeln nach, wenn es sie braucht.

Deshalb kostet ein großer Skill-Bestand wenig: Dauerhaft im Kontext liegt die Auflistung, nicht der Inhalt. Zwei Folgen lohnt es sich zu merken. Ab dem Aufruf zählt jede Zeile des Rumpfs wiederkehrend mit — halte ihn knapp und schreibe, was zu tun ist, statt zu erzählen, warum. Und Claude liest die Datei später nicht erneut: Was während der ganzen Aufgabe gelten soll, gehört als dauerhafte Anweisung hinein, nicht als Einmal-Schritt.

Wo die Datei liegt, entscheidet, wer den Skill hat. ~/.claude/skills/<name>/SKILL.md gilt in allen deinen Projekten, .claude/skills/<name>/SKILL.md nur in diesem einen und wandert per git mit; dazu kommen die Ebene der verwalteten Einstellungen für eine ganze Organisation und Skills aus Plugins. Tragen zwei Skills denselben Namen, schlägt die Organisationsebene die persönliche und die persönliche die des Projekts — und ein Skill auf einer dieser Ebenen ersetzt auch einen gleichnamigen mitgelieferten. Plugin-Skills stehen unter plugin-name:skill-name und können deshalb gar nicht kollidieren.

Unterhalb deines Arbeitsverzeichnisses sucht Claude zusätzlich in verschachtelten .claude/skills/ -Ordnern: Bearbeitet es eine Datei in packages/frontend/, stehen auch die Skills aus packages/frontend/.claude/skills/ bereit. Genauso werden die Ordner oberhalb des Startverzeichnisses bis zur Repository-Wurzel eingelesen, sodass ein Start im Unterordner die Skills der Wurzel nicht verliert. Kollidiert ein verschachtelter Name, bleiben beide Varianten erreichbar — die verschachtelte unter ihrem verzeichnis-qualifizierten Namen, etwa apps/web:deploy.

.claude/skills/code-review/
├── SKILL.md              # Instructions (required)
├── templates/
│   └── review-checklist.md
└── scripts/
    └── analyze-metrics.py

Die Beschreibung entscheidet über den Aufruf

Die description ist das Feld, an dem alles hängt: Claude entscheidet allein danach, ob ein Skill zur Anfrage passt. Ein Satz wie „hilft beim Programmieren“ trägt kein Signal und löst nie aus. Brauchbar wird es, sobald Tätigkeit, Gegenstand und Anlass darin vorkommen:

---
name: security-review
description: Scan code for security vulnerabilities including injection flaws, authentication issues, and data exposure. Use when reviewing code changes, preparing a PR, or when the user mentions security, vulnerabilities, or audit.
---

Nenne also die Tätigkeit („prüfen“, „erzeugen“, „analysieren“), das Fachgebiet und die Formulierungen, bei denen der Skill greifen soll. Für den Anlass gibt es ein eigenes Feld: when_to_use wird in der Auflistung an die description angehängt. Beide zusammen schneidet Claude Code pro Eintrag bei 1.536 Zeichen ab — einstellbar über skillListingMaxDescChars —, also gehört der Hauptfall nach vorn und der Rest der Trigger-Formulierungen nach when_to_use:

---
name: security-review
description: Scan code for security vulnerabilities including injection flaws, authentication issues, and data exposure.
when_to_use: When reviewing code changes, preparing a PR, or when the user mentions security, vulnerabilities, or audit.
---

Für die gesamte Auflistung reserviert Claude Code standardmäßig 1 % des Context Windows. Anheben kannst du das über skillListingBudgetFraction (etwa 0.02 für 2 %) oder über SLASH_COMMAND_TOOL_CHAR_BUDGET als feste Zeichenzahl. Reicht das Budget nicht, fallen bei den am wenigsten genutzten Skills die Beschreibungen weg und nur die Namen bleiben stehen: Aufrufen kann Claude sie weiter, sehen, wofür sie gut sind, nicht mehr. /doctor schätzt die Kosten der Auflistung gegen das Budget und nennt die größten Posten.

Umfangreiches Material legst du als eigene Dateien daneben und verweist aus SKILL.md mit relativen Pfaden darauf. So bleibt der Rumpf schlank, und der lange Rest wird nur gelesen, wenn er gebraucht wird:

For the full review checklist, see [templates/review-checklist.md](templates/review-checklist.md).

Damit Claude einschätzen kann, wann sich welche Datei lohnt, schreibe zu jedem Verweis dazu, was darin steht. Als Faustregel bleibt SKILL.md unter 500 Zeilen; ausführliche Referenz gehört in Nachbardateien, ausführbare Helfer in ein scripts/ -Unterverzeichnis.

Live-Kontext mitgeben, den Aufruf steuern

Mit !command holst du Live-Daten in den Skill: Claude Code führt den Befehl aus, bevor der Inhalt überhaupt abgeschickt wird, und setzt die Ausgabe an die Stelle des Platzhalters. Claude bekommt also Daten zu sehen, nicht den Befehl. Für mehrzeilige Aufrufe gibt es die Blockform, eingeleitet mit ```!. Die Ersetzung läuft genau einmal über die Originaldatei — eine Ausgabe, die selbst wie ein Platzhalter aussieht, wird nicht noch einmal ausgewertet:

---
name: pr-summary
description: Summarize pull request changes. Use when asked to review or summarize a PR.
context: fork
agent: Explore
---

## PR context
- Diff: !`gh pr diff`
- Comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

Summarize the intent and key changes in this pull request.

Welche Shell dabei zum Einsatz kommt, steuert shell: bash ist der Standard, powershell die Alternative. Sie greift, wenn das PowerShell-Tool aktiv ist — unter Windows ohne Git Bash von sich aus, sonst über CLAUDE_CODE_USE_POWERSHELL_TOOL=1, was unter Linux und macOS zusätzlich pwsh im PATH voraussetzt:

---
name: windows-helper
description: Manage Windows services and configurations
shell: powershell
---

Zwei Felder regeln, wer einen Skill starten darf. disable-model-invocation: true nimmt Claude die automatische Auswahl weg: Über /skill-name bleibt der Skill erreichbar, sein Beschreibungstext verschwindet dafür aus dem Kontext. Das ist die richtige Wahl für alles mit Außenwirkung — Deploys, Pushes, versandte Nachrichten. Umgekehrt verbirgt user-invocable: false den Skill im / -Menü, lässt Claude ihn aber weiterhin von selbst laden; gedacht für Hintergrundwissen, das als Befehl keinen Sinn ergibt.

paths: nimmt eine Glob-Liste und begrenzt damit, wann ein Skill automatisch lädt: nur wenn Claude mit Dateien arbeitet, die zu einem der Muster passen. So bleiben projektspezifische Skills aus Sessions heraus, in die sie nicht gehören:

---
name: api-generator
description: Generate REST API endpoints from schema definitions.
paths: ["src/**/*.ts", "tests/**"]
---

effort legt die Reasoning-Tiefe fest, solange der Skill aktiv ist, und überschreibt dafür die Stufe der Session. Möglich sind low, medium, high, xhigh und max; welche Stufen es wirklich gibt, hängt am Modell, und max gilt nur für die laufende Session. Ohne Angabe erbt der Skill die Session-Stufe:

---
name: security-review
description: Scan code for security vulnerabilities.
effort: high
---

context: fork schickt den Skill in einen eigenen Subagent: Der Rumpf wird dort zum Auftrag, die Konversationshistorie bleibt draußen, dein Hauptkontext bleibt frei. Welcher Agent-Typ übernimmt, sagt agent — Explore für reines Lesen, Plan für Entwürfe, general-purpose für alles, was den vollen Werkzeugkasten braucht; ohne Angabe wird general-purpose genommen. Der Fork läuft im Hintergrund und meldet sein Ergebnis, sobald er fertig ist; mit background: false wartet stattdessen der aufrufende Turn darauf. Ohne konkreten Auftrag im Rumpf ist ein Fork sinnlos — eine reine Konventionssammlung liefert dort nichts zurück.

model wählt für den Rest des laufenden Turns ein anderes Modell, ohne es in den Einstellungen zu verankern; beim nächsten Prompt gilt wieder das der Session. Erlaubt sind dieselben Werte wie bei /model, dazu inherit für „nichts ändern“:

---
name: deep-analysis
description: Thoroughly analyze the codebase for a specific pattern or issue
context: fork
agent: Explore
model: opus
disable-model-invocation: true
---

Analyze $ARGUMENTS across the entire codebase:
1. Use Glob and Grep to find all occurrences
2. Read each file and understand context
3. Summarize patterns, inconsistencies, and recommendations

Argumente übergeben, Tools vorab erlauben

Argumente erreichen einen Skill auf drei Wegen. $ARGUMENTS steht für alles, was hinter dem Namen kommt. $ARGUMENTS[0] und die Kurzform $0 greifen einzelne Positionen heraus, wobei mehrwortige Werte in Anführungszeichen zusammenbleiben. Und wer sprechende Namen will, deklariert sie im Frontmatter-Feld arguments; sie bilden in ihrer Reihenfolge auf die Positionen ab. Ersetzt wird alles, bevor der Prompt bei Claude landet. argument-hint zeigt im Slash-Menü, was der Skill erwartet:

---
name: review-pr
description: Review a GitHub PR by number
argument-hint: "<pr-number> <priority>"
allowed-tools: Bash(gh *), Read, Grep, Glob
---

Review PR #$0 with priority $1. Focus on security and performance.

Reference our standards in [standards/code-review.md](standards/code-review.md).

Aufruf /review-pr 456 high: $0 wird zu 456, $1 zu high. Eine Position ohne Argument — etwa $2, wenn nur zwei Werte übergeben wurden — bleibt unverändert im Text stehen; ein benannter Platzhalter ohne Wert wird zur leeren Zeichenkette.

allowed-tools erlaubt die genannten Tools ohne Rückfrage, und zwar für genau den Turn, der den Skill aufruft. Mit deiner nächsten Nachricht verfällt die Erlaubnis, obwohl der Skill-Inhalt im Kontext bleibt; ein erneuter Aufruf setzt sie wieder. Eingeschränkt wird dabei nichts — alle übrigen Tools bleiben verfügbar und richten sich weiter nach deinen Berechtigungen. Wer Tools wegnehmen will, listet sie unter disallowed-tools. Bei Skills, die im Projekt liegen, greift beides erst, wenn du dem Ordner vertraut hast: Lies sie vorher.

Neben den Positionen kennt Claude Code feste Platzhalter: ${CLAUDE_SESSION_ID} für die laufende Session, ${CLAUDE_EFFORT} für die aktive Effort-Stufe, ${CLAUDE_SKILL_DIR} für das Verzeichnis der SKILL.md und ${CLAUDE_PROJECT_DIR} für die Projektwurzel. Die letzten beiden ersetzt Claude Code auch in den Bash-Regeln von allowed-tools — derselbe Platzhalter an beiden Stellen lässt ein mitgeliefertes Skript ohne Rückfrage laufen.

Ältere Befehlsdateien unter .claude/commands/*.md funktionieren unverändert weiter und verstehen dasselbe Frontmatter. Empfohlen sind trotzdem Skills, weil nur sie ein Verzeichnis mit Begleitdateien mitbringen. Gibt es beides unter demselben Namen, gewinnt der Skill.

Sichtbarkeit aus den Einstellungen setzen

Manche Skills willst du zähmen, ohne ihre Datei anzufassen — etwa solche, die im Projekt-Repo liegen und allen gehören. Dafür gibt es skillOverrides in den Einstellungen: ein Eintrag je Skill-Name, der die Sichtbarkeit von außen setzt. Für Plugin-Skills gilt das nicht, die regelst du über /plugin. Schreiben musst du die Einträge nicht selbst — im /skills -Menü wählst du einen Skill aus, schaltest mit Space durch die Zustände und sicherst mit Enter nach .claude/settings.local.json:

{
  "skillOverrides": {
    "legacy-context": "name-only",
    "deploy": "off"
  }
}

Vier Werte sind möglich. "on" ist der Normalfall und listet Name samt Beschreibung. "name-only" lässt nur den Namen stehen — aufrufbar bleibt der Skill, aber Claude sieht nicht mehr, wofür er gut ist; das ist der sparsame Weg, Budget freizuräumen. "user-invocable-only" nimmt ihn Claude ganz aus der Auflistung und hält ihn dir im / -Menü offen, dort beschriftet als user-only. "off" verbirgt ihn überall. Ein Skill ohne Eintrag gilt als "on".

Was schon mitkommt

Ein Satz Skills ist bereits an Bord und braucht keine Installation, darunter /doctor, /code-review, /batch, /debug, /loop und /claude-api. Sie sind prompt-basiert: Sie geben Claude eine ausführliche Anleitung und lassen es die Arbeit mit den eigenen Tools erledigen — anders als die meisten eingebauten Befehle, die feste Logik ausführen. Drei davon arbeiten zusammen und brauchen mindestens v2.1.145: /run, /verify und /run-skill-generator starten deine App und bestätigen eine Änderung am laufenden Programm statt nur an Tests.

Ohne Vorbereitung leiten /run und /verify den Start aus dem Projekttyp ab — CLI, Server, TUI, browsergesteuert — und aus package.json, Makefile oder der README. Sobald mehr dazugehört als ein Standardstart, etwa eine Datenbank, eine env-Datei, eine grafische Sitzung oder ein mehrstufiger Build, wird diese Ableitung unzuverlässig. Dann lässt du /run-skill-generator einmal laufen: Es bringt die App aus einer sauberen Umgebung zum Laufen, hält Installationsbefehle, Umgebungsvariablen und Startskript fest und checkt das Ergebnis als Projekt-Skill unter .claude/skills/run-<name>/ ein. Danach folgen /run, /verify und jeder andere Agent im Repo diesem Rezept. Ändert sich der Bau- oder Startweg, wiederhole den Schritt.

/fewer-permission-prompts geht deine Transkripte durch, sammelt die lesenden Bash- und MCP-Aufrufe, die häufig vorkommen, und schlägt daraus eine nach Priorität geordnete Allowlist für .claude/settings.json vor. Lass es erst nach einigen Sessions laufen — dann beschreibt die Liste deinen echten Arbeitsablauf:

/fewer-permission-prompts