Claude Code Subagent erstellen: Frontmatter, Tools, Modell

Du hast einen Subagent geschrieben, Claude delegiert aber nie an ihn. Oder er taucht gar nicht erst in der @-Typeahead auf. Oder er läuft auf einem anderen Modell, als du im Frontmatter eingetragen hast. Alle drei Fälle haben dieselbe Ursache: Subagent-Dateien sehen trivial aus, Claude Code liest sie aber strenger und stiller, als man erwartet. Grundlage hier ist die offizielle Subagent-Doku von Claude Code. Wann sich Subagents überhaupt lohnen, steht im Artikel zu Subagent-Architektur und Kontext-Isolation; hier geht es ums Schreiben der Datei.

Wo die Datei liegt und wer gewinnt

Ein Subagent ist eine Markdown-Datei mit YAML-Frontmatter. Der Ort entscheidet über die Sichtbarkeit, bei Namensgleichheit gilt eine feste Reihenfolge:

1. Managed Settings (organisationsweit)
2. --agents als JSON beim Start (nur diese Session)
3. .claude/agents/ im Projekt
4. ~/.claude/agents/ für alle deine Projekte
5. agents/ eines Plugins

Projekt-Agents gehören ins Repo. Claude Code sucht dabei vom aktuellen Arbeitsverzeichnis aufwärts bis zum Repo-Root und scannt jedes .claude/agents/ auf dem Weg; bei doppeltem name gewinnt das näher liegende Verzeichnis. Für Headless-Läufe akzeptiert claude -p --agents ./agents.json auch einen Dateipfad statt Inline-JSON, laut Doku ab v2.1.281. Interaktiv lehnt Claude Code den Pfad ab.

Frontmatter: zwei Pflichtfelder, viele stille Fallen

Pflicht sind nur name und description. Ein minimaler, read-only Reviewer:

---
name: code-reviewer
description: "Eigene Subagents in Claude Code schreiben: Ablageort, Frontmatter-Felder, Auflösung von tools und model und warum Dateien still nicht laden."
tools: Read, Grep, Glob, Bash
model: sonnet
maxTurns: 20
---
Du prüfst Änderungen, schreibst nichts um und lieferst eine priorisierte Liste.

Der Body wird zum System-Prompt, und zwar exklusiv: Der Subagent bekommt nicht den Claude-Code-System-Prompt, sondern nur deinen Text plus Basisinfos wie das Arbeitsverzeichnis. Was er wissen muss, gehört also in den Body oder in den Delegations-Prompt.

Die eigentliche Falle: Feldnamen sind camelCase und müssen exakt passen. Ein unbekanntes Feld ignoriert Claude Code ohne Fehlermeldung. disallowed_tools statt disallowedTools heißt schlicht: keine Einschränkung. Ab v2.1.296 findest du Tippfehler mit claude --debug und einer Suche nach does not recognize or apply im Log unter ~/.claude/debug/<session-id>.txt.

Noch stiller sind ganze Dateien, die nicht laden. Claude Code überspringt sie ohne Hinweis in der Session, wenn name fehlt, das öffnende --- nicht in Zeile 1 steht, der name mit - beginnt, einen : enthält oder länger als 256 Zeichen ist, description fehlt oder das YAML nicht parst. Vor einer Session prüft claude plugin validate .claude/agents die Parse-Fehler, aber nicht den fehlenden name.

Zur Delegation: Claude entscheidet anhand von Task, description und Kontext. Die Doku empfiehlt Formulierungen wie „use proactively“ in der Description, warnt aber vor Länge: Ab 15.000 Tokens für alle Descriptions zusammen gibt es eine Startup-Warnung.

Tools: Allowlist, Denylist und was trotzdem fehlt

Ohne tools erbt der Subagent alle für Subagents verfügbaren Tools inklusive MCP. Mit tools baust du eine Allowlist, mit disallowedTools eine Denylist. Sind beide gesetzt, läuft zuerst die Denylist, dann wird die Allowlist gegen den Rest aufgelöst. Ganze MCP-Server adressierst du mit mcp__github__* (erlauben) oder mcp__* in disallowedTools (alle MCP-Tools weg).

Zwei Trade-offs, die man kennen muss:

• disallowedTools: Bash(git push *) entfernt das ganze Bash-Tool, nicht nur den Push. Willst du Bash behalten und einzelne Befehle sperren, gehört die Regel in permissions.deny deiner settings.json; die gilt für Hauptkonversation und Subagents.
• Background-Subagents, laut Doku der Default beim Spawnen aus der Hauptkonversation, behalten nur eine feste Liste eingebauter Tools (u. a. Read, Grep, Glob, Bash, Edit, Write, WebFetch). Alles andere fällt weg, auch wenn es in tools steht. Dieselbe Datei kann im Vordergrund also andere Tools haben als im Hintergrund.

Löst kein Eintrag in tools zu einem Tool auf, etwa weil alle falsch geschrieben sind, startet der Subagent in der Regel gar nicht und der Fehler nennt die Einträge.

Modellwahl und Effort

model akzeptiert ein Alias (sonnet, opus, haiku, fable), eine volle Model-ID oder inherit. Die Reihenfolge der Auflösung steht in der Grafik oben. Zwei Details, die beim Debuggen Zeit sparen:

• Gehört die Hauptkonversation zur selben Modellfamilie wie das Alias, läuft der Subagent auf exakt deren Modell, inklusive [1m]-Suffix und damit gleichem Kontextfenster.
• CLAUDE_CODE_SUBAGENT_MODEL ist nur ein Default. Erst zusammen mit CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 (ab v2.1.257) gilt ein Modell für alle Subagents; dann ignoriert Claude Code das model-Feld in deinen Dateien.

Welches Modell tatsächlich läuft, zeigt /tasks in der Zeile des Subagents. Für den Effort gibt es das Feld effort (low bis max, je nach Modell); CLAUDE_CODE_EFFORT_LEVEL überschreibt es. Läuft der Subagent auf einem anderen Modell als die Session, greift dein /effort nicht; das Level setzt du dann nur über das Feld.

Was das für deinen Workflow bedeutet

Behandle Agent-Dateien wie Code, nicht wie Notizen:

• Pflicht: name und description, Frontmatter in Zeile 1, Feldnamen exakt in camelCase.
• tools als Allowlist für alles, was nur lesen soll. Befehlsgenaue Sperren in permissions.deny, nicht in disallowedTools.
• model und effort explizit setzen, wenn der Agent nicht auf dem Session-Modell laufen soll, und mit /tasks gegenprüfen.
• claude plugin validate .claude/agents in CI oder als Pre-Commit-Check, claude --debug beim ersten Lauf.
• Für isolierte Schreibarbeit isolation: worktree, für Agents, die alles aus dem Prompt bekommen, omitClaudeMd: true. Wie sich Hooks pro Subagent ergänzen, steht im Hooks-Guide.

Der teuerste Fehler ist der unsichtbare: ein Feld, das nie greift, und niemand merkt es.

Du willst wissen, ob deine Agent-Dateien das tun, was ihr Frontmatter verspricht? Fordere ein Agent-Setup-Review an und bekomm priorisierte Änderungsvorschläge für .claude/agents/, Permissions und Hooks deines Repos.