Warum funktionieren Agent Skills nicht? 2026 Claude Code Skill-Trigger und Berechtigungsdiagnose

Der Skill erscheint nicht, obwohl die Datei im Projekt liegt, oder Claude Code liest die Anleitung, führt aber kein Werkzeug aus.

Die schnellste Lösung ist eine Schichtenprüfung: Erst Entdeckung mit einem minimalen Skill bestätigen, danach den Trigger testen und erst dann Berechtigungen, Arbeitsbereich und Vertrauensgrenzen wieder freigeben. Agent Skills funktionieren nicht in vielen Fällen nicht wegen mangelnder Modellfähigkeit, sondern wegen einer falschen Verzeichnisstruktur, einer unpassenden Beschreibung, fehlendem Kontext oder einer nicht unterstützten Ladeart.

Diese Anleitung richtet sich an Entwickler, die Claude Code, Codex oder OpenCode einsetzen und einen bereits angelegten Skill zuverlässig zum Laufen bringen möchten. Teamverantwortliche finden zusätzlich eine Abnahmereihenfolge für eigene Skills in Remote-Mac- und Cloud-Arbeitsbereichen.

Fehlerklasse zuerst eingrenzen

Ein vorschnelles Neuinstallieren des Clients verschiebt die Ursache, statt sie sichtbar zu machen. Für die Diagnose müssen drei Zustände auseinandergehalten werden:

• Nicht entdeckt: Der Agent kennt den Skill überhaupt nicht. Die Datei wird wegen Projektwurzel, Verzeichnisebene, Dateiname oder Frontmatter nicht geladen.
• Entdeckt, aber nicht ausgelöst: Der Skill wird angezeigt oder ist grundsätzlich verfügbar, seine Beschreibung passt jedoch nicht ausreichend zur aktuellen Aufgabe. Ein Modell ist nicht verpflichtet, einen Skill nur deshalb zu verwenden, weil er installiert wurde.
• Ausgelöst, aber fehlgeschlagen: Der Skill-Inhalt wurde gelesen, doch ein Werkzeugaufruf scheitert an Rechten, Bestätigung, Pfadgrenzen, fehlendem MCP-Server oder einer nicht gemounteten Datei.

Die offizielle Spezifikation für Agent Skills beschreibt die standardisierte Grundstruktur und die Rolle von SKILL.md. Für Claude Code gelten zusätzlich die Hinweise in der offiziellen Skills-Dokumentation. Diese Quellen sind wichtiger als einzelne Community-Berichte, weil ein Issue nur einen bestimmten Stand, eine Konfiguration oder einen Einzelfall abbilden kann.

Minimaltest statt Komplettumbau

Für die erste Prüfung genügt ein Skill, der eine eindeutige, ungefährliche Antwort anfordert. Er sollte keine Shell-Befehle, Dateischreibvorgänge oder MCP-Verbindungen benötigen. Die Anleitung kann beispielsweise verlangen, dass der Agent einen festen Diagnosehinweis ausgibt, sobald eine klar formulierte Testaufgabe gestellt wird.

Der Test muss drei Beobachtungen getrennt erfassen:

1. Wird der Skill im aktiven Projekt überhaupt gefunden?
2. Wird seine Beschreibung bei einer passenden Aufgabe berücksichtigt?
3. Wird der Inhalt von SKILL.md tatsächlich gelesen?

Wenn bereits die erste Beobachtung fehlschlägt, sind Prompt-Formulierungen oder Modellwechsel noch nicht relevant. Wenn der Skill sichtbar ist, aber nicht ausgelöst wird, beginnt die Analyse bei description. Erst nach einem bestätigten Trigger gehören Werkzeugrechte und Projektzugriff auf die Prüfliste.

Verzeichnis und Frontmatter prüfen

Die Datei SKILL.md ist kein beliebiger Markdown-Anhang. Sie liegt innerhalb eines Skill-Ordners, der an einem von der verwendeten Agent-Konfiguration unterstützten Ort eingebunden sein muss. Der aktive Projektwurzelpfad ist dabei entscheidend: Eine Datei im lokalen Checkout kann für einen Agent unsichtbar bleiben, wenn Claude Code in einem übergeordneten, anderen oder nur teilweise gemounteten Arbeitsbereich gestartet wurde.

Folgende Punkte werden in dieser Reihenfolge geprüft:

• Der Agent wurde tatsächlich aus dem erwarteten Projektverzeichnis gestartet.
• Der Skill liegt nicht in einer zusätzlichen, nicht unterstützten Verschachtelung.
• Der Ordnername und die Datei SKILL.md entsprechen der aktuell dokumentierten Struktur.
• Das Frontmatter steht am Anfang der Datei und ist syntaktisch gültig.
• Pflichtfelder enthalten gültige Werte und keine versehentlich eingefügten Tabulatoren, nicht geschlossenen Begrenzungen oder widersprüchlichen Datentypen.
• Der Skill ist Bestandteil des Arbeitsbereichs, den der Remote-Agent tatsächlich sehen darf.

Ein häufiger Diagnosefehler besteht darin, den Dateipfad im lokalen Dateimanager zu prüfen, während der Agent in einem Container, einer Remote-Sitzung oder einem anders eingehängten Checkout läuft. Der sichtbare Host-Pfad beweist nicht, dass derselbe Pfad innerhalb der Agent-Umgebung existiert.

Die aktuelle Dokumentation sollte immer gegen die eingesetzte Konfiguration geprüft werden, weil Ladeorte und unterstützte Felder versionsabhängig sein können. Eine feste Pfadangabe aus einem alten Tutorial ist deshalb kein ausreichender Beleg. Für die standardisierte Formatprüfung dient die Agent-Skills-Spezifikation; die Claude-Code-spezifische Auswertung beschreibt die Skills-Referenz.

Hinweis aus der Praxis: Ein Skill, der nach einer Änderung am Projektwurzelpfad „verschwindet“, ist nicht automatisch beschädigt. Zuerst sollte geprüft werden, ob die Sitzung noch denselben Checkout und dieselbe Konfiguration verwendet.

Triggerbeschreibung und Kontext testen

Eine korrekte Struktur macht den Skill auffindbar, löst aber noch keinen Aufruf aus. Die Beschreibung muss eine Aufgabe ausreichend präzise von gewöhnlichen Coding-Anfragen unterscheiden. Zu breite Beschreibungen konkurrieren mit vielen Skills; zu enge Beschreibungen reagieren nur auf eine einzelne Wortwahl. Gegensätzliche Beschreibungen können außerdem unklare Auswahlentscheidungen erzeugen.

Für eine belastbare Prüfung wird ein kleiner Testsatz mit drei Gruppen angelegt:

• Direkter Positivtest: Die Aufgabe verwendet genau die fachliche Tätigkeit, für die der Skill vorgesehen ist.
• Paraphrasentest: Dieselbe Absicht wird mit anderen, natürlichen Begriffen beschrieben.
• Negativtest: Eine verwandte, aber ausdrücklich nicht passende Aufgabe darf den Skill nicht auslösen.

Jeder Test erhält ein Protokoll mit Eingabe, sichtbarem Skill-Status, gelesenem Inhalt, Werkzeugentscheidung und Ergebnis. Damit lässt sich erkennen, ob nur der Wortlaut ungeeignet ist oder ob der Skill überhaupt nicht in den Kontext gelangt.

Besonders wichtig ist die Trennung zwischen „Skill wird angezeigt“ und „Skill-Text wird gelesen“. Ein verfügbarer Eintrag beweist nur, dass die Entdeckung funktioniert. Er beweist nicht, dass der Agent die vollständige Anleitung in die aktuelle Entscheidung einbezogen hat. Umgekehrt kann eine Antwort fachlich korrekt wirken, obwohl der Skill nicht verwendet wurde. Ohne eindeutigen Testmarker darf eine solche Antwort nicht als erfolgreicher Trigger gelten.

Claude Code, Codex und OpenCode können Skills unterschiedlich in den jeweiligen Agent-Kontext einordnen. Deshalb sollte ein Test nicht einfach von einem Agent auf den anderen übertragen werden. Für Codex beschreibt die offizielle Evaluierungsdokumentation zu Skills, wie Skill-Verhalten mit reproduzierbaren Aufgaben geprüft werden kann. Das liefert keine allgemeine Garantie für andere Agents, bietet aber ein sinnvolles Muster für getrennte Positiv- und Negativtests.

Ausführungswege vergleichen

Die folgende Gegenüberstellung verhindert, dass ein Problem der einen Schicht mit einer Maßnahme aus einer anderen Schicht behandelt wird:

Beobachtung	Wahrscheinlichste Schicht	Prüfschritt	Nächste Maßnahme
Skill erscheint nirgends	Entdeckung	Projektwurzel, Ordner, SKILL.md, Frontmatter	Struktur korrigieren und Sitzung im richtigen Arbeitsbereich starten
Skill ist sichtbar, reagiert aber nicht	Trigger	Positiv-, Paraphrase- und Negativtest	Beschreibung enger an die tatsächliche Aufgabe anpassen
Skill-Text erscheint, aber kein Werkzeug läuft	Ausführung	Werkzeug einzeln und ohne Nebenschritte testen	Rechte, Bestätigung und Pfadgrenzen prüfen
Lokaler Test funktioniert, Remote-Test nicht	Bereitstellung	Gemountete Verzeichnisse und aktiven Checkout vergleichen	Skill in den tatsächlich geladenen Arbeitsbereich liefern
Fremder Skill fordert weitreichende Rechte	Vertrauensgrenze	Herkunft, Version, Dateien und Werkzeuge prüfen	Isolieren, reduzieren oder nicht freigeben

Diese Tabelle ist zugleich ein Entscheidungswerkzeug: Erst wenn eine Zeile mit Belegen bestätigt ist, wird die jeweils nächste Schicht verändert. Ein Austausch des Modells ist bei einem nicht gemounteten Verzeichnis keine sinnvolle Reparatur.

Werkzeugrechte und Vertrauensgrenzen isolieren

Ein ausgelöster Skill kann ohne ausreichende Rechte korrekt gelesen werden und trotzdem scheitern. Read kann auf bestimmte Verzeichnisse begrenzt sein, Write kann eine Bestätigung verlangen, Bash kann deaktiviert oder eingeschränkt sein, und ein MCP-Werkzeug kann fehlen oder für die Sitzung nicht autorisiert sein. Die sichtbare Fehlermeldung hängt von der jeweiligen Agent-Integration ab; aus einer allgemeinen Meldung wie „konnte nicht ausgeführt werden“ darf daher nicht auf eine einzige Ursache geschlossen werden.

Die offizielle Dokumentation zu Claude-Code-Berechtigungen sollte für die konkrete Freigabelogik maßgeblich sein. Zusätzlich erklärt die Dokumentation zu kontrollierten Agent-Werkzeugen, warum erlaubte Werkzeuge, Zielpfade und kontrollierte Ausführung getrennt betrachtet werden müssen.

Die Prüfung erfolgt mit minimalem Umfang:

1. Einen Skill ohne Werkzeugzugriff ausführen und nur den gelesenen Inhalt bestätigen.
2. Einen ungefährlichen Read-Vorgang auf eine bekannte Testdatei auslösen.
3. Einen begrenzten Write-Vorgang in einem isolierten Testordner prüfen.
4. Bash nur mit einem harmlosen, vorher bekannten Befehl testen.
5. MCP erst danach als eigene Integrationsschicht zuschalten.

Drittanbieter-Skills verdienen besondere Vorsicht, weil Anweisungen in einer scheinbar harmlosen Datei zu weitreichenden Aktionen auffordern können. Vor der Veröffentlichung in einem Team-Repository werden Herkunft, Commit oder Release-Stand, erwartete Werkzeuge, Zielpfade und mögliche Datenabflüsse geprüft. Bei Änderungen wird nicht nur der Text von SKILL.md verglichen, sondern auch begleitende Dateien und Skripte.

Datenschutz und DSGVO-Anforderungen gehören in diese Prüfung. Ein Skill, der Quelldateien oder Zugangsdaten an ein externes MCP-System übergeben könnte, darf nicht allein aufgrund einer erfolgreichen Entdeckung in produktiven Projekten verwendet werden. Remote-Mac- oder Cloud-Sitzungen benötigen zusätzlich eine klare Trennung zwischen Testprojekt, Teamcode und persistenten Geheimnissen.

Lokale, entfernte und cloudbasierte Arbeitsbereiche abgrenzen

Ein lokales Projekt, ein per SSH erreichbarer Mac und ein Cloud-Arbeitsbereich sind nicht dieselbe Ausführungsumgebung. In jedem Fall werden mindestens vier Ebenen abgeglichen:

• Dateiablage: Liegt der Skill im Checkout, im Home-Verzeichnis oder nur auf dem lokalen Rechner?
• Prozessstart: Aus welchem Verzeichnis und mit welcher Agent-Konfiguration wurde die Sitzung gestartet?
• Mounts und Berechtigungen: Welche Ordner sind tatsächlich sichtbar und beschreibbar?
• Persistenz: Bleibt der Skill nach einer neuen Sitzung, einem Container-Neustart oder einem neuen Checkout vorhanden?

Bei einem Remote Mac sollte der Testordner dauerhaft und eindeutig benannt werden, während produktive Repositories zunächst nicht verwendet werden. In einem Cloud-Arbeitsbereich wird zusätzlich kontrolliert, ob der Skill beim Erstellen einer neuen Umgebung erneut ausgeliefert wird oder nur in einer einmaligen Sitzung vorhanden war.

Für Teams ist eine deklarierte Übergabe besser als das manuelle Kopieren in eine laufende Sitzung. Der Skill wird versioniert, mit einem kurzen Änderungsprotokoll versehen und über denselben Bereitstellungsweg wie der restliche Arbeitsbereich verteilt. So lässt sich nachvollziehen, welche Version getestet wurde und an welcher Stelle ein Rollback möglich ist.

Wer für diese Prüfungen einen getrennten Mac-Arbeitsplatz benötigt, kann zunächst die Informationen zum Mac-Mieten für Entwicklungsumgebungen heranziehen. Das ersetzt keine Berechtigungsprüfung, schafft aber einen kontrollierbaren Ort, an dem ein minimales Skill-Projekt vom produktiven Code getrennt bleibt.

Abnahme und Regression festlegen

Ein Skill gilt erst dann als teamtauglich, wenn nicht nur die Erstinstallation funktioniert. Die Abnahme sollte bei jedem neuen oder geänderten Skill dieselben Prüfpunkte durchlaufen:

• [ ] Der Skill wird im vorgesehenen Projekt und im vorgesehenen Remote-Arbeitsbereich entdeckt.
• [ ] SKILL.md und Frontmatter entsprechen der aktuell unterstützten Struktur.
• [ ] Ein direkter Positivtest löst den Skill aus.
• [ ] Ein Paraphrasentest bestätigt, dass die Beschreibung nicht nur auf ein einzelnes Schlüsselwort reagiert.
• [ ] Ein Negativtest verhindert unerwünschte Aktivierung bei einer ähnlichen Aufgabe.
• [ ] Der Skill-Inhalt ist im Protokoll eindeutig vom normalen Modellwissen unterscheidbar.
• [ ] Jedes benötigte Werkzeug wird einzeln mit minimalen Rechten geprüft.
• [ ] Schreib-, Shell- und MCP-Aktionen verlangen die vorgesehenen Bestätigungen.
• [ ] Ein Test mit fehlendem Zugriff erzeugt ein erwartetes, dokumentiertes Verhalten.
• [ ] Die verwendete Version und ein Rückkehrpunkt sind festgehalten.
• [ ] Ein Rollback auf die vorherige Skill-Version wurde zumindest im Testprojekt geprüft.

Für laufende Wartung genügt es nicht, nur den Inhalt der Anleitung zu versionieren. Eine Änderung an Werkzeugkonfiguration, Arbeitsbereichsmount, Agent-Version oder MCP-Server kann denselben Skill scheinbar „kaputtmachen“, obwohl die Datei unverändert blieb. Deshalb werden Regressionstests nach Infrastrukturänderungen wiederholt.

Eine interne Hilfsseite wie das Zutcloud Hilfezentrum kann als organisatorischer Einstieg für Zugangs- und Arbeitsumgebungsfragen dienen; die technischen Skill-Regeln selbst bleiben jedoch an die jeweils aktuelle offizielle Dokumentation gebunden.

Wiederherstellung ohne unkontrollierte Freigaben

Wenn ein Skill nach einer Änderung nicht mehr funktioniert, wird zunächst auf die letzte bekannte Version zurückgegangen. Danach wird jeweils nur eine Variable verändert: zuerst Arbeitsbereich, dann Struktur, dann Beschreibung, dann ein einzelnes Werkzeug. Werden gleichzeitig Frontmatter, Rechte und Prompt geändert, bleibt unklar, welcher Schritt den Fehler behoben oder verdeckt hat.

Ein brauchbares Rückgabeprotokoll enthält den aktiven Projektpfad, die Skill-Version, die verwendete Aufgabe, den sichtbaren Entdeckungsstatus, den gelesenen Inhalt, angeforderte Werkzeuge, erteilte Bestätigungen und den konkreten Fehler. Geheimnisse und personenbezogene Inhalte werden vor der Ablage entfernt. So kann der Fehler reproduziert werden, ohne Quellcode oder Zugangsdaten unnötig zu verbreiten.

Bei einem Skill, der plötzlich zusätzliche Shell- oder MCP-Rechte verlangt, wird nicht automatisch eine neue Freigabe erteilt. Der Änderungsumfang wird geprüft, die neue Version in einem isolierten Projekt ausgeführt und bei unklarer Herkunft verworfen. Ein funktionierender Trigger ist kein Sicherheitsnachweis.

Häufige Fragen zu nicht funktionierenden Agent Skills

Warum erkennt Claude Code einen Agent Skill nicht?

Prüfen Sie zuerst den Projektwurzelpfad, die unterstützte Skill-Struktur und die Datei SKILL.md. Ein zu tief verschachteltes Verzeichnis, ein abweichender Dateiname oder ungültiges YAML kann die Entdeckung verhindern. Erst wenn der Skill in der verfügbaren Skill-Liste erscheint, sollte die Beschreibung als mögliche Ursache eines fehlenden Triggers untersucht werden.

Wo sollte die Datei SKILL.md liegen?

SKILL.md gehört in das von der jeweiligen Agent-Konfiguration unterstützte Skill-Verzeichnis und muss dort als Teil eines eigenen Skill-Ordners liegen. Entscheidend sind nicht nur der Dateiname, sondern auch der aktive Projektkontext und die tatsächlich eingehängte Arbeitsumgebung. Die aktuelle offizielle Spezifikation ist vor Änderungen an Pfaden und Feldern maßgeblich.

Was ist zu tun, wenn ein Agent Skill auslöst, aber keine Werkzeuge liest?

Trennen Sie das Lesen der Skill-Anleitung vom späteren Werkzeugaufruf. Prüfen Sie zunächst, ob der Inhalt von SKILL.md im Kontext auftaucht. Danach testen Sie Read, Write, Bash oder MCP einzeln. Fehlt nur der Werkzeugaufruf, liegt die Ursache eher bei Berechtigungen, Bestätigungspflichten, Arbeitsbereichsgrenzen oder einem nicht verfügbaren Werkzeug.

Wie lassen sich Berechtigungen und Vertrauensgrenzen von Agent Skills prüfen?

Bewerten Sie Herkunft, Version, erwartete Werkzeuge und Zielpfade vor der Freigabe. Ein Skill aus einem fremden Repository darf nicht automatisch Schreibzugriff, Shell-Ausführung oder MCP-Zugriff erhalten. Testen Sie ihn zunächst in einem isolierten Projekt mit minimalen Rechten und dokumentieren Sie jede zusätzliche Freigabe samt Rücknahmeweg.

Wenn ein lokaler Skill stabil läuft, aber im aktuellen Cloud- oder Remote-Setup regelmäßig an Mounts, Sitzungszustand oder fehlenden Freigaben scheitert, ist der bestehende Ansatz nicht automatisch die beste langfristige Lösung. Lokale Rechner bieten direkten Zugriff, vermischen aber häufig persönliche und Testumgebungen; selbst verwaltete Cloud-Instanzen geben mehr Kontrolle, verursachen jedoch laufende Pflege für Images, Rechte, Persistenz und Sicherheitsupdates. Für einzelne Reproduktionen, zeitlich begrenzte AI-Coding-Tests oder getrennte Remote-Arbeitsplätze kann die Mac-Nutzung über Zutcloud deshalb übersichtlicher sein, weil die Skill-Prüfung in einer separaten Umgebung statt im produktiven Rechner stattfinden kann. Wer dagegen dauerhaft hohe Last, eigene Hardware-Schnittstellen oder vollständig individuelle Infrastruktur benötigt, sollte einen eigenen Mac oder eine selbst verwaltete Umgebung bevorzugen.

FAQ

Warum erkennt Claude Code einen Agent Skill nicht?

Prüfen Sie zuerst den Projektwurzelpfad, die unterstützte Skill-Struktur und die Datei SKILL.md. Ein zu tief verschachteltes Verzeichnis, ein abweichender Dateiname oder ungültiges YAML kann die Entdeckung verhindern. Erst wenn der Skill in der verfügbaren Skill-Liste erscheint, sollte die Beschreibung als mögliche Ursache eines fehlenden Triggers untersucht werden.

Wo sollte die Datei SKILL.md liegen?

SKILL.md gehört in das von der jeweiligen Agent-Konfiguration unterstützte Skill-Verzeichnis und muss dort als Teil eines eigenen Skill-Ordners liegen. Entscheidend sind nicht nur der Dateiname, sondern auch der aktive Projektkontext und die tatsächlich eingehängte Arbeitsumgebung. Die aktuelle offizielle Spezifikation ist vor Änderungen an Pfaden und Feldern maßgeblich.

Was ist zu tun, wenn ein Agent Skill auslöst, aber keine Werkzeuge liest?

Trennen Sie das Lesen der Skill-Anleitung vom späteren Werkzeugaufruf. Prüfen Sie zunächst, ob der Inhalt von SKILL.md im Kontext auftaucht. Danach testen Sie Read, Write, Bash oder MCP einzeln. Fehlt nur der Werkzeugaufruf, liegt die Ursache eher bei Berechtigungen, Bestätigungspflichten, Arbeitsbereichsgrenzen oder einem nicht verfügbaren Werkzeug.

Wie lassen sich Berechtigungen und Vertrauensgrenzen von Agent Skills prüfen?

Bewerten Sie Herkunft, Version, erwartete Werkzeuge und Zielpfade vor der Freigabe. Ein Skill aus einem fremden Repository darf nicht automatisch Schreibzugriff, Shell-Ausführung oder MCP-Zugriff erhalten. Testen Sie ihn zunächst in einem isolierten Projekt mit minimalen Rechten und dokumentieren Sie jede zusätzliche Freigabe samt Rücknahmeweg.