Claude Skills laden nicht in Subagents? Vier Ebenen prüfen

Fehler bei Claude-Code-Subagents eingrenzen: Vorladen, dynamische Skill-Aufrufe, Verzeichnisse und Berechtigungen prüfen – mit Diagnoseprojekt zum Download.

Zwei getrennte Stickrahmen; der kleinere erhält einen eigenen orangefarbenen Faden

Funktioniert ein Claude Skill im Hauptgespräch, aber nicht in einem benutzerdefinierten Subagenten, prüfen Sie Erkennung, Vorladen, Aufruf und Ausführung getrennt. Skill in einer Werkzeugliste lädt noch keine Anweisungen vor. Ein Eintrag unter skills: gibt dem Agenten auch nicht automatisch alle Werkzeuge, die diese Anweisungen benötigen.

Die aktuelle Claude-Code-Dokumentation unterstützt sowohl das Vorladen beim Start als auch dynamische Skill-Aufrufe innerhalb von Subagents. Ältere Aussagen, Subagents könnten Skills grundsätzlich nie aufrufen, sind deshalb im jeweiligen Versionskontext zu lesen. Das skills-Feld lädt Anweisungen beim Start; das Werkzeug Skill bietet während der Ausführung einen anderen Weg.

Diese Anleitung behandelt lokale benutzerdefinierte Claude-Code-Agents und Projekt-Skills. Die Angaben wurden am 18. November 2026 mit der offiziellen Dokumentation abgeglichen. Die Download-Beispiele sind von der Redaktion erstellte Diagnose-Testdaten: Dateien und Ergebnisprüfer wurden lokal validiert, Modellinferenz und Erfolgsquote dagegen nicht getestet. Die unten gezeigten Antworten sind Prüfkriterien, keine aufgezeichneten Claude-Ausgaben. Die verlinkten Herstellerdokumente und die Konfigurationsbeispiele sind auf Englisch.

Fehler eingrenzen, bevor Sie die Konfiguration ändern

BeobachtungZuerst prüfenHilfreicher Nachweis
Der Skill ist auch im übergeordneten Gespräch nicht verfügbarErkennung oder AufrufsteuerungTatsächlich aufgelöster Skill-Name, Dateipfad, Frontmatter, Richtlinie
Der übergeordnete Agent kann ihn nutzen; der benutzerdefinierte Agent ignoriert seine VorgabenVorladen oder dynamischer AufrufTatsächlich gewählte Agent-Definition; Vorladewarnung oder Skill-Aufruf
Der Skill-Aufruf wird verweigertWerkzeugzugriff und BerechtigungsregelnDas konkret verweigerte Werkzeug und die zugehörige Regel
Anweisungen sind vorhanden, aber eine Skript- oder Dateioperation schlägt fehlAusführungDateipfad, Arbeitsverzeichnis, verweigerte Operation, Skriptfehler
In einem Ordner funktioniert es, in einem anderen nichtGeltungsbereich oder NamenskollisionStartverzeichnis, Repository-Wurzel, tatsächlich verwendete Skill-Quelle

Behalten Sie eine fehlschlagende Eingabe bei und ändern Sie pro Durchlauf nur eine Variable. Starten Sie jede Variante in einem neuen Hauptgespräch und mit einem neuen Subagenten, damit frühere Ergebnisse nicht in die nächste Delegation gelangen. Marker und erwartete Antwort dürfen weder im delegierten Auftrag noch in automatisch geladenen Projektanweisungen stehen. Wenn Sie Dateien verschieben, Werkzeuge freigeben und die Beschreibung gleichzeitig umschreiben, bleibt sonst unklar, welche Änderung geholfen hat. Einen Überblick bietet die Anleitung zu Hooks, Subagents und Skills (Englisch); hier geht es um die gezielte Fehlereingrenzung.

1. Einen kleinen Skill mit überprüfbarer Ausgabe anlegen

Verwenden Sie ein separates lokales Testverzeichnis. Claude Code muss installiert sein; außerdem benötigen Sie eine bereits autorisierte Verbindung zu einem Modell. Notieren Sie vor einem Inferenzlauf claude --version sowie Modell und Anbieter. Eine Modellanfrage kann Ihr übliches Kontingent oder API-Guthaben verbrauchen. Der Download dieses Testprojekts löst keine solche Anfrage aus.

Laden Sie das Diagnoseprojekt herunter, oder erstellen Sie die folgenden Dateien selbst. Das Archiv enthält dieselben Dateien, Prompts, einen Ergebnisprüfer und eine Anleitung. Entpacken Sie es in einen neuen Ordner, prüfen Sie den Inhalt und starten Sie Claude Code aus diesem Ordner. Das Testprojekt enthält keine Hooks, Netzwerkaufrufe oder Zugangsdaten.

skill-diagnostic/
├── .claude/
│   ├── agents/
│   │   ├── audit-preloaded.md
│   │   └── audit-dynamic.md
│   └── skills/
│       └── sample-audit/
│           └── SKILL.md
├── sample.csv
└── check_result.py

Speichern Sie Folgendes in .claude/skills/sample-audit/SKILL.md. Der Marker macht die Formatvorgabe des Skills in der Ausgabe erkennbar. Er ist weder ein Sicherheitsmechanismus noch ein Nachweis dafür, auf welchem Weg die Anweisung beim Agenten angekommen ist.

---
name: sample-audit
description: Audit the synthetic sample.csv fixture and report missing amounts.
---
Read sample.csv in the working directory. Do not change any files.
Return exactly four lines, with no Markdown fences:
SKILL_MARKER=sample-audit-v1
ROWS=<number of data rows, excluding the header>
MISSING_AMOUNT_IDS=<comma-separated IDs, or none>
TOTAL_KNOWN_AMOUNT=<sum of nonempty amounts, two decimal places>
Keep IDs as text. A blank amount is missing, not zero.

Die Eingabedatei sample.csv ist bewusst klein:

id,amount
0007,12.50
0008,
0009,7.50

Kopieren Sie die vier erwarteten Antwortzeilen nicht in den Delegationsprompt. Sonst könnte der Agent sie ohne Nutzung des Skills wiedergeben. Der Versuch ist nur aussagekräftig, wenn die Antwort sowohl die Skill-Anweisung als auch die Eingabedatei benötigt.

2. Vorladen mit einem benutzerdefinierten Agenten prüfen

Speichern Sie .claude/agents/audit-preloaded.md:

---
name: audit-preloaded
description: Audit sample.csv using the preloaded sample-audit instructions.
tools: Read
skills:
  - sample-audit
---
Follow the preloaded audit instructions on sample.csv.
Do not read SKILL.md yourself. If the audit instructions are absent,
report PRELOAD_MISSING rather than inventing a format.

Die aktuelle Vorladeliste berücksichtigt die ersten 32 unterschiedlichen Namen. Vorgeladen wird der Inhalt des Skills, nicht jede zusätzliche Datei in seinem Ordner. Beides spielt bei diesem Testprojekt mit genau einem Skill keine Rolle.

Starten Sie nach dem Anlegen der Dateien ein neues Gespräch und geben Sie diesen Auftrag ein:

Use the audit-preloaded subagent to audit sample.csv.
Return its result verbatim. Do not perform the audit in the parent.

Prüfen Sie im Gesprächsprotokoll, ob tatsächlich audit-preloaded ausgewählt wurde. Dieser Agent hat absichtlich nur Read. Dass kein Aufruf des Werkzeugs Skill erscheint, ist beim Vorladetest normal. Ein direkter Zugriff auf SKILL.md oder die Bearbeitung durch den übergeordneten Agenten würde den vorgesehenen Vergleich unbrauchbar machen. Das wären andere Wege zur Antwort, kein Nachweis für erfolgreiches Vorladen beim Start.

Erwartet wird folgende Antwort:

SKILL_MARKER=sample-audit-v1
ROWS=3
MISSING_AMOUNT_IDS=0008
TOTAL_KNOWN_AMOUNT=20.00

Kopieren Sie ausschließlich die Antwort dieses Agenten nach result.txt und führen Sie python3 check_result.py result.txt aus. Das Prüfskript kontrolliert die vier Ergebniszeilen. Den Ladeweg kann es nicht nachweisen; prüfen Sie deshalb zusätzlich Gesprächsprotokoll und Debug-Ausgaben.

Für eine absichtlich fehlschlagende Gegenprobe ersetzen Sie sample-audit in der skills:-Liste des Agenten durch einen nicht vorhandenen Namen, etwa sample-audit-missing. Starten Sie anschließend einen neuen Agenten in einem neuen Hauptgespräch. Die erwartete Diagnose lautet PRELOAD_MISSING; der genaue Wortlaut ist nicht garantiert. Laut aktueller Dokumentation werden fehlende oder deaktivierte Vorladeeinträge übersprungen und im Debug-Protokoll als Warnung vermerkt. Stellen Sie vor dem nächsten Versuch den ursprünglichen Namen wieder her. Gibt der Agent trotzdem das normale Ergebnis aus, prüfen Sie, ob der übergeordnete Agent die Anweisungen mitgegeben hat, der falsche Agent ausgewählt wurde oder eine andere Datei den Marker enthielt.

Offizielle englische Claude-Code-Dokumentation mit der Konfiguration zum Vorladen von Skills

Für diesen Artikel aufgenommene offizielle Dokumentation. Der Screenshot zeigt die Dokumentation, keinen erfolgreichen Inferenzlauf.

3. Dynamischen Aufruf ohne Vorladen vergleichen

Speichern Sie .claude/agents/audit-dynamic.md:

---
name: audit-dynamic
description: Audit sample.csv by invoking the sample-audit skill.
tools: Read, Skill
---
First invoke the sample-audit skill using the Skill tool.
Then follow it on sample.csv. Do not read SKILL.md directly.
If the skill cannot be invoked, report INVOCATION_FAILED and the reason.

Diese Definition enthält kein skills:-Feld. Fordern Sie den übergeordneten Agenten auf, an audit-dynamic zu delegieren und dessen Antwort unverändert zurückzugeben. Für einen erfolgreichen Nachweis dieses Wegs muss im Agent-Protokoll ein Skill-Aufruf von sample-audit stehen, gefolgt vom selben vierzeiligen Ergebnis. Der Marker allein reicht nicht aus.

Entfernen Sie nun Skill aus der tools:-Liste dieses Agenten und lassen Sie alles andere unverändert. Erwartet wird ein fehlgeschlagener Aufruf, weil die Definition ein Werkzeug verlangt, das dem Agenten nicht mehr zur Verfügung steht. Fügen Sie Skill danach wieder hinzu. Ergänzen Sie während dieser Gegenprobe kein skills:-Feld: Damit würden Sie den separaten Vorladeweg einführen.

Dieser explizite Test prüft, ob ein Aufruf möglich ist. Er prüft nicht, ob Claude den Skill selbst auswählt. Dafür brauchen Sie eine neue Agent-Definition: Behalten Sie tools: Read, Skill bei, entfernen Sie aber die ausdrückliche Anweisung zu sample-audit und verwenden Sie eine neutrale Beschreibung wie Audit local CSV files. Stellen Sie eine gewöhnliche Prüfaufgabe, ohne den Skill zu nennen, und sehen Sie nach, ob ein Skill-Aufruf erfolgt. Funktioniert der explizite Aufruf, aber diese getrennte Auswahlprüfung nicht, untersuchen Sie Skill-Beschreibung und Aufgabenbezug. Ein erfolgreicher ausdrücklicher Aufruf belegt keine automatische Auswahl.

4. Aufrufsteuerung und Ausführungsrechte prüfen

Nehmen Sie die folgenden Änderungen einzeln im Testprojekt vor und stellen Sie nach jeder Prüfung den Ausgangszustand wieder her:

Einzelne ÄnderungErwarteter UnterschiedKorrektur
Dem Skill disable-model-invocation: true hinzufügenWeder modellinitiierter dynamischer Aufruf noch Vorladen sollen ihn verwendenDas Flag für bewusst manuelle Abläufe beibehalten; für diesen Versuch einen geeigneten, vom Modell aufrufbaren Skill nutzen
Stattdessen user-invocable: false hinzufügenBlendet den manuellen Befehl aus; verbietet für sich genommen keinen ModellaufrufEinen fehlenden Menüeintrag nicht mit fehlender Verfügbarkeit für das Modell verwechseln
Skill aus der expliziten Werkzeugliste des dynamischen Agenten entfernenDer dynamische Weg ist nicht verfügbar; der Vorlade-Agent ist davon unabhängigSkill nur dort bereitstellen, wo dynamische Aufrufe vorgesehen sind
Zugriff auf die Eingabedatei entziehenAnweisungen können vorhanden sein, während das Lesen der Daten scheitertDie konkrete Datei-/Werkzeugberechtigung oder den Dateipfad korrigieren

Die beiden Flags haben unterschiedliche Aufgaben; siehe Steuerung der Skill-Aufrufe. Entfernen Sie eine bewusst gesetzte Beschränkung auf manuelle Aufrufe nicht aus einem Deployment-Skill oder einem Skill für destruktive Operationen, nur damit ein Agent ihn automatisch verwenden kann.

Ein aufgelistetes Werkzeug darf nicht zwangsläufig uneingeschränkt genutzt werden. Prüfen Sie die Berechtigungsregeln von Claude Code, einschließlich Verbotsregeln, zentral verwalteter Richtlinien und Regeln für den exakten Skill-Namen. allowed-tools eines Skills kann weder ein aus dem Agent-Werkzeugsatz ausgeschlossenes Werkzeug zurückbringen noch eine Verbotsregel außer Kraft setzen. Ruft Ihr tatsächlicher Skill ein Python-Skript auf, prüfen Sie Bash und den Skriptpfad, nachdem Sie das Laden der Anweisungen nachgewiesen haben. Für die eigentliche Prüfung in unserem Testprojekt genügt Read; diese zusätzliche Fehlerquelle entfällt damit.

Verwenden Sie bypassPermissions nicht als Diagnosekorrektur. Es verändert gerade die Bedingungen, die Sie untersuchen wollen, und ist für ein schreibgeschütztes Beispiel mit drei Datenzeilen nicht erforderlich.

5. Verzeichnis- und Namensprobleme beheben

Prüfen Sie das Projekt, bevor Sie einen Skill in Ihr globales persönliches Verzeichnis verschieben:

pwd
claude --version
ls -l .claude/skills/sample-audit/SKILL.md
ls -l .claude/agents/audit-preloaded.md
ls -l .claude/agents/audit-dynamic.md

Agent-Datei und Skill-Datei erfüllen unterschiedliche Aufgaben und liegen in unterschiedlichen Verzeichnissen. Eine Datei unter .claude/agents/ wird nicht zum Skill, nur weil ihr Text das Wort „Skill“ enthält. Halten Sie für dieses Testprojekt Ordnername, Name im Frontmatter und Vorladeeintrag identisch. In die skills:-Liste gehört weder ein Dateisystempfad noch /sample-audit.

In einem Monorepo ist ein Skill unter packages/web/.claude/skills/ nicht mit einem Skill an der Projektwurzel gleichzusetzen. Die Erkennung verschachtelter Skills hängt davon ab, auf welchen Bereich Claude zugreift. Beginnen Sie mit dem Testprojekt an der Projektwurzel, um diese Unsicherheit auszuschließen, und führen Sie danach das tatsächliche Unterverzeichnis wieder ein. Werden bei einem Befehl unerwartete Anweisungen geladen, prüfen Sie Namenskollisionen zwischen persönlichen und Projekt-Skills sowie Plugin-Namensräume. Die offiziellen Regeln zur Skill-Erkennung und Benennung erläutern die Prioritäten. Alle Skills global zu verschieben kann eine neue Kollision erzeugen, statt die ursprüngliche Ursache zu beheben.

Liegt die Datei unter ../shared/.claude/skills/sample-audit/SKILL.md, starten Sie mit claude --add-dir ../shared und prüfen Sie, ob der Skill im neuen Gespräch erscheint. permissions.additionalDirectories allein gewährt Dateizugriff, lädt jedoch nicht die Skills dieses Ordners. Starten Sie bei einem verschachtelten Skill aus dem zugehörigen Unterverzeichnis oder verwenden Sie /add-dir mit einer unterstützten Version. Wiederholen Sie anschließend den Aufruf mit dem Skill-Namen. Halten Sie Startverzeichnis und sämtliche --add-dir-Argumente im Fehlerbericht fest. Klären Sie bei relativen Pfaden zu Zusatzdateien, ob sie sich auf den Skill-Ordner oder das Arbeitsverzeichnis beziehen; unsere sample.csv bezieht sich ausdrücklich auf Letzteres.

Haben Sie das oberste Skills-Verzeichnis erst nach dem Gesprächsstart angelegt, starten Sie das Gespräch neu, bevor Sie einen fehlenden Skill diagnostizieren. Dieses Testprojekt beginnt bewusst erst nach dem Anlegen der Dateien mit einer neuen Sitzung.

6. Nachweise sammeln, wenn das Minimalbeispiel weiter scheitert

Starten Sie ein neues lokales Gespräch mit einer privaten Debug-Datei. Die Syntax beschreibt die aktuelle CLI-Referenz:

claude --debug-file ./claude-skill-debug.log

Reproduzieren Sie eine Variante. Prüfen Sie den gewählten Agenten, den tatsächlich aufgelösten Skill-Namen, Warnungen zu fehlenden oder deaktivierten Skills, beim dynamischen Weg den Skill-Aufruf sowie verweigerte Read- oder Bash-Operationen. Kontrollieren Sie Protokolle vor dem Teilen: Sie können Pfade, Prompts und andere Sitzungsdaten enthalten. Veröffentlichen Sie keine Zugangsdaten oder unbeteiligten Gesprächsinhalte.

Verwenden Sie diese kompakte Berichtsvorlage:

Claude Code version / OS:
Model / provider (no secrets):
Working directory / repository root:
Agent name and definition:
Skill name, path and frontmatter:
Route: preload OR dynamic invocation
Exact prompt and synthetic input:
Expected result / actual result:
Selected-agent evidence / relevant tool call or warning:
Single change made / result after restoring baseline:

Ein Fehler beim Start, bei der Authentifizierung, bei TLS oder durch ein Ratenlimit tritt auf, bevor diese Prüfung das Skill-Verhalten nachweisen kann. Nutzen Sie dafür die Claude-Code-Anleitung zu TLS-Fehlern (Englisch) oder die Fehlersuche bei Ratenlimits (Englisch). Das Wiederholen einer abgewiesenen Modellanfrage korrigiert keinen falsch geschriebenen Vorladenamen. Ebenso behebt das Bearbeiten eines Skills keinen Zertifikatsfehler.

Wie passen context: fork, das SDK und Ofox dazu?

Ein Skill mit context: fork startet einen Agenten, der die Aufgabe des Skills ausführt. Ein Agent mit skills: beginnt mit seinen Agent-Anweisungen und erhält zusätzliche Skill-Inhalte. Wählen Sie die Richtung passend zum Ablauf; die Frontmatter-Felder sind nicht austauschbar. Siehe Skills in einem Subagenten ausführen.

Gehen Sie bei den hier verwendeten benutzerdefinierten Agenten nicht davon aus, dass sie alles aus dem Hauptgespräch kennen. Geben Sie notwendige Aufgabeneingaben ausdrücklich mit. Claude Code dokumentiert auch andere Fork-Verhaltensweisen; übertragen Sie die Isolation dieses Testprojekts nicht auf jede Agent-Art oder jeden Gesprächs-Fork.

Wenn Sie über das Claude Agent SDK starten, prüfen Sie die Dateisystemeinstellungen und die Konfiguration des Skill-Werkzeugs separat anhand der SDK-Dokumentation zu Skills. Erkennt ein Terminalgespräch einen lokalen Skill, belegt das noch nicht, dass ein in einem anderen Verzeichnis gestarteter SDK-Prozess dieselbe Konfiguration lädt.

Falls Sie Claude Code bereits über Ofox verbinden, finden Sie die Verbindungseinstellungen in der Claude-Code-Integrationsdokumentation und Hinweise zu API-Fehlern in der Fehlerbehandlungsreferenz. Anbieteranbindung und lokales Laden von Skills sind getrennte Prüfungen. Ein anderer API-Endpunkt schaltet nicht von selbst Claude-Kontofunktionen frei und repariert keine lokale Agent-Definition.

Ein sinnvolles Abschlusskriterium ist konkret: Der vorgesehene Agent startet, der beabsichtigte Ladeweg ist erkennbar, die vier Ausgabezeilen stimmen mit den Testdaten überein und die zugehörige Fehlergegenprobe verhält sich anders. Bewahren Sie diese Nachweise auf, bevor Sie den eigentlichen Workflow wieder zusammensetzen.