AGENTS.md vs. CLAUDE.md vs. Skills: Was gehört wohin

AGENTS.md ist eine einfache Markdown-Datei im Stammverzeichnis deines Repositories, die Coding-Agenten sagt, wie sie in deinem Projekt arbeiten sollen: wie man es baut, wie man die Tests laufen lässt, welche Konventionen zu befolgen sind, was in Ruhe zu lassen ist. Kein Schema, keine Pflichtabschnitte, keine Registry. Der ganze Standard passt in einen Satz: Leg eine Datei namens AGENTS.md in dein Repo, und Agenten, die die Konvention unterstützen, lesen sie, bevor sie deinen Code anfassen.

Leute nennen es das "README für Agenten", und der Vergleich hält stand. Ein README erklärt dein Projekt Menschen, die gerade angekommen sind. AGENTS.md erklärt es Software, die gerade angekommen ist. Der Unterschied ist, dass der Agent die Anweisungen tatsächlich befolgt, vage Anweisungen kosten also echtes Geld in verschwendeten Tokens und falschen Änderungen.

Wir testen Agent-Tooling beruflich bei SkillProof, und wir haben beobachtet, wie diese Datei von einem Nebenprojekt des OpenAI-Codex-Teams zum Nächsten wurde, was agentisches Programmieren einem gemeinsamen Standard am nächsten hat. Dieser Beitrag behandelt, wie sie sich zu CLAUDE.md und den anderen Tool-Dialekten verhält, und wo Skills reinpassen, denn sie lösen ein anderes Problem, als die meisten annehmen.

Was AGENTS.md ist, und wer sie wirklich liest

Die Konvention kam Mitte 2025 aus OpenAIs Codex-Team und wurde schnell von Googles Jules, Cursor, Factory, Amp und anderen mitgetragen. Der Pitch war einfach: Jeder Agenten-Anbieter hatte seine eigene Anweisungsdatei erfunden, und Repository-Wurzeln füllten sich mit fast identischem Markdown, adressiert an unterschiedliche Roboter. AGENTS.md schlug einen Dateinamen vor, den alle lesen.

Die Adoption seither ist real, aber ungleichmäßig. Hier die ehrliche Karte, wie wir sie Mitte 2026 sehen:

Tool	Liest AGENTS.md	Nativer Dialekt
OpenAI Codex	Ja, nativ	Keiner, AGENTS.md ist das Format
GitHub Copilot (Coding Agent, VS Code)	Ja	.github/copilot-instructions.md
Cursor	Ja	.cursor/rules/*.mdc
Google Jules	Ja, nativ	Keiner
Gemini CLI	Ja, über Config	GEMINI.md
Claude Code	Nicht nativ	CLAUDE.md
Zed	Ja	Keiner
Amp	Ja	Keiner
Aider	Nein	CONVENTIONS.md
Windsurf	Nein	.windsurf/rules/

Zwei Dinge fallen in dieser Tabelle auf. Erstens ist die Spalte der "Ja"-Antworten lang und wird länger; wenn 2026 ein neuer Agent erscheint, steht AGENTS.md-Unterstützung meist in den Launch-Notes. Zweitens sind die Dialekte nicht verschwunden. Copilot liest weiterhin seine eigene Instructions-Datei, Cursor hat weiterhin Rules mit Globs und Trigger-Modi, die AGENTS.md nicht ausdrücken kann, und Claude Code, das Tool, mit dem wir die meiste Zeit verbringen, will weiterhin eine CLAUDE.md.

Die praktische Lage ist also: AGENTS.md ist die Lingua Franca, die Dialekte sind, wo toolspezifische Macht lebt, und jedes Team, das mehr als einen Agenten betreibt, braucht eine Policy, um sie synchron zu halten. Diese Policy ist der Großteil dieses Artikels.

Was in die Datei gehört, ist weniger umstritten, als der Dateiname es war. Die AGENTS.md-Dateien, die funktionieren, decken Setup- und Build-Befehle ab, wie man Tests laufen lässt, Code-Style-Hinweise, die der Linter nicht erfasst, und architektonische Grenzen ("Payment-Logik lebt in packages/billing, leg sie nirgendwo sonst hin"). Die Dateien, die nicht funktionieren, lesen sich wie Mission Statements. Ein Agent muss nicht wissen, dass dir sauberer Code wichtig ist. Er braucht den Befehl, der prüft, ob der Code sauber ist.

AGENTS.md vs. CLAUDE.md

Diese beiden Dateien erledigen fast denselben Job für unterschiedliche Leser. Beide sind Anweisungsdateien auf Projektebene. Beide laden zu Sessionbeginn in den Kontext. Beide sollten kurz sein, weil jede Zeile jeden Request Tokens kostet. Hast du schon eine gute CLAUDE.md geschrieben, weißt du bereits, wie man eine gute AGENTS.md schreibt, und unser Rat in CLAUDE.md Best Practices überträgt sich fast Zeile für Zeile.

Die Unterschiede lohnt es sich zu kennen, bevor du sie vereinheitlichst:

Zielgruppe. CLAUDE.md wird von genau einem Tool gelesen. Das heißt, sie kann gefahrlos Claude-spezifische Maschinerie referenzieren: Skills, Hooks, Subagenten, MCP-Server, Berechtigungseinstellungen. Eine AGENTS.md, die sagt "nutze den systematic-debugging-Skill, bevor du einen Fix vorschlägst", ist Rauschen für Codex und Copilot, die keine Ahnung haben, was ein Skill ist.

Hierarchie und Imports. Claude Code führt CLAUDE.md-Dateien aus mehreren Ebenen zusammen (nutzerglobal, Projektwurzel, Unterverzeichnisse) und unterstützt @pfad/zur/datei-Imports darin. AGENTS.md unterstützt ebenfalls Verschachtelung, wobei die nächstgelegene Datei Vorrang hat, aber die Import-Syntax ist Claudes eigene.

Durchsetzung. Keine der beiden Dateien wird durchgesetzt. Beide sind Vorschläge an ein Sprachmodell. Alles, was garantiert jedes Mal passieren muss, gehört in einen Hook oder CI, nicht in eine der beiden Dateien. Das enttäuscht Leute bei allen Tools gleichermaßen.

Wenn dein Team Claude Code neben etwas anderem nutzt, brauchst du beide Dateien, und der Fehlermodus ist offensichtlich: zwei Dateien, die fast dasselbe sagen, driften auseinander, bis ein Agent der veralteten folgt. Zwei Muster verhindern das, und wir haben beide getestet.

Der Symlink. Mach AGENTS.md zur echten Datei und lass CLAUDE.md darauf verweisen:

# AGENTS.md is the source of truth
ln -s AGENTS.md CLAUDE.md
git add AGENTS.md CLAUDE.md

Claude Code folgt dem Symlink und liest den Inhalt, als wäre er seine eigene Datei. Das ist die Null-Wartungs-Option, und sie ist die richtige, wenn du nichts Claude-Spezifisches zu sagen hast. Ihre Grenze ist exakte Identität: Beide Leser bekommen jedes Wort, einschließlich der Wörter, die nur für den anderen relevant sind.

Der dünne Wrapper. Behalte AGENTS.md als gemeinsame Quelle, und mach CLAUDE.md zu einer kleinen Datei, die sie importiert und Claude-eigene Zeilen ergänzt:

# CLAUDE.md
@AGENTS.md

## Claude-specific
- Use the git-workflow skill for commits and PRs.
- Never edit files under infra/ without asking.

Das ist, was wir in unseren eigenen Repos betreiben. Die gemeinsamen Fakten leben einmal, die Claude-Extras leben, wo nur Claude sie sieht, und ein Diff an AGENTS.md aktualisiert jedes Tool im selben Moment. Dasselbe Muster funktioniert umgekehrt für andere Dialekte: Halte .github/copilot-instructions.md und Cursor-Rule-Dateien auf ein paar Zeilen, die auf AGENTS.md verweisen für alles, was beide Tools brauchen. Wir haben diese Dialekte im Detail verglichen in Claude Skills vs. Cursor Rules und Claude Skills vs. Copilot Instructions.

Eine Warnung aus unseren Tests: Egal welches Muster du wählst, wähle eines. Repos, die eine vollständige CLAUDE.md und eine vollständige AGENTS.md mit unabhängig editiertem Inhalt tragen, sind das Drift-Szenario mit Extraschritten.

AGENTS.md vs. Skills: völlig andere Schichten

Das ist der Vergleich, nach dem Leute tatsächlich suchen, und er basiert auf einem Kategorienfehler. AGENTS.md und Skills sind keine konkurrierenden Formate. Sie sitzen auf unterschiedlichen Schichten des Stacks und beantworten unterschiedliche Fragen.

AGENTS.md beantwortet: Was sollte irgendein Agent über dieses Projekt wissen? Es sind Fakten über einen Ort. Es reist mit dem Repository, gilt für welchen Agenten auch immer auftaucht, und sagt nichts darüber, wie der Agent seinen Job erledigt, jenseits lokaler Regeln.

Ein Skill beantwortet: Wie sollte dieser Agent diese Art von Aufgabe ausführen? Es ist ein Verhalten, verpackt in einem Ordner mit einer SKILL.md, bedarfsweise geladen, wenn die Aufgabe zu seiner Beschreibung passt. Es reist mit dir, nicht mit dem Repo. Installier einen Debugging-Skill einmal, und er funktioniert in jedem Projekt, das du öffnest, egal ob dieses Projekt je von dir gehört hat. Wir haben die Mechanik in Was sind Claude Skills? behandelt, aber das Lademodell ist der Schlüsselunterschied: AGENTS.md-Inhalt sitzt für die ganze Session im Kontext, während ein Skill etwa hundert Tokens Metadaten kostet, bis eine Aufgabe ihn triggert.

Hier der volle Stack, wie wir ihn an Whiteboards zeichnen:

Schicht	Lebt in	Gescopt auf	Geladen	Frage, die sie beantwortet
AGENTS.md	Repo-Wurzel	Das Projekt, jeder Agent	Jede Session	Was ist dieser Ort?
Tool-Dialekt (CLAUDE.md, Rules)	Repo oder Nutzerkonfig	Das Projekt, ein Tool	Jede Session	Was sollte dieses Tool hier tun?
Skills	~/.claude/skills/ oder .claude/skills/	Ein Agent, jedes Projekt	Bedarfsweise	Wie wird diese Art von Aufgabe erledigt?
MCP-Server	Tool-Konfig	Eine Maschine oder ein Team	Tool-Definitionen immer im Kontext	Was kann der Agent erreichen?

Lies das von oben nach unten als wachsende Fähigkeit und schrumpfende Portabilität. Die Standarddatei ist universell und dumm. Der Dialekt ist toolgebunden und etwas schlauer. Skills sind verhaltensreich, aber derzeit agentgebunden. MCP ist lebende Infrastruktur mit Zugangsdaten und Prozessen.

Ein konkretes Beispiel macht die Grenze offensichtlich. "Führ pnpm test --filter=changed vor jedem Commit aus" ist eine AGENTS.md-Zeile: Es ist eine Tatsache über dein Repo, wahr für jeden Agenten. "Reproduziere beim Debuggen den Fehler, bevor du einen Fix vorschlägst, und behaupte nie, ein Fix funktioniere, ohne den fehlschlagenden Test erneut laufen zu lassen" ist ein Skill, und tatsächlich einer, den wir getestet und gelistet haben: systematic-debugging. Er hat nichts mit einem bestimmten Repo zu tun. Ihn in AGENTS.md zu packen bedeutet, ihn unverändert in jedes Projekt zu kopieren und seine Token-Kosten in jeder Session zu bezahlen, auch in Sessions, in denen niemand debuggt.

Die Faustregel, die wir Teams geben: Würdest du eine Zeile unverändert in ein zweites Repo kopieren, ist es kein Projektkontext, es ist Verhalten, und es gehört in einen Skill. Ergibt eine Zeile nur in diesem Repo Sinn, ist es Kontext, und es gehört in AGENTS.md.

Die Strategie für Teams mit mehreren KI-Tools

Die meisten Teams, mit denen wir 2026 sprechen, sind keine Single-Agent-Läden. Ein typischer Mix ist Claude Code für schwerere Arbeit, Copilot im Editor und Cursor auf ein paar Rechnern der Standhaften. Hier die Konfiguration, die den Kontakt damit übersteht:

1. Schreib AGENTS.md als Quelle der Wahrheit. Eine Datei, im Repo-Stamm, behandelt wie Code. Leg jede Tatsache hinein, die irgendein Agent braucht: Befehle, Konventionen, Grenzen, Warnungen. Reviewe Änderungen daran in PRs, denn eine falsche Anweisung hier führt jeden Agenten deines Teams in die Irre.

2. Halte die Dialekte dünn. CLAUDE.md importiert AGENTS.md und ergänzt nur Claude-spezifische Zeilen. Copilot Instructions und Cursor Rules bekommen dieselbe Behandlung: ein Verweis plus, was sich wirklich nicht in der gemeinsamen Datei ausdrücken lässt. Unser Test für "dünn genug" ist unverblümt: Übersteigt eine Dialekt-Datei einen Bildschirm, gehört darin wahrscheinlich etwas in AGENTS.md oder in einen Skill.

3. Leg wiederverwendbares Verhalten in Skills. Debugging-Disziplin, Commit- und PR-Gewohnheiten, Test-Schreibstandards, Dokumentformatierung. Die gehören in keine Pro-Repo-Datei, weil sie nicht pro Repo sind. Installier sie einmal pro Agent, und sie begleiten dich überallhin. Unsere getesteten Empfehlungen für Coding-Arbeit sind in den besten Coding-Skills gesammelt, und git-workflow ist der, den wir zuerst bei jedem Team installieren würden, dem Commit-Hygiene wichtig ist.

4. Setz mit Hooks und CI durch, nicht mit Prosa. Alles, was zu 100 % passieren muss, kann nicht in einer Markdown-Datei leben, die von einem probabilistischen System gelesen wird. Formatierung beim Speichern ist ein Hook. Tests vor dem Merge sind CI. Die Markdown-Schichten sind für Urteilsvermögen, nicht für Durchsetzung.

Dieses Layout hat eine Eigenschaft, die es zu nennen lohnt: Jede Schicht ändert sich in ihrem eigenen Tempo. AGENTS.md ändert sich, wenn sich das Projekt ändert, Skills ändern sich, wenn sich das Handwerk deines Teams ändert, und kein Agent liest etwas, das an einen anderen Agenten adressiert ist.

Wird sich ein Standard durchsetzen?

Unsere Einschätzung, mit dem Standardbeobachter-Hut auf: Die Dateiebene wird konvergieren, die Verhaltensebene nicht.

Die Dateiebene konvergiert, weil die Anreize alle in eine Richtung zeigen. Eine Kontextdatei hat geringe Angriffsfläche, Anbieter gewinnen Kompatibilität für die Kosten einer Dateinamenprüfung, und Repo-Besitzer sind sichtbar müde von Anweisungsdatei-Wildwuchs. Wir erwarten native AGENTS.md-Unterstützung in Claude Code irgendwann, weil der Druck öffentlich ist und die Kosten der Unterstützung ein Dateilookup sind. Passiert das, wird das Symlink-Muster oben zu einem No-Op, den du löschen kannst.

Die Verhaltensebene ist eine andere Geschichte. Skill-artige Mechanismen tauchen überall auf: Claudes Skills, Cursors Rule-Modi, Copilots Prompt-Dateien, diverse "Playbook"-Features bei kleineren Agenten. Sie reimen sich, aber jeder kodiert die eigenen Ideen seines Anbieters über Triggering und Scoping. Die Trigger-Beschreibung und progressive Ladung eines Skills bilden sich auf einen Cursor-Rule-Glob etwa so gut ab wie eine Symphonie auf einen Klingelton. Verhaltensformate sind, wo sich Anbieter differenzieren, sie haben also jeden Grund, weiter auseinanderzudriften.

Und hier ist der Teil, den Anbieter nicht in Launch-Posts schreiben: Portabilität des Formats ist nicht Portabilität der Qualität. Eine ungetestete Verhaltensdatei scheitert auf jedem Tool, das sie lädt, auf dieselbe Weise. Sie triggert, wenn sie nicht sollte, oder nie. Etwa die Hälfte der Community-Skills, die wir von GitHub ziehen, scheitert unseren ersten Testdurchlauf, und die Fehlerursachen sind formatunabhängig: vage Trigger-Beschreibungen und Anweisungen, die der Autor nie gegen ein echtes Tool verifiziert hat. Wir haben das Muster in warum die Hälfte der Claude Skills nicht funktioniert aufgeschrieben, und alles darin gilt für das, was auch immer dein anderer Agent seine Version von Skills nennt. Ein konvergierter Standard würde uns einen Dateinamen und dieselbe alte Fehlerrate geben.

Also: Standardisiere deine Fakten, denn das Ökosystem standardisiert mit dir. Sei dann wählerisch bei deinen Verhalten, denn niemand standardisiert Qualität.

FAQ

Liest Claude Code AGENTS.md?

Nicht nativ, Stand Mitte 2026. Claude Code sucht nach CLAUDE.md. Die Standard-Workarounds sind ein Symlink (ln -s AGENTS.md CLAUDE.md) oder eine dünne CLAUDE.md, die die gemeinsame Datei mit @AGENTS.md importiert. Beides funktioniert; die Import-Version gibt dir zusätzlich einen Platz für Claude-eigene Anweisungen.

Sollte AGENTS.md meine CLAUDE.md ersetzen?

Ersetze ihren Inhalt, behalte die Datei. Verschieb alles Tool-Agnostische nach AGENTS.md, dann schrumpf CLAUDE.md auf einen Import plus Claude-spezifische Zeilen zu Skills, Hooks und Berechtigungen. CLAUDE.md ganz zu löschen ergibt nur mit dem Symlink-Ansatz Sinn, wo beide buchstäblich dieselben Bytes sind.

Kann ich skill-artige Anweisungen in AGENTS.md statt Skills zu installieren?

Du kannst, und für ein einzelnes kleines Repo ist das in Ordnung. Die Kosten zeigen sich bei Skalierung: Die Anweisungen laden in jeder Session, ob relevant oder nicht, und sie begleiten dich nicht zu anderen Projekten. Andere Agenten, die die Datei lesen, bekommen auch Verhaltensanleitung, die für Claude geschrieben wurde. Verhalten, das du repoübergreifend wiederverwenden würdest, gehört in einen Skill.

Wie lang sollte eine AGENTS.md sein?

Kurz genug, dass jede Zeile ihre Kontextkosten verdient. Die meisten guten, die wir überprüft haben, sind 30 bis 80 Zeilen. Ist deine mehrere Hundert Zeilen lang, trägt sie wahrscheinlich Verhaltensinhalt, der in Skills gehört, oder Referenzmaterial, das ein verlinktes Dokument sein sollte, das der Agent bedarfsweise liest.

Funktionieren Unterverzeichnis-AGENTS.md-Dateien?

Ja, die Konvention unterstützt Verschachtelung: Die Datei am nächsten zum bearbeiteten Code gewinnt für diesen Bereich. Monorepos nutzen das, um Paketen ihre eigenen Build- und Testbefehle zu geben. Behalte die Root-Datei für repoweite Fakten und schieb Paketspezifika nach unten. Claude Code wendet dieselbe Nächste-Datei-Logik auf CLAUDE.md an, das Wrapper-Muster verschachtelt sich also sauber.