Claude Code Subagents vs. Skills: das deutsche Praxis-Tutorial

Ein Agent, der alles macht, macht nichts richtig. Wer Claude Code länger als eine Woche ernsthaft nutzt, kennt das Muster: Der Agent ist brillant bei der ersten Aufgabe, mittelmässig bei der fünften und verliert bei der zehnten den Faden — weil ein einziger Kontext alles gleichzeitig sein soll: Reviewer, Bauarbeiter, Rechercheur, Historiker.

Claude Code hat dafür zwei Bordmittel, die erstaunlich wenige Teams nutzen — und zu denen es auf Deutsch praktisch nichts Praxisnahes gibt: Subagents und Skills. Beide sind Markdown-Dateien. Beide sind in einer Stunde gebaut. Und zusammen sind sie der Unterschied zwischen einem cleveren Spielzeug und einem Werkzeug, das dein Team jeden Tag gleich gut benutzt.

Die Landkarte: Subagent, Skill, MCP-Server

Drei Abstraktionen, drei Jobs — die Verwechslung ist der häufigste Anfängerfehler:

Merkregel: Skills sind Wissen, Subagents sind Arbeitsteilung, MCP ist Anschluss an die Welt. Wie man Letzteres baut, steht im MCP-Tutorial — heute geht es um die ersten beiden.

Subagents vs. Skills: wie du dich entscheidest

Die Tabelle ist die Theorie — hier die Entscheidung in der Praxis. Stell dir drei Fragen zu dem, was du automatisieren willst:

1. Ist es Wissen oder ist es Arbeit? „So schreiben wir Commit-Messages", „so auditieren wir Barrierefreiheit" — das ist Wissen: ein Skill. „Reviewe diesen Diff", „recherchiere, wie Modul X funktioniert" — das ist Arbeit, die jemand erledigen muss: ein Subagent.
2. Braucht es ein eigenes Kontextfenster? Wenn die Aufgabe dreissig Dateien liest und deine Hauptsession nur das Fazit braucht, isolier sie in einem Subagent. Wenn die Anleitung auf eine Seite passt und die laufende Session steuert, ist es ein Skill.
3. Braucht es andere Rechte? Ein Reviewer, der nicht schreiben darf, ein Rechercheur, der nicht deployen darf — Rechtegrenzen gibt es nur zwischen Agenten, also Subagent. Ein Skill ändert nie Rechte; er läuft mit dem, was der ladende Agent ohnehin hat.

Daraus fallen zwei Faustregeln: Skills skalieren Konventionen, Subagents skalieren Kontext. Und wenn beides zutrifft — abgegrenzte Aufgabe und fester Arbeitsweg — nimm beides: einen Subagent, dessen System-Prompt ihm den Skill vorschreibt.

Ein Skill in 20 Minuten — an einem echten Beispiel

Skills leben als SKILL.md in .claude/skills/<name>/ im Projekt. Frontmatter beschreibt, wann der Skill gilt; der Body sagt, wie gearbeitet wird. Ein reales Beispiel aus unserem Marketing-Repo — ein Skill, der SEO-Audits wiederholbar macht:

---
name: geo-score
description: Use when auditing this site's AI-search readiness —
  after changing structured data, meta tags, or llms.txt.
---

# GEO Score Audit

1. Render the key pages and extract JSON-LD, meta, hreflang.
2. Score against the checklist below (0–100).
3. Append the result to docs/GEO-SCORE.md — never overwrite history.

## Checklist
- Entity graph present, @ids stable … (usw.)

Der Punkt ist nicht der Inhalt — der Punkt ist die Wirkung: Vorher hing die Audit-Qualität davon ab, wer fragte und wie. Nachher produziert jeder im Team (und jeder zukünftige Agent-Lauf) denselben Audit mit derselben Messlatte. Ein Skill ist kodifizierte Team-Konvention, die der Agent von selbst findet.

Die Kunst liegt im description-Feld: Es entscheidet, ob der Agent den Skill im richtigen Moment lädt. Schreib es wie einen Trigger („Use when …"), nicht wie eine Zusammenfassung.

Ein Subagent in 20 Minuten

Subagents leben in .claude/agents/<name>.md — YAML-Frontmatter plus System-Prompt. Der wichtigste Effekt: Sie laufen im eigenen Kontextfenster. Ein Rechercheauftrag über dreissig Dateien verbrennt nicht mehr das Gedächtnis deiner Hauptsession.

---
name: review-gate
description: Adversarial code reviewer. Use before merging
  agent-generated changes.
tools: Read, Grep, Glob
---

Du bist ein skeptischer Reviewer. Du hast die Änderung NICHT
geschrieben. Suche aktiv nach Fehlern: Randfälle, fehlende Tests,
Architektur-Verletzungen. Melde Befunde mit Datei und Zeile.
Du änderst nie Code — du berichtest.

Zwei Entscheidungen machen den Unterschied:

1. Werkzeugrechte beschneiden. Der Reviewer oben kann lesen, aber nicht schreiben — er kann seine eigene Kritik nicht „schnell fixen". Rollen-Trennung, technisch erzwungen statt erhofft.
2. Eine Rolle pro Subagent. „Recherchiere und implementiere und teste" ist kein Subagent, das ist die Hauptsession. Je schärfer die Rolle, desto besser das Ergebnis — dasselbe Prinzip wie bei menschlichen Reviews.

Wie die Teile zusammenspielen

Das Muster, das sich bei uns bewährt hat: Die Hauptsession orchestriert und implementiert. Skills halten die Konventionen (wie wird spezifiziert, auditiert, released). Subagents übernehmen die kontextfressenden oder rollenfremden Teile — Recherche vor dem Bauen, Review nach dem Bauen. Und MCP-Server liefern die Aussenwelt dazu.

Wer es so schneidet, bekommt etwas, das grösser ist als die Summe der Teile: einen Workflow, der auch dann funktioniert, wenn nicht der Enthusiast im Team ihn bedient, sondern irgendwer an einem Dienstagnachmittag.

Kann ein Subagent Skills benutzen?

Die Frage kommt in jedem Team, dem wir das vorstellen — darum bekommt sie ihren eigenen Abschnitt: Ja. Ein Subagent findet und lädt Projekt-Skills genauso wie die Hauptsession — ein review-gate-Subagent greift auf deinen Audit-Skill zu, wenn dessen Beschreibung zur Aufgabe passt.

Der Haken: Das Laden ist die eigene Entscheidung des Subagents, getroffen in seinem eigenen Kontext. Wenn ein Skill immer angewendet werden muss — die Release-Checkliste, das Security-Review — dann hoffe nicht auf die Erkennung. Verweise explizit im System-Prompt des Subagents darauf („folge bei jedem Audit dem geo-score-Skill"). Hoffnung ist keine Konvention; ein Satz im System-Prompt schon.

Best Practices, die den Alltag überlebt haben

Was nach Monaten täglicher Nutzung übrig blieb, verdichtet:

• Skill-Beschreibungen als Trigger schreiben, nicht als Zusammenfassung. „Use when auditing AI-search readiness" feuert im richtigen Moment; „ein Skill über SEO-Audits" nie.
• Eine Rolle pro Subagent, in einem Satz benennbar. Braucht die Beschreibung ein „und", teile den Subagent.
• Read-only als Standard. Read, Grep, Glob vergeben und Schreibrechte nur, wenn die Rolle sie verlangt.
• Skills in die Versionskontrolle, neben den Code, den sie regeln. Ein Skill, den niemand reviewt, driftet; ein Skill im Repo entwickelt sich mit dem Projekt.
• Die Hauptsession orchestrieren lassen. Subagents, die Subagents starten, verbrennen Tokens und verlieren den Faden — Tiefe eins reicht fast immer.
• Mit je einem anfangen. Ein Team, das einen guten Skill und einen guten Subagent pflegt, schlägt ein Repo mit fünfzehn verwaisten.

Was du diese Woche tun kannst

Bau einen Skill für die eine Sache, die dein Team ständig unterschiedlich macht — das Review-Ritual, die Release-Checkliste, das Audit. Zwanzig Minuten Markdown. Miss den Effekt daran, wie oft in den nächsten zwei Wochen jemand fragt: „Wie machen wir das nochmal?"

Mehr solcher Bauanleitungen — Subagents, Skills, MCP, Multi-Agent-Patterns — erscheinen regelmässig hier im Blog; der Newsletter liefert den jeweils nächsten zuerst.