CLAUDE.md gegen AGENTS.md gegen SKILL.md: Was kommt wohin und warum.

Jeder, der mit Claude Code anfängt, erstellt tendenziell eine CLAUDE.md-Datei und packt alles hinein: Projekt-Einrichtung, Codierregeln, Richtlinien für Pull Requests, Details zur Technologie-Stack und Einarbeitungshinweise. Dann kommt AGENTS.md dazu, gefolgt von SKILL.md – es sieht so aus, als wären es drei Dateien für dieselbe Aufgabe. Das ist aber nicht der Fall. Wenn man sie verwechselt, zahlt man für Tokens, die nichts für einen bringen.

Ein einfaches mentales Modell

Stellen Sie sich ein Unternehmen vor. CLAUDE.md ist das Mitarbeiterhandbuch, das jeder Neue am ersten Tag liest – stets im Hintergrund. AGENTS.md ist dasselbe Handbuch, allerdings so verfasst, dass externe Auftragnehmer jeder Agentur es verstehen können, nicht nur die fest angestellten Mitarbeiter. SKILL.md ist ein Handbuch auf einem Regal, das man nur herunternimmt, wenn man eine bestimmte Aufgabe erledigt. Drei Dateien, drei Aufgaben und drei verschiedene Ladeverfahren.

CLAUDE.md: immer geladen

Dies ist die Hauptkonfigurationsdatei von Claude Code. Zu Beginn einer Sitzung liest Claude sie und speichert sie in seinem Systemprompt. Sie wird nur einmal geladen, wird Teil des Kontexts, der während der gesamten Sitzung verwendet wird, und muss nicht mit jeder Nachricht erneut von der Festplatte geladen werden. Wenn Sie also eine Begrüßung eingeben, sind diese Anweisungen bereits vorhanden – und sie sind es auch weiterhin, wenn Sie später um die Behebung eines Fehlers bitten.

Die Folge ist, dass eine große Datei dauerhaft einen Teil des Kontextfensters belegt, auch bei Aufgaben, bei denen der größte Teil davon irrelevant ist. Deshalb lohnt sich eine fokussierte, kurze Datei.

Drei Ebenen

Anweisungen stammen aus mehreren Bereichen und werden kombiniert:

1. Eine persönliche Datei unter ~/.claude/CLAUDE.md, die Präferenzen enthält, die in jedem Projekt gelten, wie zum Beispiel den Einrückungsstil oder Gewohnheiten bei Commit-Nachrichten. Teammitglieder sehen sie niemals.

Ein Projektdatei, entweder .claude/CLAUDE.md oder eine Datei im Wurzelverzeichnis des Repositoriums. Sie wird in Git gespeichert, sodass jeder, der das Repo kloniert, dieselben Regeln erhält. Hier finden sich Informationen zum Stack, Befehle sowie Teamstandards.

regel spezifisch für bestimmte Pfade, die unter .claude/rules/ gespeichert sind und über eine paths-Einstellung im Frontmatter verfügen. Eine testing-rules-Datei kann beispielsweise nur dann geladen werden, wenn Testdateien bearbeitet werden, wodurch irrelevante Anleitungen außerhalb des Kontexts bleiben.

Einschränkendere Projektanleitungen werden nach allgemeineren Anweisungen auf Benutzerebene geladen, sodass im Falle eines Konflikts die Projektversion Vorrang haben kann. Die praktische Regel lautet: Persönliche Präferenzen gehen in die persönliche Konfiguration, gemeinsame Teamkonventionen in das Projekt.

Was gehört hinein

Bleiben Sie kurz. Ein Ziel von etwa 200 Zeilen ist angemessen, obwohl es sich dabei um eine Richtlinie und nicht um eine feste Grenze handelt. Enthalten Sie nur das, was Claude für jede Aufgabe benötigt: den Technologiestack, die Befehle zur Ausführung von Tests und zum Starten des Entwicklungs Servers, absolute Regeln wie das Verbot der Protokollierung von Benutzerdaten sowie die wichtigsten Architekturentscheidungen.

Lassen Sie alles weg, was spezifisch für eine Aufgabe ist. Ein ausführlicher Leitfaden zur Überprüfung eines PRs oder ein Katalog an Randfällen finden bessere Verwendungsorte, die weiter unten erläutert werden.

Eine wichtige Besonderheit

Falls Sie CLAUDE.md während einer Sitzung bearbeiten, wird die laufende Sitzung dies nicht bemerken. Die Datei wurde zu Beginn nur einmal gelesen, weshalb für die Anwendung von Änderungen eine neue Sitzung erforderlich ist. Das ist der häufigste Grund, warum neu hinzugefügte Regeln ignoriert zu erscheinen scheinen.

AGENTS.md: für Teams mit mehreren Tools

AGENTS.md dient demselben Zweck und enthält den Projektkontext sowie Anweisungen. Der Unterschied liegt darin, wer ihn lesen kann. Claude Code liest CLAUDE.md, während OpenAI Codex, Cursor, Gemini CLI und GitHub Copilot AGENTS.md lesen.

Laut dieser Beschreibung erkennt Claude Code AGENTS.md nicht direkt, doch ein Symbollink löst dieses Problem, indem er beide Namen auf dieselbe Datei verweist (überprüfen Sie die aktuellen Dokumente, falls die Unterstützung geändert wurde):

ln -s AGENTS.md CLAUDE.md

Nun gibt es eine einzige Datei, jedes Tool liest sie und nichts gerät aus dem Takt.

Wann es benötigt wird

Falls das gesamte Team nur Claude Code verwendet, reicht CLAUDE.md aus. Wenn die Mitarbeiter verschiedene Tools nutzen oder wenn der CI einen anderen Agenten als die Entwickler lokal verwenden, wird AGENTS.md zur einzigen Quelle der Wahrheit für alle Tools.

Stillschweigendes Verschwinden von Anweisungen

Mehre-Agent-Pipelines weisen einen problematischen Fehlermodus auf. Stellen Sie sich vor, eine Phase läuft in Claude Code und eine andere in einem Tool eines anderen Anbieters. Wenn Ihre Regeln nur in CLAUDE.md gespeichert sind, ignoriert das zweite Tool sie ohne jeglichen Fehler oder Warnhinweis. Der Agent läuft zwar normal, befolgt aber nicht die Konventionen, von denen Sie annahmen, sie würden gelten. Die Ausgaben werden inkonsistent, das Verhalten weicht ab, und da nichts defekt erscheint, ist die Ursache schwer zu finden. Die Verwendung von AGENTS.md als gemeinsamer Basis ermöglicht es jedem Tool in der Pipeline, dieselben Regeln zu sehen.

SKILL.md: auf Anfrage geladen

Dieses funktioniert anders. Die anderen beiden werden zu Beginn jeder Sitzung geladen und bleiben im Kontext. Eine Fähigkeit wird nur dann geladen, wenn die aktuelle Aufgabe ihrer Beschreibung entspricht.

Eine Fähigkeit ist ein Ordner, der einen SKILL.md-Datei enthält. Die Datei beginnt mit einem kurzen YAML-Header, der der Fähigkeit einen Namen sowie eine einzeilige Beschreibung gibt, und genau diese Beschreibung liest Claude, um zu beurteilen, ob die Fähigkeit passt. Wenn Sie eine Nachricht senden, vergleicht Claude sie mit den Beschreibungen all Ihrer Fähigkeiten und lädt die passende herunter. Wenn die Aufgabe beendet ist, wird die Fähigkeit wieder entfernt. So könnte das Frontmatter aussehen:

---
name: pr-review
description: Use when the user asks to review a pull request or check code quality.
allowed-tools: [Read, Grep, Glob]
---

Warum das Tokens spart

Nehmen wir an, Sie haben zehn Workflows dokumentiert. Legen Sie alle zehn in CLAUDE.md ab – dann werden alle bei jeder Nachricht geladen, selbst bei einer Anfrage zur Korrektur eines Tippfehlers. Als Fähigkeiten wird nur die relevante geladen, während die anderen neun keinen Aufwand verursachen. Bei langen Sitzungen mit unterschiedlichen Aufgabentypen sorgt das dafür, dass der Kontext übersichtlich bleibt und sich auf die vorliegende Arbeit konzentriert.

Die Beschreibung ist am wichtigsten

Claude stützt sich bei der Auswahl auf die Beschreibung. Eine vage Beschreibung wie „hilft beim Code“ wird entweder nie aktiviert oder für alles. Eine präzise Beschreibung, beispielsweise die Überprüfung von Python-Pull-Requests auf Schwachstellen wie SQL-Injection oder hartecodierte Geheimnisse, wird zuverlässig und nur dann ausgelöst, wenn sie relevant ist. Der Ordnernamen dient Ihnen; die Beschreibung gilt für Claude – schreiben Sie sie also für Claude.

Zwei nützliche Frontmatter-Optionen

allowed-tools begrenzt die Funktionen von Claude, solange die Fähigkeit aktiv ist. Bei einer Fähigkeit, die einen Codebase durchsucht, ermöglicht die Einstellung auf „lesen“, „grep“ und „glob“ es Claude, sich umzusehen, ohne Dateien zu bearbeiten oder zu schreiben – diese Einschränkung gilt auch dann, wenn Sie eine Bearbeitung anfordern.

context: fork führt die Arbeit der Fähigkeit in einem isolierten Kontext aus. Zwischenschritte bleiben verborgen, und nur das endgültige Ergebnis wird in die Hauptsession zurückgesendet. Dies eignet sich für Aufgaben, bei denen viel Inhalt erzeugt wird, den man nicht lesen muss, wie zum Beispiel das Scannen von fünfzig Dateien zu einem einzigen Zusammenfassung.

Halten Sie die Fähigkeiten auch kompakt

Eine große Fähigkeit verbraucht nach dem Laden mehr Kontext. Wenn ein Workflow umfangreiche Dokumentation, Beispiele oder Referenzmaterialien benötigt, legen Sie diese in separate Dateien und lassen die Fähigkeit sie bei Bedarf abrufen. Die Hauptanweisungen sollten auf dem Workflow selbst bleiben.

Vergleich der drei Methoden

Wie man wählt

• Regeln, die für jede Aufgabe in jeder Sitzung gelten, werden in CLAUDE.md aufgenommen.
• Falls das Team mehrere KI-Programmierwerkzeuge verwendet oder der Prozess diese miteinander kombiniert, sollte AGENTS.md als Quelle der Wahrheit dienen und CLAUDE.md darauf verlinkt werden.

Ein bestimmter Arbeitsablauf, den Sie wiederholen – wie das Überprüfen von Pull Requests, die Erstellung eines Lebenslaufs oder das Durchsuchen von Dokumentation – sollte zu einer Fähigkeit werden.

Falls Claude für einen Arbeitsablauf nur in Lese-Modus bleiben muss, machen Sie ihn zu einer Fähigkeit mit allowed-tools.

Falls Sie etwas manuell mit einem Befehl auslösen möchten, verwenden Sie einen Slash-Befehl in .claude/commands/.

Eine übersichtliche Gestaltung

your-project/
├── AGENTS.md                   <- shared source of truth for all tools
├── CLAUDE.md                   <- imports AGENTS.md, adds Claude-specific rules
├── .claude/
│   ├── rules/
│   │   ├── testing.md          <- loads only when editing test files
│   │   └── security.md         <- loads only when editing auth-related files
│   ├── skills/
│   │   ├── pr-review/
│   │   │   └── SKILL.md        <- loads when you ask for a PR review
│   │   └── latex-resume/
│   │       └── SKILL.md        <- loads when you ask to build a resume
│   └── commands/
│       └── standup.md          <- /standup generates your daily update
└── ~/.claude/
    └── CLAUDE.md               <- your personal preferences, not in the repo

CLAUDE.md bleibt kurz, weil er nur das enthält, was jede Aufgabe wirklich benötigt. Die Fähigkeiten übernehmen die komplexen, auf bestimmte Aufgaben zugeschnittenen Workflows. AGENTS.md sorgt dafür, dass alles weiterhin funktioniert, wenn ein Teammitglied die Tools wechselt.

Grundregel

Falls CLAUDE.md mehr als 200 Zeilen oder etwa 1.200 bis 1.500 Tokens umfasst, bezahlt man vermutlich für die meisten Nachrichten Instruktionen, die nicht benötigt werden. Sortieren Sie nach dem Zeitpunkt, zu dem jede Anweisung benötigt wird: „immer“ bedeutet CLAUDE.md, „über verschiedene Tools hinweg“ bedeutet AGENTS.md, „nur für eine bestimmte Aufgabentyp“ bedeutet eine Fähigkeit. Ihr Kontextfenster ist wie ein Budget – die Hauptdatei verbraucht einen Teil davon bei jeder Nachricht, während Fähigkeiten nur dann verbraucht werden, wenn sie genutzt werden. Planen Sie die Struktur daher entsprechend.