Die Skills, die mein Agent nicht sehen konnte

Ich hatte 84 Skills installiert und ging davon aus, dass alle 84 funktionierten. Fünf davon taten es nicht. swiftui, testing-philosophy, typeset, web-performance und update-shortcuts-guide erreichten das Modell als nackte Namen ohne angehängte Beschreibung, während ihre Dateien auf der Festplatte einwandfreie Beschreibungen trugen. Ein Skill ohne Beschreibung lässt sich nicht ansteuern, denn die Beschreibung ist das Routing-Signal. Diese fünf konnten sich nie automatisch aktivieren, und nirgendwo wies mich etwas darauf hin. Keine Fehlermeldung, keine Warnung, keine Logzeile. Ich fand sie zufällig, und beweisen ließ sich die Ursache nur, weil die Behebung sie vor meinen Augen rückgängig machte. {.answer-block}

TL;DR

• Skill-Beschreibungen werden in den Kontext jedes einzelnen Turns geladen und teilen sich ein festes Zeichenbudget. Wird es überschritten, fallen Beschreibungen stillschweigend weg.¹²
• Ich hatte 84 Skills installiert, 82 davon trugen eine Beschreibung, zusammen 21.848 Zeichen. Fünf kamen mit vorhandenem Namen und fehlender Beschreibung an. Auf der Festplatte hatten diese fünf jeweils 206 bis 336 Zeichen.
• Kein Dateimerkmal erklärte, welche fünf wegfielen. Beschreibungslänge, Dateigröße, YAML-Format, Abweichung zwischen name und Verzeichnis sowie Änderungszeitpunkt überschnitten sich zwischen den weggefallenen und den erhaltenen Skills.
• Ich schrieb 74 Beschreibungen auf insgesamt 9.885 Zeichen zusammen. Alle fünf tauchten mitten in der Sitzung wieder auf, in derselben Unterhaltung, mit intakter Beschreibung. Hypothese, Eingriff, Bestätigung.
• Das genaue Budget ist nicht dokumentiert und derzeit umstritten. Bei Anthropic sind Issues offen, laut denen der Anteil gegen eine feste Basis von 200K berechnet wird und die 1M-Kontexterweiterung dabei ignoriert bleibt.³⁴
• Die Regel beim Umschreiben, mit der alles hineinpasste: Die einzige Aufgabe einer Beschreibung ist die Antwort auf die Frage, wann soll das aufgerufen werden. Ablauf, Philosophie und Dateipfade gehören in den Body, der erst beim Aufruf geladen wird.

Ein Fehler ohne Fehlermeldung

Die meisten Fehler in der Harness melden sich von selbst. Ein Hook beendet sich mit einem Wert ungleich null, ein MCP-Server startet nicht, ein Tool-Aufruf liefert einen Stacktrace. Beim Beschreibungsbudget passiert nichts davon. Es serviert dem Modell klammheimlich eine kürzere Liste als die auf Ihrer Festplatte, und jedes nachgelagerte Symptom sieht nach einem Problem des Modells aus statt nach einem Problem der Verkabelung.

Aufgefallen ist es mir beim Lesen meines eigenen Kontextfensters, nicht meines Dateisystems. Beim Überfliegen der Skill-Liste hatten fünf Einträge einen Namen und danach nichts. Jeder andere Eintrag hatte einen Namen und einen Satz. Ich zog mir die Dateien:

swiftui                    HAS  322 chars on disk -> DROPPED in context
testing-philosophy         HAS  291 chars on disk -> DROPPED in context
typeset                    HAS  248 chars on disk -> DROPPED in context
web-performance            HAS  206 chars on disk -> DROPPED in context
update-shortcuts-guide     HAS  336 chars on disk -> DROPPED in context

Die Folge ist schlimmer, als wenn ein Skill langsam oder falsch wäre. Ein Agent entscheidet anhand der Beschreibung, ob er einen Skill aufruft. Streichen Sie die Beschreibung, und Sie haben das Routing nicht verschlechtert, sondern beseitigt. Der Skill ist installiert, gültig und unerreichbar. swiftui ist mein Skill für die iOS-26-Patterns, was bedeutet: Jede Swift-Sitzung, die ich gefahren habe, lief ohne ihn.

Bei Anthropic sind Issues offen, die genau dieses Versagen beschreiben, darunter eines mit dem Titel „Beschreibungsbudget für Skills kürzt Routing-Informationen stillschweigend und verursacht Fehler beim Skill-Routing”.² Das Verhalten ist also ein bekannter Bug und keine lokale Fehlkonfiguration. Das war gut zu wissen, und geholfen hat es mir nicht dabei, herauszufinden, welche meiner Skills betroffen waren.

Die einfachen Erklärungen ausschließen

Verlockend wäre gewesen, den Mechanismus zu erraten und ihn zu reparieren. Ich versuchte zuerst, die Vermutungen zu widerlegen, denn „fünf Skills sind kaputt” und „fünf Skills sind aus diesem Grund kaputt” sind sehr verschiedene Behauptungen.

Wenn irgendeine Eigenschaft auf Dateiebene einen Skill zum Wegfall markierte, dann müsste sich die weggefallene Gruppe irgendwo messbar von der erhaltenen unterscheiden. Ich verglich sie:

Nichts trennte sie. Die weggefallenen Beschreibungen waren nicht die längsten, die Dateien nicht auffällig groß, der YAML-Stil war in beiden Gruppen gemischt, und die Änderungsdaten deckten denselben Zeitraum ab. Auch die alphabetische Position schied aus: Skills, die nach swiftui einsortiert werden, behielten ihre Beschreibung.

Der ehrliche Stand war an dieser Stelle: ein reproduzierbares Symptom und kein Mechanismus. Also hielt ich es genau so fest und suchte nach einem Test statt nach einer Theorie.

Der Test

Wenn das Gesamtbudget den Ausschlag gibt, dann müsste eine Kürzung der Gesamtsumme die weggefallenen Beschreibungen zurückbringen, unabhängig davon, welche Dateien ich kürze. Diese Vorhersage ist widerlegbar und billig.

Ich schrieb 74 Beschreibungen um und brachte die Summe von 21.848 Zeichen auf 9.885. Die fünf zuvor unsichtbaren Skills kamen mit angehängter Beschreibung zurück, in derselben Sitzung, ohne Neustart.

Das ist das ganze Experiment. Eine Vorhersage, ein Eingriff, eine Bestätigung. Der Wegfall hängt von der Gesamtgröße ab, nicht von einer Eigenschaft der einzelnen Datei, und genau deshalb konnte kein Merkmal auf Dateiebene die beiden Gruppen unterscheiden.

Ein Bug, der keine Spur hinterlässt, hinterlässt dennoch einen kontrafaktischen Befund. Wenn Sie die Ursache durch Untersuchen des Fehlers nicht finden, ändern Sie eine Variable und beobachten Sie, ob der Fehler mitzieht.

Ich möchte genau sein bei dem, was ich nicht nachgewiesen habe. Ich kenne das genaue Budget nicht, und ich veröffentliche keine Zahl, die ich nicht belegen kann. Die offizielle Dokumentation nennt die Grenze nicht.⁵ Messungen aus der Community setzen die praktische Obergrenze bei etwa 15.500 bis 16.000 Zeichen an und beziffern den Overhead pro Eintrag auf rund 109 Zeichen, verursacht durch XML-Tags, den Skill-Namen und das Feld für den Speicherort — nichts davon erfasst eine reine Zählung der Beschreibungszeichen. Bei 84 Skills macht allein dieser Overhead rund 9.156 Zeichen aus. Zugleich berichten Anthropic-Mitwirkende, der Budgetanteil werde gegen eine feste Basis von 200K berechnet und ignoriere die 1M-Kontexterweiterung, sodass zwei Sitzungen auf derselben Maschine unterschiedliche Budgets bekommen können.³⁴

Mein erster Anlauf, diesen Befund aufzuschreiben, behauptete, mein Setup liege „119 % über dem Budget”. Ich hatte eine ungeprüfte Annahme (1 % eines 1M-Fensters) mit einer echten Messung multipliziert und daraus eine selbstbewusste Zahl erzeugt, unter der nichts lag. Die beobachteten Fakten halten stand: Bei 21.848 Zeichen fielen fünf Beschreibungen weg, bei 9.885 keine einzige. Der Prozentwert hielt nicht stand, und er hätte nie geschrieben werden dürfen.

Die einzige Aufgabe einer Beschreibung ist das Routing

12.000 Zeichen zu streichen klingt zerstörerisch. War es nicht, denn das meiste, was in diesen Beschreibungen stand, hat nie Routing-Arbeit geleistet.

So warb mein Skill jiro für sich, mit 686 Zeichen:

Shokunin-Handwerksphilosophie für Codequalität und Berufsstolz. Aktiviert sich beim Implementieren von Funktionen, beim Refactoring, beim Schreiben von Tests, beim Review von Arbeit oder bei jeder nicht trivialen Änderung in FastAPI/Python, Swift/SwiftUI, HTMX-Frontends und Infrastrukturcode. Bindet drei Kernphilosophien ein: Shokunin (Exzellenz im Unsichtbaren), Omotenashi (Dienst durch Handwerk), Rick Rubin (kreatives Kanalisieren und Destillieren). Zentrales Entscheidungstor: das Evidence Gate (Belege für Qualität liefern, keine Gefühle darüber). Einsetzen bei: Funktionen bauen, Refactoring, Testen, Code-Review, Bugfixes oder jeder Arbeit, bei der vor der Fertigmeldung Qualitätsnachweise verlangt sind.

Rund 500 dieser Zeichen erklären, was der Skill enthält. Nichts davon hilft bei der Entscheidung, ob man ihn öffnen soll. Der Ersatz kommt mit 126 Zeichen aus:

Handwerks- und Evidenzstandards für Codequalität. Einsetzen beim Implementieren, Refactoring, Testen, Review oder Beheben von Bugs.

Dieselben Trigger-Wörter, dasselbe Routing-Verhalten, ein Fünftel der Kosten. Die Philosophie ist nicht verschwunden; sie steht im Body, der erst geladen wird, wenn der Skill tatsächlich läuft. In jedem Turn dafür zu bezahlen brachte nichts.

Das Muster wiederholte sich über den gesamten Bestand. Neun update-*-guide-Skills schleppten 3.024 Zeichen nahezu identisches Boilerplate über das Abtasten von Quellen, das Synchronisieren von Kopien und das Ausführen von Übersetzungen mit sich. Auf jeweils rund 115 Zeichen eingedampft, routen sie weiterhin korrekt, denn was sie unterscheidet, ist der Guide, den sie aktualisieren, nicht die Pipeline, die sie teilen.

Drei Regeln erledigten die Arbeit:

1. Trigger behalten, Erklärung streichen. Namen, Slash-Befehle und die Wörter, die ein Benutzer tatsächlich tippen würde, bleiben. Beschreibungen interner Abläufe fliegen raus.
2. Dateipfade gehören in den Body. Ein Pfad hilft dem Modell nicht bei der Entscheidung, wann etwas aufzurufen ist.
3. Gemeinsames Boilerplate ist reiner Overhead. Wenn neun Skills denselben Satz sagen, unterscheidet dieser Satz keinen einzigen von ihnen.

Die zweite Steuer: Beschreibungen, die wirken, ohne aufgerufen zu werden

Das Kürzen legte einen subtileren Preis frei. Elf meiner Beschreibungen, zusammen 3.808 Zeichen, führten Befehlssprache: ALWAYS, NEVER, MUST, PROACTIVELY, BEFORE. In distribute stand NEVER. In no-shortcuts stand ALWAYS. In git-custody stand BEFORE.

Diese Wörter liegen in jedem einzelnen Turn im Kontext, ob der Skill je läuft oder nicht. Sie lesen sich als Anweisungen, weil sie als Anweisungen geschrieben sind, und das Modell hat keine verlässliche Möglichkeit, eine Beschreibung als trägen Katalogtext zu behandeln und zugleich eine gleichlautende System-Anweisung als bindend.

Eine aktuelle Arbeit gibt dem Effekt einen Namen. „The Regression Tax”, gemessen über rund 6.000 Läufe auf zwei Benchmarks zur Büroautomatisierung und drei Harness-Stacks, identifiziert Skill Description Osmosis: Ein Skill verändert das Verhalten des Agenten allein dadurch, dass er im Kontext vorhanden ist, selbst wenn er nie aufgerufen wird.¹ Der Hauptbefund lautet: Die besten Skills gewinnen dadurch, dass sie weniger Regression verursachen, und nicht dadurch, dass sie mehr hinzugewinnen; außerdem investieren Skills zu viel in prozedurale Anleitung und zu wenig in Grounding und Verifikation.

Der Beleg aus der Produktion kam vor der Theorie. Anthropic nahm in v2.1.215 die automatische Aktivierung der mitgelieferten Skills /verify und /code-review zurück und beschränkte sie auf den ausdrücklichen Aufruf.⁷ Zwei Releases später rief sich auch /deep-research nicht mehr selbst auf.⁸ Das sind schwergewichtige Skills, deren ungefragte Läufe mehr kosteten, als sie einbrachten — Osmose, vom Anbieter im Feld beobachtet und dadurch korrigiert, dass er die Aktivierung entfernte statt die Beschreibung umzuschreiben.

Eine übergroße Beschreibung kostet also doppelt. Sie verbraucht Budget, das andere Skills fürs Routing brauchen, und sie übt Verhaltensdruck aus, um den niemand gebeten hat. Beide Kosten fallen in Turns an, in denen der Skill nichts beiträgt.

Der unangenehme Teil: Auch der Body regiert womöglich nicht

„Verschieben Sie es in den Body” lautet der Rat, den ich gerade gegeben habe, und er trägt eine Annahme mit sich, die man aussprechen sollte: dass ein Ablauf, den der Agent beim Aufruf lädt, tatsächlich bestimmt, was der Agent tut. Neue Benchmark-Arbeit legt nahe, dass diese Annahme schwächer ist, als sie klingt.

HANDBOOK.md hat genau das getestet. Fünfundsechzig Aufgaben, Richtliniendokumente von 20 bis 124 Seiten, Agenten, die in simulierten Unternehmen mit E-Mail, Chat, Kalendern und Handel arbeiten, dazu 824 programmatische Bewertungskriterien. Die beste von dreißig Modellkonfigurationen bestand 36,2 % der Durchläufe, und die meisten Frontier-Konfigurationen blieben unter 25 %.⁹

Die benannten Fehlermodi sind genau die, auf die es hier ankommt. Agenten lassen eine plausible Anfrage aus der Umgebung die geltende Richtlinie überstimmen. Sie führen eine vorgeschriebene Prüfung durch und handeln dann gegen deren Ergebnis. Über lange Horizonte verlieren sie Regeldetails. Nichts davon sind Abruffehler; das Dokument war die ganze Zeit verfügbar.

Die ehrliche Fassung meiner Regel ist also enger als „Beschreibungen routen, Bodys erklären”. Den Ablauf aus der Beschreibung herauszunehmen bleibt richtig, weil es Budget zurückholt, das andere Skills fürs Routing brauchen, und weil es verhindert, dass nicht aufgerufener Text das Verhalten lenkt. Beides sind echte Gewinne, und keiner davon hängt daran, dass der Body gut regiert. Was Sie damit nicht erkaufen, ist die Gewissheit, dass der verschobene Ablauf auch befolgt wird. Ein Handbuch mit 124 Seiten und ein SKILL.md-Body mit 3.000 Wörtern liegen auf derselben Kurve.

Praktisch gelesen: Behandeln Sie die Länge des Bodys als Kosten, nicht als Gratisparkplatz. Wenn eine Regel wirklich gelten muss, ist eine Beschreibung der falsche Ort dafür und ein langer Body nur ein geringfügig besserer. Durchsetzung gehört an eine deterministische Stelle (ein Hook, eine Berechtigungsregel, ein Test), nicht in Prosa, an die sich ein Modell erinnern soll, während es etwas anderes tut.

Den eigenen Bestand prüfen

Beginnen Sie innerhalb einer Sitzung. Führen Sie /context aus; der Befehl meldet, ob Skills ausgeschlossen wurden.⁵ Werden Ausschlüsse angezeigt, haben Sie das Problem, und die Diagnose ist erledigt.

Warum ich nicht dort angefangen habe, ist aufschlussreich: Meine fünf Skills waren nicht ausgeschlossen, sie kamen mit intakten Namen und entfernten Beschreibungen an, was ein leiserer Fehler ist als ein fehlender Eintrag und womöglich nicht auf dieselbe Weise sichtbar wird. Prüfen Sie also trotzdem gegen Ihr Dateisystem. Der Test braucht kein Werkzeug außer einer Shell:

python3 - <<'PY'
import os, re, glob
rows = []
for f in glob.glob(os.path.expanduser('~/.claude/skills/*/SKILL.md')):
    name = os.path.basename(os.path.dirname(f))
    fm = re.match(r'^---\s*\n(.*?)\n---\s*\n', open(f, encoding='utf-8', errors='replace').read(), re.S)
    if not fm:
        continue
    d = re.search(r'^description:\s*(.*?)(?=\n[a-zA-Z_-]+:|\Z)', fm.group(1), re.S | re.M)
    if not d:
        continue
    desc = ' '.join(d.group(1).split()).strip('"\'').lstrip('|').strip()
    rows.append((len(desc), name))
rows.sort(reverse=True)
print(f'{len(rows)} skills, {sum(r[0] for r in rows)} description chars')
for length, name in rows[:15]:
    print(f'  {length:4d}  {name}')
PY

Vergleichen Sie dann die Ausgabe mit dem, was Ihr Modell tatsächlich erhalten hat. Die Lücke zwischen beiden ist der ganze Befund. Erscheint ein Skill in Ihrem Kontext mit einem Namen und ohne Satz dahinter, ist dieser Skill installiert und unerreichbar.

Aus der Prüfung folgen drei Gewohnheiten:

Kalkulieren Sie jeden neuen Skill ein, nicht nur die langen. Der Overhead pro Eintrag fährt bei jedem Skill mit, unabhängig von der Länge der Beschreibung; der zehnte Skill mit 90 Zeichen kostet deshalb mehr als 90 Zeichen.

Zählen Sie nach jedem Hinzufügen erneut. Ich kann Ihnen keinen sicheren Puffer nennen, weil die Obergrenze nicht dokumentiert ist und Berichten zufolge davon abhängt, wie der Anteil berechnet wird.³⁴ Eine empirische Prüfung schlägt einen errechneten Spielraum, der auf einer Annahme ruht — genau der Fehler, den ich gemacht habe.

Machen Sie vor dem Kürzen eine Momentaufnahme. Die meisten meiner Skill-Verzeichnisse waren nicht von git erfasst, und sieben waren Symlinks in ein Verzeichnis, das überhaupt kein Repository war, weshalb git add sie mit „beyond a symbolic link” abwies. Ich schrieb zuerst jede ursprüngliche Beschreibung in eine JSON-Datei. Eine Versionskontrolle, die Sie nicht überprüft haben, ist kein Backup.

Die wichtigsten Erkenntnisse

• Ein Skill ohne Beschreibung ist nicht verschlechtert, er ist unerreichbar. Die Beschreibung trägt die gesamte Routing-Entscheidung.
• Der Fehler ist konstruktionsbedingt stumm. Keine Fehlermeldung, keine Warnung, kein Log. Führen Sie /context für Ausschlusswarnungen aus und vergleichen Sie danach Ihre Kontextliste mit Ihrem Dateisystem, denn eine entfernte Beschreibung ist leiser als ein fehlender Eintrag.
• Den Wegfall treibt die Gesamtgröße, nicht Eigenschaften einzelner Dateien. Kein Merkmal der einzelnen Datei sagte vorher, welche Skills ihre Beschreibung verloren.
• Wenn die Untersuchung scheitert, greifen Sie ein. Den Mechanismus konnte ich durch Betrachten des Fehlers nicht finden. Die Summe zu ändern und dabei zuzusehen, wie sich der Fehler umkehrt, bewies ihn in einem einzigen Schritt.
• Beschreibungen routen; Bodys erklären. Alles in einer Beschreibung, was nicht bei der Entscheidung wann aufrufen hilft, wird in jedem Turn bezahlt und bringt nichts ein.
• Imperative in Beschreibungen wirken auf Sie, ohne aufgerufen zu werden. ALWAYS und NEVER lenken das Verhalten schon aus dem Katalog heraus, und genau das ist der gemessene Osmose-Effekt.¹
• Veröffentlichen Sie keinen Prozentwert, den Sie nicht belegen können. Mein eigener erster Text multiplizierte eine echte Messung mit einem geratenen Budget und erzeugte eine selbstbewusste, falsche Zahl.

Häufige Fragen

Warum aktiviert sich mein Claude-Code-Skill nicht?

Prüfen Sie, ob das Modell die Beschreibung überhaupt sehen kann. Skill-Beschreibungen werden in den Kontext jedes Turns geladen und teilen sich ein festes Zeichenbudget; wird es überschritten, fallen Beschreibungen stillschweigend weg, ohne Fehlermeldung, ohne Warnung, ohne Logzeile. Fünf meiner 84 Skills erreichten das Modell als nackte Namen, während ihre Dateien auf der Festplatte einwandfreie Beschreibungen trugen. Ein Skill ohne Beschreibung lässt sich nicht ansteuern.¹²

Wie groß ist das Beschreibungsbudget für Skills in Claude Code?

Das genaue Budget ist nicht dokumentiert und derzeit umstritten, und ich veröffentliche keine Zahl, die ich nicht belegen kann. Gemessen habe ich Folgendes: Bei 21.848 Zeichen an Beschreibungen fielen fünf Beschreibungen weg, bei 9.885 Zeichen keine einzige. Messungen aus der Community setzen die praktische Obergrenze bei etwa 15.500 bis 16.000 Zeichen an, bei rund 109 Zeichen Overhead pro Eintrag, und Anthropic-Mitwirkende berichten, der Budgetanteil werde gegen eine feste Basis von 200K berechnet.³⁴⁶

Wie prüfe ich, welche meiner Skills ihre Beschreibung verloren haben?

Beginnen Sie in einer Sitzung mit /context; der Befehl meldet, ob Skills ausgeschlossen wurden. Prüfen Sie danach trotzdem gegen Ihr Dateisystem, denn meine fünf waren nicht ausgeschlossen: Sie kamen mit intakten Namen und entfernten Beschreibungen an, was ein leiserer Fehler ist als ein fehlender Eintrag. Summieren Sie die Beschreibungszeichen über das Frontmatter Ihrer SKILL.md-Dateien und vergleichen Sie diese Liste mit dem, was Ihre Kontextliste tatsächlich zeigt.⁵

Was gehört in eine Skill-Beschreibung und was in den Body?

Die einzige Aufgabe einer Beschreibung ist die Antwort darauf, wann der Skill aufgerufen werden soll. Behalten Sie die Trigger-Wörter, Namen und Slash-Befehle, die ein Benutzer tatsächlich tippen würde, und verschieben Sie Ablauf, Philosophie und Dateipfade in den Body, der erst beim Aufruf geladen wird. Meine jiro-Beschreibung ging von 686 Zeichen auf 126 zurück, bei gleichem Routing-Verhalten, denn rund 500 dieser Zeichen erklärten nur, was der Skill enthält.

Beeinflussen Skill-Beschreibungen das Verhalten, auch wenn der Skill nie läuft?

Ja, und das ist die zweite Steuer. Elf meiner Beschreibungen enthielten ALWAYS, NEVER, MUST, PROACTIVELY und BEFORE, also Wörter, die in jedem Turn im Kontext liegen und sich als Anweisungen lesen, weil sie als Anweisungen geschrieben sind. „The Regression Tax” gibt dem Effekt den Namen Skill Description Osmosis: Ein Skill verändert das Verhalten des Agenten allein durch seine Anwesenheit im Kontext, selbst wenn er nie aufgerufen wird.¹

Quellen