Wo jede Anweisung hingehört: AGENTS.md, CLAUDE.md und SKILL.md

Mehr als 4.300 Ingenieure haben ein einzelnes GitHub-Problem mit Upvotes unterstützt, in dem gefordert wird, dass Claude Code AGENTS.md ohne zusätzliche Hilfe lädt. Im Juli 2026, in Version 2.1.201, tut er dies immer noch nicht. Anthropics eigene Dokumentation zur Speicherverwaltung erklärt Entwicklern nun, wie man das Verhalten dennoch erzwingen kann: Man führt in einer Terminal-Sitzung „ln -s AGENTS.md CLAUDE.md“ aus. Im Grunde liefert der Anbieter eine Workaround-Lösung für eine Datei, die sein eigenes Tool weigert sich zu lesen.

Der Argumentationsteil ist der weniger interessante Teil. Die eigentliche Ingenieurskunst zeigt sich in einer Zeile des claude-api SKILL.md im öffentlichen Skills-Repositorium von Anthropic, genauer gesagt im Beschreibungsfeld des YAML-Frontmatters. Im Gegensatz zu CLAUDE.md und AGENTS.md entscheidet diese Beschreibung darüber, ob Claude überhaupt den Rest der Datei liest. Es sind drei Dateien sowie drei Lademodelle beteiligt, und die Frage nach dem Platzierungsort beantwortet sich bereits, sobald das Entscheidungskriterium sichtbar wird.

Wie die Trennung zustande kam

Die Zeitlinie zeigt, wie die Branche zu diesem Punkt gelangt ist. Im August 2025 wurde die AGENTS.md-Spezifikation als universelles Satz an Anweisungen für KI-Code-Assistenten veröffentlicht. Build-Befehle, Testsregeln und Projektarchitekturen konnten an einem Ort gespeichert werden; die Idee war, dass sowohl Cursor, Copilot als auch eigenständige Agenten diese einzige Datei nutzen würden.

Zwei Monate später, im Oktober 2025, stellte Anthropic Agent Skills vor, das einen anderen Ansatz für den Umgang mit Kontexten verfolgte. Anstelle einer einfachen Markdown-Datei mit Regeln handelt es sich bei einer „Skill“ um einen Ordner mit eigenen Metadaten, Skripten und Referenzdokumenten.

Bis Dezember 2025 waren beide Formate zu offenen Standards geworden. Die Spezifikation für Fähigkeiten wurde auf agentskills.io veröffentlicht, während die AGENTS.md-Spezifikation an die Linux Foundation als Leitprojekt für die Agentic AI Foundation übergeben wurde. Über 60.000 Repositorien sowie etwa ein Dutzend Tools unterstützen AGENTS.md bereits aus der Box heraus, sodass keiner der Standards verschwinden wird.

Dadurch schreiben Teams heute dieselben Anweisungen an drei Orten: eine AGENTS.md für den Editor, eine CLAUDE.md für die Terminal und eine SKILL.md für komplexe Workflows. Danach wundern sie sich, warum die Agenten langsamer werden und die Kosten für Tokens steigen. Die Lösung beginnt damit, wie diese Tools tatsächlich Text parsen.

Die Zugangskontrolle für eine Fähigkeit

Eine Sitzung beginnt nicht damit, dass der Agent alle Dateien im Projekt liest, da dies das Kontextfenster erschöpfen und die Aufmerksamkeit des Modells schwächen würde. Stattdessen sucht er nach bestimmten Eingangspunkten sowie nach Fähigkeiten, bei denen ein schrittweises Offenbaren von Inhalten angewandt wird.

Zu Start lädt der Agent die Metadaten jeder installierten Fähigkeit in den Systemprompt. Zu diesen Metadaten gehören ein Name und eine Beschreibung, was etwa 100 Token pro Fähigkeit kostet. Anschließend liest der Agent die Anfrage des Benutzers, vergleicht sie mit den geladenen Beschreibungen und entscheidet, ob der Inhalt einer Fähigkeit angezeigt werden soll. Die Beschreibung dient dabei als Schutzmechanismus, wobei das Referenzmaterial dahinter gesperrt bleibt.

Unten finden Sie das Frontmatter der claude-api-Fähigkeit, wie es im offenen Repository von Anthropic veröffentlicht wurde.

---
name: claude-api
description: |
  Reference for the Claude API / Anthropic SDK — model ids, pricing, params,
  streaming, tool use, MCP, agents, caching, token counting, model migration.
  TRIGGER — read BEFORE opening the target file; don't skip because it "looks
  like a one-liner" — whenever: the prompt names Claude/Anthropic in any form
  (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`,
  `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/
  model choice/limits/caching) — never answer from memory; OR the task is
  LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/
  RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/
  converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens).
  SKIP only when another provider is being worked on (overrides all triggers):
  OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR
  `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|
  cohere|ollama'` over the project hits (run this grep FIRST if no provider
  named — don't Read the file).
license: Complete terms in LICENSE.txt
---

# Claude API reference

Model IDs, pricing, request/response shapes, tool use, MCP, caching,
streaming, and migration notes for the Anthropic SDK.

... (body continues; only loaded if the description above passes the gate)

Das Beschreibungsfeld erfüllt eine doppelte Funktion. Es teilt dem Agenten mit, was die Fähigkeit kann, und dient gleichzeitig als Programmierinterface, über das der Autor der Fähigkeit die Auslöselogik kodiert.

TRIGGER und SKIP sind Konventionen und keine im Schema definierten Felder. Der Autor schreibt einfach Anweisungen in gewöhnlicher Sprache darüber, wann das Schaltfeld geöffnet werden soll. Der Inhalt dieser Fähigkeit umfasst Hunderte von Zeilen an API-Referenzen. Eine Frage bezüglich einer Postgres-Datenbank scheitert an der Beschreibungskontrolle, und der Referenztext bleibt ungeladen.

CLAUDE.md und AGENTS.md verhalten sich anders. Sie haben kein äquivalentes Schaltfeld. Sobald ein Agent sie auf dem Pfad findet, injiziert er sie zu Beginn der Sitzung, und sie bleiben während des gesamten Gesprächs bestehen.

Was gehört in welche Datei

Das Lademodell bestimmt den Inhalt. Eine injizierte Datei sollte nur das enthalten, was der Agent in jeder Runde benötigt. Eine gesperrte Datei sollte spezialisierte Kenntnisse enthalten, die für bestimmte Aufgaben gelten.

Ein Repository namens Orchard zeigt, wie diese Dateien ohne Informationsdoppelungen auf der Festplatte koexistieren können.

orchard/
├── AGENTS.md                          # root: shared, tool-agnostic project context
├── CLAUDE.md                          # 6 lines: imports + Claude-specific memory tiers
├── README.md                          # for humans
├── .github/
│   └── workflows/
│       └── skills-to-agents.yml       # dave1010/skills-to-agents@v2 → emits <skills> block into AGENTS.md
├── .agents/
│   └── skills/
│       └── db-migration/
│           ├── SKILL.md               # YAML frontmatter + body; loads only when description gate matches
│           ├── scripts/
│           │   └── check_reversibility.py
│           └── references/
│               └── postgres-lock-modes.md
├── services/
│   └── payments/
│       └── AGENTS.md                  # nested: subproject-specific rules; nearest-file-wins
└── packages/
    └── ui/

AGENTS.md enthält die gemeinsamen Build-Regeln, einschließlich Stilrichtlinien, die Struktur des Monorepos, Anleitungen zum Ausführen von Tests sowie Hinweise zu Abhängigkeiten. Es bildet den Grundkontext, den jedes Agent benötigt – unabhängig davon, welches Tool ihn liest. Sein charakteristisches Verhalten ist die Priorisierung des nächstgelegenen Files: Ein Agent, der in services/payments/ arbeitet, liest zunächst das dort befindliche AGENTS.md und bevorzugt dessen lokale Regeln gegenüber denen des Wurzelverzeichnisses. OpenAI verwaltet seinen internen Kontext mit einem solchen 88-Dateien umfassenden Monorepo-Muster, wobei die verschachtelten Dateien durch das Laden nur dessen, was der aktuelle Ordner benötigt, die Struktur übersichtlich halten.

CLAUDE.md hat eine engere Aufgabe. Es enthält Anweisungen, die nur dann Sinn ergeben, wenn das aktive Agent Claude Code ist.

Bloat ist das häufige Problem bei CLAUDE.md-Dateien. Entwickler fügen ihren gesamten AGENTS.md-Inhalt in CLAUDE.md ein, in der Annahme, Claude benötige eine eigene Kopie der Build-Regeln. Die richtige minimale Form hingegen importiert die gemeinsame Standardversion in Claudes Kontext.

# Project instructions for Claude Code

@AGENTS.md

## Claude-specific

- Prefer `Explore` subagent for cross-file searches over 3 files; single grep otherwise.
- User-level memory lives at ~/.claude/CLAUDE.md — do not duplicate its rules here.

<!--
Alternative if you do not want an @ import and prefer one file on disk:

    ln -s AGENTS.md CLAUDE.md

This is Anthropic's own recommendation for repos that keep AGENTS.md canonical
and have nothing Claude-specific to add. See docs.claude.com/en/docs/claude-code/memory.
-->

Eine Regel, die für mehrere Tools gilt, sollte in AGENTS.md aufgeführt werden. Die Import-Anweisung @AGENTS.md ist das empfohlene Muster in Anthropics Dokumentation zur Speicherverwaltung, während ein Symbollink als Ersatz dient, wenn in einem Repository nichts speziell für Claude hinzugefügt werden muss und lediglich das Tool den Standarddateiinhalt lesen soll.

SKILL.md dient als schichtbasierte Struktur für bedingte Fähigkeiten, wiederkehrende Arbeitsabläufe, einmalige Funktionen sowie tiefgehendes Fachvokabular. In orchard enthält .agents/skills/db-migration/ alles, was benötigt wird, um eine Postgres-Migration sicher durchzuführen – genauer gesagt ein Python-Skript zur Überprüfung der Umkehrbarkeit sowie eine Markdown-Anmerkung zu den Lock-Modi von Postgres. All das gehört nicht in AGENTS.md. Ein Agent, der eine CSS-Datei im UI-Paket bearbeitet, sollte in seinem Systemprompt keine Informationen zu Lock-Modi erhalten. Die Beschreibungsregel stellt sicher, dass die entsprechende Fähigkeit nur geladen wird, wenn eine Migration-Datei verändert wird.

Eine Routing-Regel

Sobald die Lademodelle verfügbar sind, wird das Hinzufügen neuer Kontexte mechanisch ablaufen:

• Der gemeinsame, tool-unabhängige Projektkontext, der bei jedem Schritt benötigt wird, kommt in AGENTS.md hin.
• Anweisungen, die ausschließlich für Claude Code bestimmt sind, werden in CLAUDE.md aufgenommen – idealerweise als kurzes File, das AGENTS.md importiert.
• Situative Workflows, Skripte und Domänenzuordnungen, die nur für bestimmte Aufgaben benötigt werden, kommen in eine Skill, hinter einer Beschreibung, die angibt, wann sie geöffnet werden soll.

Der Schutz des ständig aktiven Budgets

Der Unterschied zwischen bedingtem und ständig aktiven Laden hängt direkt von der Leistung des Agents ab.

Eine im Januar 2026 veröffentlichte Studie (arXiv:2601.20404) von Forschern des King’s College London, der Singapore Management University, der Heidelberg University und der Universität Bamberg untersuchte, was AGENTS.md-Dateien tatsächlich leisten. Die Laufzeit der Agenten verringerte sich um 28,64 Prozent und die Anzahl der erzeugten Tokens um 16,58 Prozent, während die Aufgaben in ähnlichem Tempo erledigt wurden. Eine gemeinsame Anweisungsschicht macht die Agenten effizienter. Sie müssen keine Build-Befehle mehr erfinden oder falsche Testsets ausführen, da das Modell die kanonischen Regeln einmal liest und direkt mit der Aufgabe fortfährt.

Diese Effizienz besteht nur solange der Kontext relevant bleibt. Jedes Token, das in den Systemprompt eingefügt wird, zieht die Aufmerksamkeit des Modells auf sich. Angenommen, ein Team klebt einen 500-Wort-Leitfaden zu Datenbank-Migrationen in das Root-Datei AGENTS.md ein. Der Agent muss ihn dann beim Beheben eines Frontend-Fehlerzustands lesen und seine Aufmerksamkeit auf die Lock-Modi von Postgres richten, anstatt über React Hooks nachzudenken.

Konditionales Laden schützt diese Vorteile. Das Verschieben situativer Workflows in SKILL.md hält das Root-Datei AGENTS.md übersichtlich, was die Vorteile eines gemeinsamen Kontexts bei der Ausführung bewahrt und verhindert, dass Ressourcen für nicht anwendbare Anweisungen aufgewendet werden.

Die existierende Brücke und die fehlende

Im Ökosystem gibt es eine Übersetzungslücke. Claude Code versteht Fähigkeiten sowie deren Offenbarungsschwellen, doch Cursor, Copilot und eigenständige CLI-Tools verstehen die Struktur .agents/skills/ nicht nativ.

Ein Team, das eine Datenbank-Migrationsskilled entwickelt hat, möchte, dass auch Cursor-Nutzer davon profitieren. Die manuelle Eingabe der Skill in AGENTS.md würde die einzige zuverlässige Quelle aufheben, daher ist die Lösung die Kompilierung.

Nicht-Claude-Agenten können so die Skills ohne manuelle Duplikation einsehen. Der generierte Block, wie er in orchard’s AGENTS.md erscheint, sieht so aus.

# Project agents

Build with `pnpm build`. Test with `pnpm test`. Migrations under
`services/payments/migrations/` must run through the db-migration skill.

## Style

- TypeScript 5.x, strict mode on. No `any` in new code.
- Errors surface as structured `AppError` with a `code` field, never raw strings.

<!-- BEGIN skills-to-agents (auto-generated; edit .agents/skills/*/SKILL.md) -->
<skills>
  <skill name="db-migration" path=".agents/skills/db-migration/">
    Run a Postgres migration end-to-end. TRIGGER whenever the user asks to
    add/modify a migration, backfill a column, or lock-analyze a schema
    change. SKIP if the query is purely a read-only SELECT / EXPLAIN.
  </skill>
  <skill name="release-notes" path=".agents/skills/release-notes/">
    Draft the release notes for a merged PR. TRIGGER on "cut a release",
    "write release notes", or "prep the changelog". SKIP if the PR is a
    dependency bump.
  </skill>
</skills>
<!-- END skills-to-agents -->

## Repo layout

- `services/` — deployable services, each with its own AGENTS.md
- `packages/` — shared libraries
- `.agents/skills/` — Conditional workflows

Die Brücke gibt den Namen, den Pfad und die Beschreibung jeder Fähigkeit an. Nicht-Claude-Agenten verfügen nicht über eine eingebaute schrittweise Anzeige dieser Verzeichnisse, weshalb die Zusammenfassung im Fähigkeitsblock als ihre Schnittstelle dient: Ein Tool, das AGENTS.md liest, findet diesen Block, liest die Auslösebedingungen und ermittelt, wo auf der Festplatte nach Informationen zur Migration gesucht werden muss.

Die noch fehlende Brücke besteht darin, dass Claude Code AGENTS.md direkt lesen könnte, ohne Import oder Symbolverknüpfung. Auf Manifold wird weiterhin ein Prognosemarkt darüber geführt, ob Anthropic bis Ende des Jahres eine solche Unterstützung einbauen wird. Die Lücke deutet darauf hin, dass Tool-Entwickler ihre eigene Kontextschicht kontrollieren möchten. Anthropic besitzt CLAUDE.md, während die Community AGENTS.md kontrolliert. Die gegenseitige Kompatibilität wird weiterhin von den verwendeten Tools und CI-Pipelines abhängen, nicht von spezifischen Vorgaben.

Das System am Ende

Ein Überblick über das Monorepo des Obstgartens zeigt eine funktionierende Struktur. Ingeschachtelte AGENTS.md-Dateien enthalten die gemeinsamen strukturellen Regeln. Ein einzeiliger CLAUDE.md-Datei kümmert sich um die für Claude spezifischen Importe. Die db-migration SKILL.md wartet hinter ihrer Beschreibungstür darauf, dass eine Datenbankaufgabe sie auslöst, und der GitHub Action verbindet alles miteinander, sodass kein Entwickler dieselbe Regel zweimal schreibt.