Lektion 1: Claude Code als Agenten-Plattform

Claude Code hat sich von einem reinen Coding-Assistenten zu einer vollständigen Plattform für autonome KI-Agenten entwickelt. Für Softwareentwickler, die eigene Agenten bauen wollen, ist das Verständnis der fünf tragenden Säulen entscheidend: Skills, Tool Use, MCP, RAG und Agentic Patterns.

Was Sie in diesem Kurs lernen

Dieser Kurs richtet sich an Softwareentwickler, die verstehen wollen, wie KI-Agenten auf Werkzeuge zugreifen, externen Speicher nutzen und über standardisierte Protokolle kommunizieren. Nach Abschluss können Sie:

• Eigene Skills erstellen und in Claude Code oder anderen Frameworks nutzen
• Tool Use / Function Calling über die Anthropic API implementieren
• MCP-Server bauen, die beliebige Datenquellen und APIs bereitstellen
• RAG-Pipelines mit Vektor-Datenbanken aufsetzen
• Multi-Agent-Systeme orchestrieren

Die fünf Säulen

Der Paradigmenwechsel

Die Entwicklung von KI-Anwendungen hat sich fundamental verändert: Statt einzelner Prompts arbeiten moderne Systeme mit iterativen Agenten-Schleifen. Der Agent denkt nach, wählt ein Werkzeug, beobachtet das Ergebnis und wiederholt den Prozess -- bis die Aufgabe erledigt ist. Dieses "ReAct"-Pattern (Reason + Act) ist die Grundlage aller modernen KI-Agenten.

---

Lektion 2: Skills -- Modulare Fähigkeiten für Agenten

Was sind Skills?

Skills sind modulare, wiederverwendbare Fähigkeiten, die einen KI-Agenten erweitern. In Claude Code besteht jeder Skill aus einem Ordner mit einer `SKILL.md`-Datei plus optionalen Begleitdateien. Skills folgen dem offenen Standard agentskills.io, der auch mit Cursor, Gemini CLI und anderen kompatiblen IDEs funktioniert.

Progressive Disclosure -- Das Kernprinzip

Das geniale an Skills ist das Prinzip der Progressive Disclosure: Statt alle Instruktionen sofort in das Kontextfenster zu laden (wie bei MCP-Servern mit Dutzenden Tool-Definitionen), entdeckt der Agent Fähigkeiten erst bei Bedarf.

Die drei Ebenen:

1. YAML Frontmatter (immer geladen, ~5% des Gesamtkontexts): Nur Name und Kurzbeschreibung. Claude weiss, dass der Skill existiert.
2. SKILL.md Body (on-demand): Die vollständigen Instruktionen werden erst geladen, wenn Claude den Skill als relevant einstuft.
3. Verlinkte Dateien: Zusätzliche Skripte, API-Docs und Referenzdateien im Skill-Verzeichnis.

> "Usually the skill description is about 5% of the total context of the skill. That's all you're loading up front." -- Cole Medin

Skill erstellen -- Schritt für Schritt

1. Verzeichnis anlegen: ``` .claude/skills/fix-issü/SKILL.md ```

2. SKILL.md schreiben: ```yaml

---

name: fix-issü description: Fix a GitHub issü by number. Reads the issü, implements the fix, writes tests, and creates a commit. disable-model-invocation: trü allowed-tools: Bash(gh *), Read, Grep, Glob, Write, Edit

---

Fix GitHub issü $ARGUMENTS following our coding standards.

1. Read the issü: `gh issü view $ARGUMENTS`
2. Understand the requirements and affected files
3. Implement the fix
4. Write or update tests
5. Run the test suite
6. Create a descriptive commit ```

3. Aufrufen: `/fix-issü 142`

Sichtbarkeitsebenen

Aufruf-Kontrolle

• `disable-model-invocation: trü` -- Nur manüll via `/name` aufrufbar (nicht automatisch)
• `user-invocable: false` -- Nur Claude kann den Skill laden (für Sub-Agenten)
• `context: fork` -- Startet in isoliertem Subagent mit eigenem Kontextfenster
• `agent: Explore` -- Nutzt einen spezialisierten Agenten-Typ

Skills in eigenen Agenten nutzen

Skills sind nicht auf Claude Code beschränkt! Sie funktionieren in jedem Agent-Framework. Dafür brauchen Sie nur zwei Tools:

1. load_skill -- Liest die SKILL.md-Datei
2. read_reference -- Liest verlinkte Referenzdokumente

```python

Beispiel: Skills in Pydantic AI

import os from pathlib import Path

def get_skill_descriptions(skills_dir: str) -> str: """Sammelt alle Skill-Beschreibungen für den System-Prompt.""" descriptions = [] for skill_path in Path(skills_dir).glob("*/SKILL.md"): content = skill_path.read_text()

Nur YAML Frontmatter extrahieren

frontmatter = content.split("---")[1] descriptions.append(frontmatter) return "\n".join(descriptions) ```

Bundled Skills (mitgeliefert)

Claude Code bringt bereits nützliche Skills mit:

---

Lektion 3: Tool Use -- Agenten mit Werkzeugen ausstatten

Das Grundprinzip

Tool Use (auch Function Calling) erlaubt Claude, strukturiertes JSON auszugeben, das reale Aktionen auslöst -- API-Aufrufe, Datenbankabfragen, Berechnungen oder beliebige andere Operationen. Der Entwickler definiert die verfügbaren Tools mit Name, Beschreibung und JSON Schema.

Der Tool-Use-Flow (4 Schritte)

```

1. REQUEST: Entwickler sendet Nachricht + Tool-Definitionen
2. TOOL_USE: Claude antwortet mit strukturiertem Tool-Aufruf
3. TOOL_RESULT: Entwickler führt Tool aus, sendet Ergebnis zurück
4. ANTWORT: Claude verarbeitet Ergebnis und antwortet (oder ruft weitere Tools auf) ```

Tool-Definition -- Best Practices

Die `description`-Felder sind der primäre Steuerungsmechanismus. Investieren Sie hier genauso viel Sorgfalt wie in Code-Dokumentation:

```json { "name": "database_query", "description": "Führt eine SQL-SELECT-Abfrage auf der Produktdatenbank aus. Nur lesende Zugriffe erlaubt. Gibt maximal max_rows Zeilen zurück.", "input_schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Die SQL-SELECT-Abfrage. Beispiel: SELECT name, price FROM products WHERE category = 'electronics'" }, "max_rows": { "type": "integer", "default": 100, "description": "Maximale Anzahl zurückgegebener Zeilen (1-1000)" } }, "required": ["query"] }, "input_examples": [ {"query": "SELECT * FROM products LIMIT 10", "max_rows": 10}, {"query": "SELECT name FROM customers WHERE city = 'Berlin'"} ] } ```

Wichtige Parameter

Parallele Tool Calls

Claude kann mehrere Tools gleichzeitig aufrufen. Alle `tool_result`-Blocks müssen in einer User-Message zusammengefasst werden:

```python import anthropic

client = anthropic.Anthropic()

response = client.messages.create( model="claude-sonnet-4-5-20250514", max_tokens=1024, tools=[weather_tool, calendar_tool], messages=[{"role": "user", "content": "Wie wird das Wetter morgen und was steht im Kalender?"}] )

Claude kann beide Tools parallel aufrufen

-> tool_use Block für get_weather UND get_calendar

```

Error Handling

Fehler werden als `tool_result` mit `is_error: trü` zurückgegeben. Claude kann den Fehler analysieren, korrigieren und erneut versuchen:

```json { "type": "tool_result", "tool_use_id": "toolu_xyz", "is_error": trü, "content": "Fehler: Tabelle 'users' existiert nicht. Verfügbare Tabellen: customers, orders, products." } ```

Advanced: Dynamic Tool Loading

Bei grossen Tool-Bibliotheken (>10 Tools) spart `defer_loading: trü` massiv Token. Statt alle Definitionen vorab zu laden, durchsucht Claude dynamisch den Tool-Katalog:

• Token-Einsparung: Bis zu 191.000 Token bei grossen Workflows
• Accuracy: Steigt von 79,5% auf 88,1% bei Opus-Modellen
• Empfehlung: Ab 10+ Tools immer Dynamic Tool Loading nutzen

---

Lektion 4: Model Context Protocol (MCP) -- Der offene Standard

Was ist MCP?

Das Model Context Protocol ist ein offener Standard, der das "N x M-Integrationsproblem" löst. Statt für jede Kombination aus LLM und Datenquelle eine eigene Integration zu bauen, bietet MCP ein einheitliches Protokoll -- vergleichbar mit USB-C für Hardware.

MCP wurde im November 2024 von Anthropic veröffentlicht und ist seit Ende 2025 unter der Linux Foundation / AAIF als Industriestandard etabliert. OpenAI, Google und Microsoft unterstützen das Protokoll ebenfalls.

Architektur

``` +------------------+ +------------------+ +------------------+

+------------------+ +------------------+ +------------------+ ```

Die drei Primitives

Transport-Protokolle

stdio (empfohlen für lokal):

• Server läuft als Kindprozess
• Kommunikation über stdin/stdout
• Höchste Sicherheit, geringste Latenz

Streamable HTTP (empfohlen für remote):

• HTTP POST für Anfragen, JSON oder SSE für Antworten
• Session-Management über `Mcp-Session-Id` Headers
• Resumability nach Verbindungsabbruch

SSE (deprecated):

• Veraltet! Neue Projekte sollen Streamable HTTP verwenden.

MCP-Server bauen -- TypeScript-Beispiel

```typescript import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { z } from "zod";

const server = new McpServer({ name: "firmenwiki", version: "1.0.0" });

// Tool registrieren server.tool( "search_wiki", "Durchsucht das Firmenwiki nach einem Stichwort", { query: z.string(), max_results: z.number().default(5) }, async ({ query, max_results }) => { const results = await searchWikiDatabase(query, max_results); return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] }; } );

// Resource registrieren server.resource( "wiki://articles/{id}", "Einzelner Wiki-Artikel", async (uri) => { const id = uri.pathname.split("/").pop(); const article = await getArticle(id); return { contents: [{ uri: uri.href, mimeType: "text/markdown", text: article.content }] }; } );

// Server starten const transport = new StdioServerTransport(); await server.connect(transport); ```

Tool Discovery zur Laufzeit

Der Discovery-Prozess läuft dynamisch:

1. Client sendet `tools/list`
2. Server antwortet mit verfügbaren Tools (Name, Beschreibung, Schema)
3. LLM entscheidet, welches Tool es nutzt
4. Server kann via `notifications/tools/list_changed` über neue Tools informieren

MCP-Server in Claude Code einbinden

```bash

MCP-Server hinzufügen

claude mcp add firmenwiki -- node /pfad/zu/firmenwiki-server.js

Oder per Konfiguration in .claude/settings.json:

{ "mcpServers": { "firmenwiki": { "command": "node", "args": ["/pfad/zu/firmenwiki-server.js"] } } } ```

Sicherheitshinweise

• Keine integrierte Authentifizierung im Protokoll -- eigene Auth-Layer nötig!
• Fast 7.000 ungeschützte MCP-Server offen im Internet (Stand 2026)
• Tool Poisoning: Manipulierte Tool-Beschreibungen können Agenten täuschen
• Best Practice: Input-Validierung, Rate Limiting, Audit Logging, keine öffentliche Exposition ohne Auth

---

Lektion 5: RAG -- Retrieval Augmented Generation

Wann RAG und wann nicht?

Ein weit verbreitetes Missverständnis: "RAG ist tot." Die Realität ist differenzierter:

Moderne RAG-Pipeline: Contextual Retrieval

Anthropics "Contextual Retrieval" ist der aktülle Gold-Standard. Der Schlüssel: Vor dem Chunking wird jedem Chunk ein erklärenden Kontext hinzugefügt.

Die Pipeline:

``` Dokumente --> Chunking (512-1024 Token mit Overlap) --> Kontextgenerierung (Claude Haiku pro Chunk) --> Dual-Indexierung: Dense Embeddings + BM25 --> Hybrid Search mit Reciprocal Rank Fusion --> Reranking (Top 150 -> Top 20) --> Finale LLM-Antwort (Claude Sonnet/Opus) ```

Ergebnis: Bis zu 67% weniger Retrieval-Fehler gegenüber klassischem RAG.

Contextual Embeddings -- So funktioniert's

Statt einen nackten Text-Chunk einzubetten, wird jeder Chunk mit Kontext angereichert:

Vorher (klassisch): > "Der Preis beträgt 49,99 Euro pro Monat bei jährlicher Abrechnung."

Nachher (Contextual): > "Dieser Abschnitt stammt aus der Preisliste des Enterprise-Plans unserer SaaS-Plattform. Er beschreibt die monatlichen Kosten bei Jahresabonnement. Der Preis beträgt 49,99 Euro pro Monat bei jährlicher Abrechnung."

Praxis: RAG mit Qdrant und Claude

```python from qdrant_client import QdrantClient from qdrant_client.models import Distance, VectorParams, PointStruct import anthropic

1. Qdrant-Client und Collection

qdrant = QdrantClient("localhost", port=6333) qdrant.create_collection( collection_name="firmenwissen", vectors_config=VectorParams(size=1024, distance=Distance.COSINE) )

2. Dokumente mit Kontext anreichern und indexieren

def enrich_and_index(chunks: list[str], document_title: str): claude = anthropic.Anthropic() for i, chunk in enumerate(chunks):

Kontext generieren

context_response = claude.messages.create( model="claude-3-5-haiku-20241022", max_tokens=200, messages=[{ "role": "user", "content": f"Beschreibe in einem Satz, worum es in diesem Abschnitt aus '{document_title}' geht:\n\n{chunk}" }] ) enriched = f"{context_response.content[0].text}\n\n{chunk}"

Embedding erzeugen und speichern

embedding = get_embedding(enriched) # Voyage AI oder OpenAI qdrant.upsert( collection_name="firmenwissen", points=[PointStruct( id=i, vector=embedding, payload={"text": enriched, "source": document_title} )] )

3. Suche und Antwortgenerierung

def ask(question: str) -> str: query_embedding = get_embedding(question) results = qdrant.search( collection_name="firmenwissen", query_vector=query_embedding, limit=10 ) context = "\n---\n".join([r.payload["text"] for r in results])

claude = anthropic.Anthropic() response = claude.messages.create( model="claude-sonnet-4-5-20250514", max_tokens=2048, messages=[{ "role": "user", "content": f"Beantworte die Frage basierend auf folgendem Kontext.\n\nKontext:\n{context}\n\nFrage: {question}" }] ) return response.content[0].text ```

Vektor-Datenbanken im Vergleich

Praxis-Tipp: NotebookLM als kostenlose RAG-Lösung

Google NotebookLM kann über einen MCP-Server direkt in Claude Code eingebunden werden:

```bash claude mcp add notebook-lm npx notebook-lm-mcp@latest ```

Damit wird NotebookLM zur Wissensbasis und Claude Code zum Interface -- kostenlos und sofort einsetzbar.

---

Lektion 6: Agentic Patterns -- Agenten orchestrieren

Das ReAct-Pattern (Reason + Act)

Das fundamentale Pattern aller modernen KI-Agenten:

```

1. REASON: Analysiere die Aufgabe, erstelle einen Plan
2. ACT: Führe eine Aktion aus (Tool Call)
3. OBSERVE: Prüfe das Ergebnis
4. REPEAT: Bis Aufgabe erledigt oder Guardrail greift ```

Claude Code nutzt dieses Pattern nativ. Es denkt nach (Extended Thinking), wählt ein Tool, beobachtet das Ergebnis und iteriert.

Das WHISK-Framework für Context Management

Cole Medin's WHISK-Framework adressiert das grösste Problem bei Agenten: Context Rot -- 80% der Agent-Fehler entstehen durch schlechtes Kontext-Management.

Sub-Agenten vs. Agent Teams

Claude Agent SDK

Das offizielle SDK für eigene Agenten (Python und TypeScript):

```python from claude_agent_sdk import Agent, Tool

Agent mit Tools definieren

agent = Agent( model="claude-sonnet-4-5-20250514", tools=[ Tool(name="read_file", fn=read_file_impl), Tool(name="write_file", fn=write_file_impl), Tool(name="run_tests", fn=run_tests_impl), ], system_prompt="Du bist ein erfahrener Python-Entwickler..." )

Agent-Loop starten

result = agent.run("Implementiere eine REST-API für Benutzer-Verwaltung") ```

Kernfeatures:

• Agent Loop: Verwaltung der Observe-Think-Act-Schleife
• Context Compaction: Automatische Zusammenfassung bei Kontextfenster-Überlauf
• Multi-Agent Handoffs: Saubere Übergabe zwischen spezialisierten Agenten

Guardrails für Production-Agenten

Effektive Agenten brauchen harte Leitplanken:

Praxis: Multi-Agent Code-Migration

Der `/batch`-Skill zeigt Multi-Agent-Orchestrierung in Aktion:

1. Aufgabe wird in 5-30 unabhängige Units zerlegt
2. Pro Unit startet ein Hintergrund-Agent in eigenem Git-Worktree
3. Jeder Agent implementiert, testet und öffnet einen PR
4. Alle arbeiten parallel -- massive Beschleunigung

---

Lektion 7: Alles zusammen -- Einen Production-Agenten bauen

Architektur-Überblick

Ein produktionsreifer KI-Agent kombiniert alle fünf Säulen:

``` +-------------------+

+-------------------+ | +------------------+------------------+

+-----v-----+ +------v------+ +------v------+

+-----+-----+ +------+------+ +------+------+

+------------------+------------------+ | +------v------+

+-------------+ | +------------+------------+

Datenbank APIs/Services Dateisystem ```

Checkliste für Production-Agenten

1. Skills statt hardcodierter Prompts -- Nutzen Sie das `.claude/skills/`-System mit YAML Frontmatter. Skills ins Git-Repository aufnehmen.
2. Tool-Definitionen als Dokumentation behandeln -- Die `description`-Felder im JSON Schema sind der primäre Steuerungsmechanismus.
3. MCP für alle Integrationen -- Neue Anbindungen ausschliesslich als MCP-Server. Lokal: stdio. Remote: Streamable HTTP.
4. RAG mit Contextual Enrichment -- Niemals nackte Chunks einbetten. Immer Kontext-Anreicherung mit Haiku vorschalten. Hybrid Search + Reranking.
5. Dynamic Tool Loading ab 10+ Tools -- `defer_loading: trü` spart bis zu 191.000 Token.
6. MCP-Server absichern -- Input-Validierung, Rate Limiting, Audit Logging. Keine öffentliche Exposition ohne Auth.
7. Guardrails als Hard Gates -- Linter, Tests und Schema-Validierung in die Agent-Schleife integrieren.
8. Context Management mit WHISK -- Write, Isolate, Select, Compress. 80% der Fehler kommen von schlechtem Kontext.

Trends und Ausblick 2026

• Skills als offener Standard -- Portabel über Claude Code, Cursor, API und Drittanbieter
• MCP ersetzt proprietäre APIs -- OpenAIs Assistants API wird eingestellt, MCP wird Industriestandard
• Dynamic Tool Loading -- Löst das Problem explodierender Kontextgrössen
• Security wird Topthema -- Context-Layer Attacks und Tool Poisoning erfordern neue Sicherheitskonzepte
• Multi-Agent wird Mainstream -- Claude Agent SDK mit Compaction macht längere Aufgaben möglich

Weiterführende Ressourcen

• Anthropic Docs: Skills
• Anthropic Docs: Tool Use
• MCP Spezifikation
• Anthropic: Contextual Retrieval
• Claude Agent SDK
• Cole Medin: Skills for ANY Agent
• Cole Medin: WHISK Framework
• awesome-claude-code