CLAUDE.md, SKILL.md und MCP: Welche Schicht enthält welche Anweisungen

Neuere Nutzer von Claude Code und ähnlichen Programmier-Assistenten machen im ersten Monat oft denselben Fehler. Sie öffnen CLAUDE.md und tippen weiter: Stilrichtlinien, Bereitstellungsanleitungen, Überprüfungslisten, rohe Datenbank-Schemata – bis die Datei 600 oder 900 Zeilen umfasst. Die Annahme ist, dass mehr Kontext zu Beginn den Assistenten intelligenter macht.

Doch das Gegenteil ist der Fall. Das Arbeitsgedächtnis wird überlastet, die Antworten werden ungenauer, und Anfragen, die zuvor funktionierten, funktionieren plötzlich nicht mehr. Irgendetwas stimmt nicht, doch es fällt schwer zu sagen, was genau. Bei jeder einfachen Anfrage muss das Modell zunächst durch Hunderte von Zeilen irrelevanter Anweisungen waten, bevor es zu einer einzigen Codezeile gelangt. Weder das Modell noch die Anfrage sind schuld – es wurde einfach von einer einzigen Textdatei verlangt, drei verschiedene Aufgaben zu erledigen.

Moderne Kodierungsagenten funktionieren am besten, wenn die Anweisungen in drei klare Schichten unterteilt werden: Projektregeln, die stets aktiv sind, Aufgabenspezifische Fähigkeiten, die nach Bedarf geladen werden, sowie Live-Verbindungen zu Tools über MCP. Durch diese getrennten Schichten erhält das Modell nur das, was es benötigt – und zwar genau zu dem Zeitpunkt, an dem es es braucht.

Warum drei Schichten?

Es ist berechtigt, sich zu fragen, warum drei Schichten und nicht eine große Datei oder zehn kleine, spezialisierte Dateien. Jede Schicht befasst sich mit einem anderen Problem, und die Überschneidungen zwischen den Problemen sind geringer als erwartet.

• CLAUDE.md kümmert sich um Dinge, die stets zutreffen müssen.
• SKILL.md kümmert sich um Dinge, die nur gelegentlich relevant sind.
• MCP kümmert sich um Daten, die bereits im Moment der Aufzeichnung veraltet sind.

Es handelt sich um drei unterschiedliche Fehlermodi und nicht um drei Varianten desselben. Wenn man die Fähigkeiten in CLAUDE.md integriert, entsteht eine überdimensionierte Datei, die bei jeder Sitzung vollständig geladen wird – unabhängig davon, ob ein Deployment-Checkliste benötigt wird. Jede weitere Ebene stellt letztendlich nur eine Unterteilung eines der drei Fehlermodi dar und keine neue Aufgabe.

Was gehört in CLAUDE.md oder AGENTS.md

Betrachten Sie CLAUDE.md als eine Notiz, die am ersten Tag für einen Entwickler hinterlassen wird. Es handelt sich dabei nicht um das vollständige Onboarding-Dokument, sondern nur um die wenigen ungeschriebenen Regeln, die bereits alle Teammitglieder kennen – wie zum Beispiel, dass hier keine Klassenkomponenten verwendet werden dürfen oder dass man niemals direkt auf die Datenbank zugreifen, sondern immer über die Service-Schicht arbeiten soll.

Die Datei befindet sich im Projektverzeichnis, und Claude Code liest sie automatisch zu Beginn jeder Sitzung. Niemand ruft sie auf oder bittet darum. Sie ist einfach vorhanden – genauso wie das Gedächtnis eines Menschen an die Teamkonventionen, wenn er sich an die Arbeit macht.

Gute Kandidaten sind Codierkonventionen, Projektstruktur, strenge Einschränkungen, Sicherheitsregeln wie das Vermeiden der Offenlegung von API-Schlüsseln im Code sowie die Rolle, die der Agent bei der Überprüfung der Arbeit einnehmen sollte.

Schlechte Kandidaten sind eine 40-stufige Bereitstellungsanleitung, ein Datenbankschema sowie alles, was nur alle zehn Tage relevant ist. In diese zweite Kategorie geraten die meisten Menschen, wenn sie Fehler machen. Wenn etwas nicht in jeder Sitzung gilt, gehört es vermutlich dort nicht hin. Ein CLAUDE.md, das versucht, alles zu sein, wird letztendlich zu einer langsamen, überdimensionierten Version von nichts.

Eine globale Version existiert außerdem unter ~/.claude/CLAUDE.md und gilt für jedes Projekt. Dort speichern die Menschen in der Regel persönliche Gewohnheiten wie den bevorzugten Stil von Commit-Nachrichten oder die Sprache für Antworten und legen projektbezogene Regeln im Projektfile ab.

Ein Datei, das seine Aufgabe erfüllt, sieht wie folgt aus und basiert auf einem weithin verbreiteten Satz an Verhaltensrichtlinien.

# CLAUDE.md

Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.

**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.

## 1. Think Before Coding

**Don't assume. Don't hide confusion. Surface tradeoffs.**

Before implementing:
- State your assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them - don't pick silently.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop. Name what's confusing. Ask.

## 2. Simplicity First

**Minimum code that solves the problem. Nothing speculative.**

- No features beyond what was asked.
- No abstractions for single-use code.
- No "flexibility" or "configurability" that wasn't requested.
- No error handling for impossible scenarios.
- If you write 200 lines and it could be 50, rewrite it.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

## 3. Surgical Changes

**Touch only what you must. Clean up only your own mess.**

When editing existing code:
- Don't "improve" adjacent code, comments, or formatting.
- Don't refactor things that aren't broken.
- Match existing style, even if you'd do it differently.
- If you notice unrelated dead code, mention it - don't delete it.

When your changes create orphans:
- Remove imports/variables/functions that YOUR changes made unused.
- Don't remove pre-existing dead code unless asked.

The test: Every changed line should trace directly to the user's request.

## 4. Goal-Driven Execution

**Define success criteria. Loop until verified.**

Transform tasks into verifiable goals:
- "Add validation" → "Write tests for invalid inputs, then make them pass"
- "Fix the bug" → "Write a test that reproduces it, then make it pass"
- "Refactor X" → "Ensure tests pass before and after"

For multi-step tasks, state a brief plan:
```
1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]
```

Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

---

**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

Es ist kurz und präzise, und es muss nächste Woche nichts daran überarbeitet werden. So sieht es aus, wenn etwas schiefgeht – ein Muster, das in frühen Versionen häufig vorkommt.

# Project Notes

Our database has these tables: users, orders, products, sessions,

audit_log (schema pasted below, 340 lines)...

To deploy, first SSH into staging, then run these 47 commands...

Here's our Slack webhook URL for notifications: hooks.slack.com/...

When reviewing PRs, check for: [12 paragraphs of instructions]

Jeder Eintrag in diesem zweiten Beispiel ist für CLAUDE.md fehlerhaft – jeweils aus unterschiedlichen Gründen. Ein Schema wird veraltet, sobald jemand eine Spalte hinzufügt. Die Bereitstellungsanleitungen beschreiben nur eine einzige, benannte Aufgabe. Eine webhook-URL gilt als Geheimnis und sollte in einer Umgebungsvariable gespeichert werden, nicht im kommitionierten Markdown. Die Anweisungen zur PR-Überprüfung sind lediglich eine Fähigkeit, die in den Kleidern von CLAUDE.md erscheint.

Ein praktischer Test: Würde diese Aussage nach drei Monaten, an einem zufälligen Dienstag und während der Erledigung einer unverwandten Aufgabe immer noch zutreffen, wenn man sie erneut liest? Wenn nicht, gehört sie nicht in die Datei.

SKILL.md: Expertise, die nur bei Bedarf sichtbar wird

Agent Skills stammt von Anthropic aus dem Oktober 2025 und wurde so konzipiert, dass Anweisungen für eine bestimmte Aufgabe in einer Datei abgelegt werden können und bei Bedarf geladen werden, anstatt ständig im Kontext Platz einzunehmen. Im Dezember 2025 wurde dieses Format als unabhängiger Standard freigegeben, und andere Tools übernahmen es schnell. VS Code, Cursor, Googles Antigravity IDE, Gemini CLI, Goose sowie mehrere weitere Programmier-Agenten unterstützen nun dasselbe SKILL.md-Format, das auch Claude Code verwendet. Es handelt sich um denselben Standard, der MCP zum branchenweiten Standard für Tool-Verbindungen gemacht hat.

Die Idee ist nützlich, sobald man sie versteht: Nicht alle Kenntnisse müssen ständig im Kopf des Agenten vorhanden sein. Der größte Teil dessen, was ein Ingenieur weiß, wird nur für eine bestimmte Aufgabe relevant. Niemand erinnert sich während des Schreibens einer Hilfsfunktion an die Bereitstellungsüberprülliste. Fähigkeiten folgen derselben Logik. Ein Ordner mit einer SKILL.md-Datei bleibt ungenutzt, bis eine Anfrage wie „Überprüfe diesen PR“ eintrifft – in diesem Fall zieht Claude die tatsächliche Überprülliste heran.

Ein Skill-Datei beginnt mit einer kurzen Beschreibung, die als Frontmatter bezeichnet wird und angibt, was die Fähigkeit leistet und wann sie ausgelöst werden sollte. Wenn eine Nachricht übereinstimmt, lädt Claude den Rest der Datei. Falls nicht, nimmt dieser Inhalt keinen Platz in der Konversation ein. Deshalb wirken Skills leichter als wenn alles in CLAUDE.md untergebracht würde. Ein Skill für die Überprüfung von Pull-Requests, ein anderer für Datenbank-Migrationen und noch einer für Veröffentlichungsnotizen konkurrieren nicht um Platz, es sei denn, genau diese Aufgabe wird gerade ausgeführt.

.claude/skills/
├── code-review/
│   └── SKILL.md
├── pr-description/
│   └── SKILL.md
└── anti-sycophancy/
    └── SKILL.md

Projektbezogene Fähigkeiten befinden sich in .claude/skills/ innerhalb des Repositoriums. Persönliche Fähigkeiten, die dem Benutzer überall folgen sollten, befinden sich in ~/.claude/skills/. Diese Trennung spiegelt CLAUDE.md wider: projektbezogen versus global. Ein echtes Beispiel, gekürzt:

---
name: production-code-validation-checklist
description: "Run this checklist before pushing code to GitHub"
---

# Production Code Validation Checklist

**Run this checklist before pushing code to GitHub.**

This is not optional. This is how you prevent broken repositories.

## Secrets Audit
- [ ] Searched for: password, secret, token, key, api_key, credential
- [ ] All secrets are in environment variables or .env, not in code
- [ ] .env file is in .gitignore

## Failure Scenario Testing: Deliberately Break It
This is the most important step. Production code breaks. Can your code
handle it?
- [ ] Run without a required environment variable, does it fail with a
      clear error?
- [ ] Simulate a timeout on any HTTP request, does the code handle it?
- [ ] Feed it empty input, null input, and malformed input, one at a time

## Final Production Readiness Assessment
Choose ONE:
- [ ] PROTOTYPE: concept proven, not production ready
- [ ] DEVELOPMENT READY: works for development, not production
- [ ] PRODUCTION CANDIDATE: ready for real-world testing
- [ ] PRODUCTION VERIFIED: tested in a real environment, known to work

**If you cannot check a box, you are not done.**

Achten Sie darauf, was es vermeidet. Es hält weder Codierkonventionen noch ein Datenbankschema bereit. Es gibt nur eine benannte Aufgabe, die durch einen bestimmten Auslöser aktiviert wird – genau das macht es zu einer Fähigkeit und nicht zu einem kleineren CLAUDE.md. Die einfache Prüfung lautet: Ist etwas nur bei Ausführung einer spezifischen, benannten Aufgabe erforderlich? Wenn ja, handelt es sich um eine Fähigkeit und nicht um eine Regel.

MCP: Zugriff, nicht nur Wissen

CLAUDE.md und SKILL.md sind beide von Menschen verfasste Markdown-Dateien. MCP ist anders. Es verbindet Claude während seiner Ausführung mit Ressourcen außerhalb des Chats – sei es eine Datenbank, GitHub, Slack, das Dateisystem oder alles andere, was verbunden wurde.

In Projekten mit starkem Fokus auf RAG ist eine direkte Verbindung zu Chroma ein typischer Fall. Der offizielle chroma-mcp-Server stellt Sammlungen als Tools bereit, die Claude abfragen kann.

{
  "mcpServers": {
    "chroma": {
      "command": "uvx",
      "args": [
        "chroma-mcp",
        "--client-type", "persistent",
        "--data-dir", "/path/to/your/chroma/data"
      ]
    }
  }
}

In Claude Code erfolgt die Einrichtung mit einem einzigen Befehl, ohne manuelles Bearbeiten von JSON.

claude mcp add --scope project chroma \
  -- uvx chroma-mcp --client-type persistent --data-dir ./chroma-data

Es registriert den Server und schreibt die Konfiguration in .mcp.json im Projekt, das dann kommittiert werden kann, damit das gesamte Team dieselbe Verbindung erhält, ohne sie manuell konfigurieren zu müssen. Claude Code bietet drei Berechtigungsgrade an: lokal, was einen Benutzer auf einem Rechner bedeutet; projektbasiert, was eine im Repository gespeicherte und geteilte Konfiguration bedeutet; sowie benutzerbasiert, was alle Projekte umfasst, an denen eine Person arbeitet. Das gleiche Muster von projektbasiert gegen global tritt ein drittes Mal auf, was es leicht macht, sich daran zu erinnern, sobald man es bemerkt hat.

Das Protokoll hat sich so schnell entwickelt, dass dieser Wachstumstrend bereits zum Alltag gehört. Das offizielle Serververzeichnis listet mehr als 9.000 Server auf, und laut den von Anthropic bereitgestellten Zahlen stiegen die monatlichen Downloads des Referenz-SDKs von etwa 2 Millionen auf fast 100 Millionen in rund 16 Monaten. Es handelt sich dabei nicht mehr um eine Nischenfunktion. Jeder, der weiterhin ein Schema oder einen GitHub PR in einen Prompt einfügt, erledigt auf manuelle Weise das, was eine MCP-Verbindung in Echtzeit leistet – und die eingefügte Kopie wird unverzüglich veraltet, sobald sich etwas im Quellsystem ändert.

Eine Entscheidungshierarchie

1. Muss das in jeder Sitzung gelten, unabhängig von der Aufgabe? Wenn ja, fügen Sie es in CLAUDE.md ein. Wenn nein, gehen Sie weiter.
2. Handelt es sich um eine spezifische, benannte, wiederholbare Aufgabe mit eigenen Schritten? Wenn ja, erstellen Sie dazu ein SKILL.md. Wenn nein, gehen Sie weiter.

Muss Claude aktuelle Daten haben oder irgendwo außerhalb des Gesprächs handeln? Wenn ja, verwenden Sie MCP. Wenn nicht, gehört es möglicherweise überhaupt nicht zur Konfiguration des Agents. Manche Dinge sind besser als Dokumentation zu belassen, die niemand von einer KI verlangt, dass sie auswendig lernt.

Eine Namensfalle

Jeder, der zwischen verschiedenen Tools wechselt, wird früher oder später darauf stoßen. Claude Code und Cursor lesen CLAUDE.md, während Codex CLI sowie einige andere Umgebungen AGENTS.md lesen – beides dient demselben Zweck nur unter unterschiedlichen Namen. Googles Antigravity, das von dem ehemaligen Windsurf-Team nach Googles Vereinbarung mit ihnen Mitte 2025 entwickelt wurde, verwendet ebenfalls seine eigene AGENTS.md-Konvention. Dennoch lesen alle Tools – Claude Code, Cursor, Codex und Antigravity – das gleiche SKILL.md-Format für Fähigkeiten. Somit ist die Regelung pro Tool unterschiedlich, doch die Struktur für Fähigkeiten bleibt einheitlich. Das ist wichtig, bevor man annimmt, dass eine für ein Tool geschriebene Fähigkeit für ein anderes neu geschrieben werden muss.

Die Gewohnheit, die das löst

Vor dem Hinzufügen eines Absatzes zu CLAUDE.md sollten Sie zunächst prüfen, in welches der drei Kategorien er gehört. Ein großer Teil des Materials, das in CLAUDE.md untergebracht ist, stellt eigentlich eine Fähigkeit dar, die nie ihre eigene Dateiordner erhalten hat. Diese Praxis ist im Grunde eine Form des Kontextmanagements unter Verwendung einer anderen Kennzeichnung: Man entscheidet, was der Agent sehen soll und zu welchem Zeitpunkt – anstelle alles in die erste geöffnete Datei zu packen und darauf zu hoffen, dass das Modell alles ordnet. Öffnen Sie eine CLAUDE.md-Datei und zählen Sie, wie viele Absätze eigentlich Fähigkeiten sind, die die falsche Dateierweiterung tragen. Die Anzahl ist in der Regel höher als erwartet.