Agent Skills: .claude/skills und .agents/skills einrichten

Wenn du ein Repository mit Claude Code, Codex, Cursor und Gemini CLI verwendest, verwalte die gemeinsamen Skill-Dateien unter .agents/skills/<skill-name>/. Lege für jeden Skill unter .claude/skills/ einen symbolischen Link mit relativem Zielpfad an, damit Claude Code auf dasselbe Verzeichnis zugreifen kann. Prüfe anschließend in jedem Client, ob er den Skill erkennt und aufrufen kann, bevor dein Team diese Struktur übernimmt.

Damit gibt es nur eine bearbeitbare Kopie der Arbeitsanweisungen, obwohl die Clients unterschiedliche Regeln für die Suche verwenden. Ein Team, das ausschließlich Claude Code nutzt, kann seine bestehende Struktur unter .claude/skills/ beibehalten. Ein Umzug lohnt sich, wenn dieselben Skills tatsächlich auch in einem anderen Client benötigt werden.

Hat die AAIF den Verzeichnisnamen standardisiert?

Der Standard ist bei der AAIF angesiedelt, doch die Clients entscheiden weiterhin selbst, wo sie nach Skills suchen. Anthropic kündigte die Übergabe am 22. Oktober 2026 an, und die Stiftung nahm Agent Skills als Projekt auf.

Der Leitfaden für Client-Implementierungen nimmt den Speicherort der Skill-Verzeichnisse ausdrücklich von den Vorgaben der Spezifikation aus. Er empfiehlt, neben dem jeweiligen Client-Verzeichnis auch .agents/skills/ für die Zusammenarbeit verschiedener Tools zu berücksichtigen. Diese Empfehlung bedeutet nicht, dass jeder bestehende Client diesen Pfad bereits durchsucht.

Die übertragbare Einheit ist ein Verzeichnis mit einer SKILL.md, die einen YAML-Metadatenblock am Anfang, das sogenannte Frontmatter, und Anweisungen in Markdown enthält. Die Formatspezifikation verlangt name und description; weitere Ressourcen sind optional. Aufrufsyntax, Laufzeitumgebungen für Skripte und Berechtigungen hängen weiterhin vom ausführenden Client ab. Insbesondere allowed-tools ist noch experimentell und wird unterschiedlich unterstützt. Es eignet sich deshalb nicht als einheitliche Berechtigungsrichtlinie für alle Clients.

Welche Pfade durchsuchen die vier Tools?

Verwende die folgenden dokumentierten Suchverzeichnisse im lokalen Dateisystem. Die Pfade und Bedienelemente entsprechen der offiziellen Dokumentation mit Stand 2026-10-26. Ergänze jeden Pfad um <skill-name>/SKILL.md, um die hier verwendete Struktur zu erhalten.

Tool	Verzeichnisse im Repository	Benutzerverzeichnisse	Empfehlung für ein gemeinsames Repository
Claude Code	`.claude/skills/`	`~/.claude/skills/`	Lege pro Skill einen Link von `.claude/skills/` zum gemeinsamen Verzeichnis an.
Codex CLI und IDE-Erweiterung	`.agents/skills/`	`~/.agents/skills/`	Lies das gemeinsame Verzeichnis direkt.
Cursor Agent	`.agents/skills/`, `.cursor/skills/`; aus Kompatibilitätsgründen auch `.claude/skills/` und `.codex/skills/`	Dieselben vier Verzeichnisnamen unter `~/`	Verwende `.agents/skills/`; ein zusätzlicher Link für Cursor ist nicht nötig.
Gemini CLI	`.agents/skills/` und `.gemini/skills/`	`~/.agents/skills/` und `~/.gemini/skills/`	Lies `.agents/skills/` direkt. Innerhalb desselben Geltungsbereichs hat dieser Pfad Vorrang vor `.gemini/skills/`.

Der aktuelle Leitfaden von Claude Code führt die native Suche in .agents/skills/ nicht auf, und der Funktionswunsch #31005 ist weiterhin offen. Umgekehrt nennen die oben verlinkten Anleitungen für Codex und Gemini .claude/skills/ nicht als Suchverzeichnis. Halte dich an die dokumentierten Pfade, statt beide Verzeichnisse für alle Clients als austauschbar zu behandeln.

Diese Pfade betreffen die lokale Suche. Ein Skill im Home-Verzeichnis deines Laptops steht nicht automatisch in einem entfernten Worker oder einem neuen Container bereit. Auch diese Umgebung muss die Dateien erhalten.

Erstelle einen gemeinsamen Skill und einen Link für Claude Code

Speichere den vollständigen Skill unter .agents/skills/ und verlinke sein gesamtes Verzeichnis, damit später ergänzte Skripte und Referenzdateien ebenfalls erreichbar sind. Ein eigener Link pro Skill lässt zugleich Platz für vorhandene Skills, die nur für Claude gedacht sind.

Du benötigst Git sowie einen installierten und authentifizierten Client, der bereits in deinem Repository arbeiten kann. Für diese Dateisystemkonfiguration sind keine neuen API-Zugangsdaten erforderlich. Die üblichen Zugangsbedingungen des Clients und Berechtigungen für seine Tools gelten weiterhin.

Schreibe den portablen Skill

Erstelle in deinem Editor .agents/skills/review-staged/SKILL.md und bei Bedarf die übergeordneten Verzeichnisse. Falls dieser Skill bereits existiert, wähle einen anderen Namen und passe Verzeichnis, Frontmatter und Befehle entsprechend an.

Füge diesen vollständigen Dateiinhalt ein:

---
name: review-staged
description: "Review staged Git changes for correctness before a commit. Use when the user asks to review the Git index or staged changes."
---

Begin the answer with `Skill loaded: review-staged`.

1. Locate the repository root with `git rev-parse --show-toplevel`.
   Run all following commands from that directory.
2. Run `git diff --cached --name-only`. If it prints no paths,
   report `No staged changes.` and stop.
3. Run `git diff --cached --check` and `git diff --cached --`.
   Treat a nonzero `--check` exit as evidence to report, not a reason
   to skip reading the diff.
4. Read relevant files as needed. Report concrete correctness issues
   with file and line references. Separate confirmed issues from questions.
5. Finish with suggested verification commands. Do not claim they ran.

Do not edit files, stage changes, or create a commit.

Dieser Ablauf prüft den Git-Index, also die für den nächsten Commit vorgemerkten Änderungen. Die Referenz zu git diff beschreibt --cached für diesen Vergleich und --check für Whitespace-Fehler und Konfliktmarkierungen. Der Skill fordert den Agenten auf, gewöhnliche Befehle auszuführen, statt sich auf eine clientspezifische Erweiterung des Prompts zu verlassen.

Lege den Link mit Bash unter macOS oder Linux an

Erstelle einen relativen symbolischen Link, kurz Symlink, für diesen Skill. Claude Code dokumentiert ausdrücklich die Unterstützung für verlinkte Skill-Verzeichnisse.

Führe den folgenden Block in Bash aus. Du kannst dabei in einem beliebigen Verzeichnis innerhalb des gewünschten Git-Repositorys beginnen:

(
  set -eu
  cd "$(git rev-parse --show-toplevel)"
  test -f .agents/skills/review-staged/SKILL.md
  mkdir -p .claude/skills

  skill_link=.claude/skills/review-staged
  if [ -e "$skill_link" ] || [ -L "$skill_link" ]; then
    printf '%s\n' "Already exists: $skill_link" >&2
    exit 1
  fi

  ln -s ../../.agents/skills/review-staged "$skill_link"
  test -L "$skill_link"
  test -f "$skill_link/SKILL.md"
  readlink "$skill_link"
)

Die erwartete Ausgabe lautet ../../.agents/skills/review-staged bei einem Exit-Status von 0. Die beiden ..-Bestandteile beziehen sich auf das übergeordnete Verzeichnis des Links, .claude/skills/, und führen zurück zum Repository-Stamm.

Wenn am vorgesehenen Pfad bereits ein Eintrag existiert, prüfe ihn, bevor du etwas änderst. Behalte einen vorhandenen korrekten Link bei. Falls dort ein echtes Skill-Verzeichnis liegt, gleiche seinen Inhalt bewusst mit der zentral gepflegten Kopie ab. Der Befehl ersetzt weder ein Verzeichnis noch einen Link, dessen Ziel nicht mehr existiert.

Erstelle den entsprechenden Link unter Windows

Verwende für den folgenden relativen Verzeichnislink PowerShell 7.1 oder neuer. Die New-Item-Dokumentation von Microsoft nennt diese Versionsvoraussetzung. Das Erstellen symbolischer Links unter Windows erfordert normalerweise erhöhte Rechte oder eine unterstützte Windows-Version mit aktiviertem Entwicklermodus.

Speichere zuerst die zentrale SKILL.md und führe diesen Block im Repository-Stamm aus:

New-Item -ItemType Directory -Force -Path '.claude/skills' -ErrorAction Stop | Out-Null
Push-Location '.claude/skills' -ErrorAction Stop
try {
    New-Item -ItemType SymbolicLink -Path 'review-staged' `
        -Target '../../.agents/skills/review-staged' -ErrorAction Stop | Out-Null
    Get-Item 'review-staged' | Select-Object LinkType, Target
    Test-Path 'review-staged/SKILL.md' -PathType Leaf
}
finally {
    Pop-Location
}

LinkType sollte den Wert SymbolicLink haben, und die Dateiprüfung sollte True zurückgeben. Scheitert das Erstellen an fehlenden Rechten, nutze das von deiner Organisation freigegebene Verfahren für den Entwicklermodus oder die Einrichtung mit erhöhten Rechten.

Gehe nicht davon aus, dass sich die native Git Bash wie unter Linux verhält: Git for Windows dokumentiert, dass ln -s standardmäßig Kopien erstellt. Verwende das PowerShell-Verfahren und prüfe den entstandenen Link.

Nach dem Klonen kann ein anderes Problem auftreten. Mit core.symlinks=false checkt Git einen symbolischen Link als gewöhnliche Datei aus, die dessen Zielpfad als Text enthält. Prüfe das in PowerShell:

git config --show-origin --get core.symlinks
Get-Item '.claude/skills/review-staged' |
    Select-Object LinkType, Target, PSIsContainer
Test-Path '.claude/skills/review-staged/SKILL.md' -PathType Leaf

Ist der Link stattdessen eine Textdatei, lies ihren Inhalt, bevor du genau diese Datei durch einen echten Link ersetzt. Richte für künftige Klone eine unterstützte Verarbeitung symbolischer Links beim Checkout ein. Das Ändern der Git-Einstellung allein wandelt eine bereits ausgecheckte Textdatei nicht in einen Verzeichnislink um.

Prüfe Erkennung, Aktivierung und Ausgabe

Prüfe zuerst den Skill-Katalog des Clients und rufe den Skill danach ausdrücklich auf. Eine Datei auf der Festplatte beweist noch nicht, dass der Client sie erkannt hat. Ebenso belegt ein Katalogeintrag nicht, dass die Anweisungen geladen wurden.

Öffne oder starte jeden Client im Repository-Stamm. Verwende diese Bedienelemente innerhalb des Clients, nicht an einer Bash- oder PowerShell-Eingabeaufforderung:

Client	Erkennung bestätigen	Beispiel aufrufen
Claude Code	Führe `/skills` aus; verwende bei Bedarf `/reload-skills` gemäß der Befehlsreferenz.	Sende `/review-staged`.
Codex CLI oder IDE-Erweiterung	Öffne `/skills` oder die Skill-Auswahl über `$`.	Sende `$review-staged Review my staged changes.`
Cursor Agent	Öffne Customize → Skills und suche den Skill in der `/`-Auswahl.	Wähle `review-staged` und bitte um eine Prüfung der vorgemerkten Änderungen.
Gemini CLI	Führe `/skills list` aus; verwende nach dem Hinzufügen von Dateien `/skills reload`.	Sende diese Anfrage: `Use the review-staged skill to review my staged changes.`

Der dokumentierte Aktivierungsablauf von Gemini verwendet activate_skill und eine interaktive Zustimmungsabfrage. Bestätige auf Nachfrage das Verzeichnis des gewünschten Skills. Der Leitfaden zur Verwaltung beschreibt die Befehle zum Auflisten und Neuladen.

Die erwartete Antwort beginnt mit Skill loaded: review-staged, gefolgt von Befunden und vorgeschlagenen Prüfungen. Bei leerem Index folgt No staged changes.. Prüfe neben dieser Markierung auch die Aufzeichnung der Aktivierung oder des Dateizugriffs sowie die Git-Befehle. Das belegt, dass die Arbeitsanweisungen geladen wurden. Ob jeder Befund der Codeprüfung stimmt, musst du gesondert beurteilen.

Cursor liest in dieser Struktur beide Pfade. Laut den Versionshinweisen zu IDE 3.25 vom 14. Oktober 2026 können Skills mit demselben Namen als getrennte Menüeinträge erscheinen. Prüfe deine installierte Version auf doppelte Einträge. Verlasse dich nicht darauf, dass alle Clients mehrere Verweise auf denselben Skill gleich behandeln.

Verwende eine klare Struktur für Monorepos und CI

Behalte gemeinsame Skills im Repository-Stamm und starte für die erste funktionierende Einrichtung alle Clients dort. Bei Abläufen für ein bestimmtes Paket nennst du das Paket in Beschreibung und Anweisungen des Skills, statt auf identische Suchregeln in verschachtelten Verzeichnissen zu vertrauen. Das obige Beispiel prüft bewusst den gesamten Git-Index.

Eine praktische Struktur weist jedem Pfad eine eindeutige Aufgabe zu:

Pfad	Aufgabe
`.agents/skills/review-staged/SKILL.md`	Zentral gepflegte gemeinsame Anweisungen.
`.agents/skills/review-staged/references/`	Optionale Begleitdokumente, die mit diesem Skill verteilt werden.
`.claude/skills/review-staged`	Relativer Link zum vollständigen gemeinsamen Skill-Verzeichnis.
`packages/mobile/`	Anwendungscode, der in der angefragten Aufgabe genannt wird.

Die Regeln für den Geltungsbereich unterscheiden sich. Claude Code und Codex suchen vom Startverzeichnis aufwärts bis zum Repository-Stamm nach ihren jeweiligen Skill-Verzeichnissen. Cursor dokumentiert außerdem verschachtelte Projekt-Skills, deren Geltungsbereich auf Dateien unterhalb ihres Verzeichnisses begrenzt ist. Geminis Verwaltungsleitfaden beschreibt Workspace-Skills relativ zum aktuellen Verzeichnis. Wenn du alle vier Clients im Repository-Stamm startest, musst du dich nicht auf diese Unterschiede verlassen.

Lege jeden gemeinsamen Skill direkt in einem Unterverzeichnis des Skill-Stammverzeichnisses ab. Geminis Einstiegsleitfaden begrenzt die Suche auf diese Tiefe. Dass Cursor rekursiv sucht, macht eine zusätzliche Ebene für Kategorien nicht über alle Clients hinweg portabel.

Ist nur ein einzelnes Paket als Arbeitsbereich geöffnet, wiederhole dort die Erkennungsprüfung und installiere oder verlinke den gemeinsamen Skill bei Bedarf auch dort. Übernimm das Ziel ../../ des Links im Repository-Stamm nicht ungeprüft für einen tiefer liegenden Speicherort, sondern berechne den relativen Pfad neu.

Committe das zentrale Verzeichnis und den relativen Symlink, sofern die Checkout-Umgebungen deines Teams diese unterstützen. Das Linkziel sollte innerhalb des Repositorys liegen, damit ein neuer Klon es ohne Zugriff auf das Home-Verzeichnis eines einzelnen Entwicklers auflösen kann.

Für einen CI-Checkout unter Linux prüft dieser Bash-Block die benötigten Dateien und den Link:

test -f .agents/skills/review-staged/SKILL.md &&
test -L .claude/skills/review-staged &&
test -f .claude/skills/review-staged/SKILL.md

Ein Exit-Status von 0 bedeutet, dass diese Dateisystemprüfungen erfolgreich waren. Die Erkennung und der Aufruf im Client müssen weiterhin mit den oben beschriebenen Schritten in der tatsächlichen Ausführungsumgebung geprüft werden.

Wenn der Skill weiterhin nicht lädt: Prüfe die fehlerhafte Ebene

Behebe das Problem dort, wo es auftritt, statt den Prompt wiederholt zu ändern. Die folgenden Punkte sind alternative Diagnosezweige. Sie sind keine Liste von Einstellungen, die jeder nacheinander ändern muss.

Der Skill fehlt im Katalog: Prüfe den Stamm des Arbeitsbereichs, die Schreibweise der Verzeichnisse und den exakten Dateinamen SKILL.md. Lies die Datei über den Pfad, den der Client durchsucht. Funktioniert der zentrale Pfad, aber der Claude-Pfad nicht, repariere den Link oder den Checkout.
Datei gefunden, Metadaten abgelehnt: Prüfe die YAML-Begrenzer, eine nicht leere description mit höchstens 1024 Zeichen und einen zum Verzeichnis passenden name mit 1–64 Zeichen aus Kleinbuchstaben, Ziffern oder Bindestrichen. Vermeide Bindestriche am Anfang, am Ende oder direkt hintereinander.
Eine neue Datei erscheint noch nicht: Lade Claude- oder Gemini-Skills mit den oben genannten Befehlen neu. Codex dokumentiert die automatische Erkennung; bleibt eine Änderung unsichtbar, starte Codex neu. Öffne Cursor erneut, wenn die Suche beim Programmstart wiederholt werden muss.
Ein Workspace-Skill fehlt in Gemini: Prüfe den Vertrauensstatus des Ordners über /permissions trust. Die aktuelle Konfigurationsreferenz führt skills.enabled mit dem Standardwert true auf, doch eine Administratorrichtlinie kann Skills untersagen. Korrigiere eine deaktivierte Einstellung oder eine Vertrauensentscheidung über die dafür vorgesehenen Bedienelemente.
Der falsche Skill wird ausgeführt: Suche nach persönlichen und projektbezogenen Kopien mit demselben Namen. Claude bevorzugt persönliche Skills gegenüber Projekt-Skills; Codex kann beide auflisten; Gemini bevorzugt Workspace-Skills gegenüber Benutzer-Skills. Verwende für unterschiedliche Abläufe unterschiedliche Namen.
Der Skill ist aufgelistet, wird aber nicht automatisch ausgewählt: Rufe ihn zunächst ausdrücklich auf. Funktioniert das, überarbeite die Beschreibung so, dass sie die zugehörige Aufgabe klar benennt. Eine präzisere Beschreibung hilft bei der Auswahl; das Verschieben einer bereits korrekt erkannten Datei nicht.
Der Skill ist geladen, aber Befehle schlagen fehl: Prüfe, ob Git verfügbar ist, welches Arbeitsverzeichnis verwendet wird und welcher Berechtigungsfehler gemeldet wird. Eine portable Verzeichnisstruktur installiert keine Laufzeitumgebung und erteilt keine Ausführungsrechte.