Eigene Slash-Commands in Claude Code erstellen

1. Was ein Slash-Command technisch ist

Ein Slash-Command in Claude Code ist im Kern nichts anderes als eine Markdown-Datei an einem festgelegten Speicherort. Tippt man in der Claude-Code-CLI ein Kommando wie /review-pr, sucht Claude Code nach einer passenden Datei, laedt deren Inhalt als vorformulierten Prompt und fuehrt ihn im aktuellen Kontext aus. Es gibt keine separate Programmiersprache, keinen Compile-Schritt und keine versteckte Konfigurationsdatenbank, nur eine Textdatei, die genauso im Git-Repository versioniert wird wie der restliche Code.

Der praktische Nutzen zeigt sich sofort im Entwickleralltag: Wiederkehrende Aufgaben wie ein strukturiertes Code-Review, ein Release-Vorbereitungs-Check oder ein Datenbank-Migrations-Dry-Run muessen nicht jedes Mal neu in Prompt-Form gegossen werden. Ein Slash-Command kapselt die Formulierung einmalig, das ganze Team ruft danach denselben, getesteten Prompt ab. Das reduziert Varianz zwischen Entwicklern und macht Claude-Code-Workflows nachvollziehbar, weil der tatsaechlich ausgefuehrte Prompt im Repository nachlesbar bleibt statt nur in der Terminal-Historie eines einzelnen Entwicklers zu existieren.

2. Aufbau: Markdown-Datei plus Frontmatter

Jeder Slash-Command besteht aus zwei Teilen: einem optionalen YAML-Frontmatter-Block am Dateianfang und dem eigentlichen Prompt-Text darunter. Das Frontmatter steuert Metadaten wie eine kurze Beschreibung, die in der Autovervollstaendigung angezeigt wird, sowie eine explizite Liste erlaubter Tools ueber das Feld allowed-tools. Fehlt das Frontmatter komplett, wird die gesamte Datei als Prompt interpretiert, das genuegt fuer einfache Commands vollstaendig.

Der Dateiname selbst bestimmt den Aufruf: review.md wird zu /review, Unterverzeichnisse werden zu Namespaces getrennt durch einen Doppelpunkt. Diese Eins-zu-eins-Abbildung zwischen Dateisystem und Command-Namen macht das System vorhersehbar, wer die Verzeichnisstruktur eines Projekts kennt, kennt automatisch auch dessen verfuegbare Slash-Commands. Das folgende Beispiel zeigt einen minimalen Command fuer eine strukturierte Zusammenfassung offener Pull Requests.

# Directory layout for project-wide slash commands
mkdir -p .claude/commands

# Create a minimal slash command: /pr-summary
cat > .claude/commands/pr-summary.md << 'EOF'
---
description: Summarize all open pull requests with review status
allowed-tools: Bash(gh pr list:*), Bash(gh pr view:*)
---

List all open pull requests via `gh pr list --json number,title,author,reviewDecision`.
Group them by review status (approved, changes requested, pending) and flag any PR
open longer than 5 days as stale.
EOF

# Invoke it inside Claude Code
# /pr-summary

3. Projektweite und persoenliche Slash-Commands

Claude Code unterscheidet zwei Speicherorte fuer Slash-Commands, und diese Unterscheidung ist mehr als reine Organisation. Commands unter .claude/commands/ im Projektverzeichnis werden mit dem Repository versioniert und stehen jedem Teammitglied automatisch zur Verfuegung, sobald es das Projekt auscheckt. Commands unter ~/.claude/commands/ im Home-Verzeichnis sind persoenlich, projektuebergreifend und werden nicht mit anderen geteilt, ideal fuer individuelle Gewohnheiten wie ein persoenliches Format fuer Commit-Nachrichten.

In der Praxis empfiehlt sich eine klare Trennung: alles, was Projektwissen voraussetzt, etwa den genauen Deploy-Ablauf oder das Test-Framework des Projekts, gehoert in .claude/commands/ und damit ins Repository. Alles, was projektunabhaengig ist, etwa ein persoenlicher Slash-Command zum Formatieren von Notizen oder zum Zusammenfassen eines beliebigen Textes, gehoert ins Home-Verzeichnis. Wer beide Ebenen konsequent nutzt, vermeidet, dass persoenliche Commands versehentlich ins Team-Repository gelangen und dort fuer Verwirrung sorgen.

# Project-wide: versioned with the repository, shared with the whole team
ls .claude/commands/
# pr-summary.md  fix-issue.md  release-check.md

# Personal: never shared, lives only on this machine
mkdir -p ~/.claude/commands
cat > ~/.claude/commands/summarize.md << 'EOF'
---
description: Summarize the given text into three concise bullet points
---

Summarize the following text into exactly three bullet points, no preamble:

$ARGUMENTS
EOF

4. Argumente und Platzhalter richtig einsetzen

Statische Prompts reichen fuer viele Faelle, aber echte Wiederverwendbarkeit entsteht erst mit Argumenten. Claude Code kennt dafuer den Platzhalter $ARGUMENTS, der beim Aufruf durch alles ersetzt wird, was nach dem Slash-Command-Namen eingegeben wurde. Ruft ein Entwickler /fix-issue 342 auf, ersetzt Claude Code $ARGUMENTS im Prompt-Text durch 342, der Command kann diesen Wert dann etwa in einen gh issue view-Aufruf einsetzen.

Fuer feingranularere Kontrolle stehen positionelle Platzhalter $1, $2 und so weiter zur Verfuegung, sobald mehrere durch Leerzeichen getrennte Argumente uebergeben werden. Ein Slash-Command fuer das Anlegen eines Hotfix-Branches kann so etwa $1 als Ticket-Nummer und $2 als kurze Beschreibung interpretieren, statt beide Werte manuell aus einem einzigen zusammengesetzten String zu parsen. Diese Trennung macht komplexere Commands deutlich robuster gegen Tippfehler und erspart zusaetzliche Parsing-Logik im Prompt-Text selbst.

mkdir -p .claude/commands

# /fix-issue 342 -- fetches issue and drafts a fix plan
cat > .claude/commands/fix-issue.md << 'EOF'
---
description: Fetch a GitHub issue and draft a fix plan before touching code
argument-hint: <issue-number>
allowed-tools: Bash(gh issue view:*)
---

Fetch issue #$ARGUMENTS with `gh issue view $ARGUMENTS --json title,body,labels`.
Read the referenced files, then propose a fix plan with affected files and test
strategy before making any code changes. Wait for explicit approval.
EOF

# /new-hotfix TICKET-88 "fix null pointer in checkout"
cat > .claude/commands/new-hotfix.md << 'EOF'
---
description: Create a hotfix branch following the team naming convention
argument-hint: <ticket> <short-description>
allowed-tools: Bash(git checkout:*), Bash(git branch:*)
---

Create and check out a branch named hotfix/$1-$2 from the current default branch.
Ticket reference: $1. Description: $2.
EOF

5. Bash-Ausfuehrung und allowed-tools kombinieren

Ein besonders maechtiges Feature von Slash-Commands ist das Praefix ! vor einer Bash-Zeile im Prompt-Text. Beginnt eine Zeile mit !, fuehrt Claude Code den dahinterstehenden Befehl vor der eigentlichen Prompt-Verarbeitung aus und fuegt dessen Ausgabe direkt in den Kontext ein. Ein Slash-Command kann so etwa den aktuellen Git-Status, die letzten Commits oder den Inhalt einer Log-Datei automatisch einsammeln, ohne dass Claude selbst erst einen Tool-Aufruf staten muss.

Damit dieses Feature nicht zum Sicherheitsrisiko wird, muss das Frontmatter-Feld allowed-tools exakt definieren, welche Bash-Befehle erlaubt sind. Statt pauschal jeden Bash-Aufruf zuzulassen, spezifiziert man Muster wie Bash(git status:*) oder Bash(npm test:*), sodass ein Slash-Command zum Testen niemals versehentlich einen destruktiven rm -rf-Befehl ausfuehren kann. Diese Kombination aus automatischer Kontext-Anreicherung und eng begrenztem Tool-Zugriff macht Bash-gestuetzte Commands sowohl produktiv als auch sicher genug fuer den Teameinsatz.

mkdir -p .claude/commands

# /release-check -- gathers repo state before a release, no code changes allowed
cat > .claude/commands/release-check.md << 'EOF'
---
description: Gather pre-release repo state and flag risks
allowed-tools: Bash(git log:*), Bash(git status:*), Bash(npm test:*)
---

Current branch and status:
!`git status --short --branch`

Commits since last tag:
!`git log $(git describe --tags --abbrev=0)..HEAD --oneline`

Test suite result:
!`npm test -- --silent`

Based on the above, list open risks before this release goes out. Do not modify
any files, this command is read-only.
EOF

6. Namespacing bei vielen Commands im Team

Sobald ein Team mehr als eine Handvoll Slash-Commands pflegt, wird eine flache Ablage in einem einzigen Verzeichnis schnell unuebersichtlich. Claude Code loest das ueber Unterverzeichnisse, die automatisch zu einem Namespace mit Doppelpunkt-Trennung werden: eine Datei unter .claude/commands/db/migrate.md wird zu /db:migrate, eine Datei unter .claude/commands/frontend/build.md zu /frontend:build. Diese Struktur spiegelt oft die Teamaufteilung eines Projekts wider und macht sofort erkennbar, zu welchem Bereich ein Slash-Command gehoert.

Fuer groessere Projekte empfiehlt sich eine Konvention nach Verantwortungsbereich statt nach Technologie: backend/, frontend/, ops/ und docs/ als oberste Ebene, darunter die konkreten Commands. Wer neue Commands anlegt, sollte sich vorher kurz fragen, ob ein bestehender Namespace passt, bevor ein neuer eroeffnet wird, denn zu viele flache Top-Level-Namespaces heben den Ordnungsgewinn wieder auf. Die Beschreibung im Frontmatter bleibt dabei die wichtigste Orientierungshilfe, sie erscheint in der Autovervollstaendigung und sollte in einem Satz erklaeren, was der Slash-Command tut und was nicht.

7. Praxisbeispiele: Deploy, Review und Tests

In der taeglichen Praxis fallen drei Kategorien von Slash-Commands besonders oft an. Die erste ist der Review-Command, der einen strukturierten Blick auf einen Diff wirft: Sicherheitsluecken, fehlende Tests, Style-Verstoesse, jeweils mit klarer Prioritaet. Die zweite Kategorie sind Deploy- und Release-Commands, die einen festen Ablauf aus Checks, Build und Freigabe abbilden, wie im vorherigen Abschnitt gezeigt. Die dritte Kategorie sind Test-Commands, die etwa gezielt nur die von den letzten Aenderungen betroffenen Testdateien ausfuehren, statt die komplette Suite bei jedem kleinen Fix laufen zu lassen.

Ein vierter, oft unterschaetzter Anwendungsfall ist Onboarding: ein Slash-Command namens /explain-module, der ein beliebiges Verzeichnis als Argument entgegennimmt und eine strukturierte Erklaerung der Architektur, der wichtigsten Klassen und der Testabdeckung liefert. Neue Teammitglieder nutzen genau diesen Command in den ersten Wochen deutlich haeufiger als erfahrene Entwickler, was ihn zu einem messbaren Hebel fuer schnelleres Einarbeiten macht, ganz ohne dass jemand persoenlich Zeit fuer eine Fuehrung durch den Code investieren muss.

8. Debugging und typische Fehlerquellen

Der haeufigste Fehler bei eigenen Slash-Commands ist ein zu breit gefasstes allowed-tools-Muster. Wer Bash(*) statt eines spezifischen Musters wie Bash(npm test:*) einsetzt, hebelt die Sicherheitsfunktion faktisch aus und erlaubt dem Command jeden beliebigen Bash-Befehl, was besonders bei mit !-Praefix eingebetteten Befehlen riskant wird. Ein zweiter haeufiger Fehler ist ein fehlendes argument-hint-Feld: ohne diesen Hinweis in der Autovervollstaendigung wissen Teammitglieder oft nicht, in welcher Reihenfolge und Form Argumente erwartet werden.

Ein dritter Fehler betrifft die Erwartungshaltung an $ARGUMENTS versus $1/$2: Wird im Prompt-Text $1 verwendet, aber der Aufruf enthaelt nur ein einziges Wort ohne Leerzeichen als Trenner, bleibt $2 leer und der Command verhaelt sich unerwartet. Am einfachsten testet man einen neuen Slash-Command zunaechst mit klar erkennbaren Testwerten wie test-arg-1 und test-arg-2, um sofort zu sehen, ob die Platzhalter korrekt und in der richtigen Reihenfolge ersetzt wurden, bevor der Command produktiv im Team eingesetzt wird.

# Safe way to test a new slash command before rolling it out to the team
# /new-hotfix test-arg-1 test-arg-2
# Expected: branch name becomes hotfix/test-arg-1-test-arg-2

# If $2 stays empty, the call was likely missing a space separator, e.g.:
# /new-hotfix "test-arg-1 test-arg-2"   -- WRONG, treated as a single $1

git branch --list "hotfix/test-arg-1*"   # verify the branch name matches

9. Slash-Commands im Vergleich zu Alternativen

Nicht jede wiederkehrende Aufgabe gehoert zwingend in einen Slash-Command. Je nach Komplexitaet und Zielgruppe gibt es passendere Alternativen, deren Staerken und Schwaechen sich direkt gegenueberstellen lassen.

Die Faustregel lautet: Sobald ein Prompt zum zweiten oder dritten Mal fast identisch eingegeben wird, lohnt sich die Investition in einen Slash-Command. Feste, rein deterministische Schritte ohne Interpretationsspielraum gehoeren eher in ein klassisches Bash-Skript, waehrend dauerhafte Verhaltensregeln, die immer gelten sollen, besser in CLAUDE.md aufgehoben sind statt in einem Command, der explizit aufgerufen werden muss.

10. Zusammenfassung

Eigene Slash-Commands in Claude Code sind Markdown-Dateien mit optionalem Frontmatter, die wiederkehrende Prompts, Argumente und einen eng begrenzten Tool-Zugriff buendeln. Projektweite Commands unter .claude/commands/ werden mit dem Repository versioniert und stehen dem ganzen Team zur Verfuegung, persoenliche Commands unter ~/.claude/commands/ bleiben individuell. Platzhalter wie $ARGUMENTS, $1 und $2 machen Commands parametrisierbar, das !-Praefix erlaubt automatische Bash-Ausfuehrung vor der Prompt-Verarbeitung.

Sicherheit entsteht durch praezise allowed-tools-Muster statt pauschaler Freigaben, Struktur durch sinnvolles Namespacing nach Verantwortungsbereich statt nach Technologie. Wer Review-, Deploy- und Test-Workflows als Slash-Commands versioniert, reduziert Varianz im Team und macht Claude-Code-Nutzung nachvollziehbar, statt sie von individuellen Prompt-Gewohnheiten einzelner Entwickler abhaengig zu machen.

11. FAQ: Eigene Slash-Commands in Claude Code