Hooks und Skills

Die Projektanweisung aus Kapitel 03 hat eine Eigenschaft, die man leicht überliest: Sie ist Text im Kontext. Der Agent liest sie und richtet sich meistens danach.

Für vieles genügt das. Für zwei Fälle genügt es nicht, und für beide gibt es eine eigene Einrichtung.

Der Hook läuft

Ein Hook ist ein Programm, das an einem bestimmten Ereignis gestartet wird. Vor einem Tool Call, nach einer Dateiänderung, am Ende einer Antwort. Die Best Practices (externe Seite, code.claude.com) des Herstellers stellen den Unterschied in einem Satz gegenüber: Hooks sind deterministisch und garantieren, dass die Handlung stattfindet, während Anweisungen in CLAUDE.md nur ein Rat sind.

Der übliche Hook ist gewöhnlicher Programmcode, meist ein Skript von wenigen Zeilen, und er läuft an seinem Ereignis, ohne das Modell zu fragen. Das ist der Grund, warum eine Anweisung, die unbedingt gelten muss, hier besser aufgehoben ist als in einer Datei, die gelesen wird.

Es gibt auch Hooks, die ein Modell um ein Urteil bitten. Die Hook-Referenz (externe Seite, code.claude.com) führt sie als eigene Bauart, die einem Claude-Modell einen Prompt schickt und es in einer einzigen Runde urteilen lässt.

Bei ihnen ist garantiert, dass die Prüfung stattfindet. Ihr Ergebnis ist das Urteil eines Modells.

Der Skill wird geholt

Ein Skill geht in die andere Richtung. Er ist eine Arbeitsanweisung, die bereitliegt und erst dann in den Kontext kommt, wenn sie gebraucht wird. Die Skill-Doku (externe Seite, code.claude.com) rät zu einem Skill, sobald man dieselben Anweisungen, dieselbe Checkliste oder dasselbe mehrstufige Verfahren immer wieder in den Chat kopiert, oder sobald ein Abschnitt der CLAUDE.md zu einem Verfahren angewachsen ist, wo eine Tatsache stehen sollte.

Der zweite Fall ist der brauchbare Maßstab. In einer Projektanweisung stehen Tatsachen über das Projekt: wie gebaut wird, welche Namen gelten, wo was liegt. Sobald daraus eine Abfolge von Schritten wird, ist es ein Verfahren, und Verfahren gehören dorthin, wo sie nur beim Gebrauch kosten.

Anthropic beschreibt das Bauprinzip bei der Vorstellung der Skills (externe Seite, anthropic.com) mit einem treffenden Vergleich: Wer einen Skill für einen Agenten baut, stellt so etwas wie eine Ein­ar­bei­tungs­mappe für eine neue Mitarbeiterin zusammen.

seitlich verschiebbar

eigene Darstellung, Stand 04.08.2026

Wann man was nimmt

Die Entscheidung ist meistens einfach, wenn man sie an einer Frage festmacht: Muss es jedes Mal passieren?

Die letzte Zeile bleibt bewusst dort, wo sie ist. Eine Konvention ist eine Tatsache, und sie muss beim Schreiben jeder Zeile mitwirken.

Was beide gemeinsam haben

Der Hersteller empfiehlt in seinen Best Practices (externe Seite, code.claude.com), eine zu lange Projektanweisung zusam­men­zu­strei­chen: Was Claude ohne die Anweisung schon richtig macht, wird gestrichen oder in einen Hook umgewandelt.

Dieselbe Seite schickt im Abschnitt über die Projektanweisung den zweiten Teil woandershin: Fachwissen und Abläufe, die nur manchmal gebraucht werden, gehören in einen Skill.

Beide Einrichtungen verschieben damit dasselbe. Verlässlichkeit wandert vom Text, den ein Modell liest, in ein Programm, das läuft. Was das für die Prüfung bedeutet, steht am Ende von Kapitel 07: Die Frage lautet danach, ob das Programm daneben tut, was auf ihm steht.

Ein Hook hängt an einem Ereignis, und die Ereignisse haben sehr verschiedene Frequenzen. Wer das übersieht, baut eine Prüfung, die entweder zu spät kommt oder tausendmal läuft.

Drei Takte

Die Ereignisse, an denen eine Sitzung entlangläuft, teilen sich in drei Gruppen, und der Takt entscheidet, was man sinnvoll hineinlegt.

seitlich verschiebbar

eigene Darstellung nach Anthropic, Hooks reference, Stand 04.08.2026

Die drei Takte ordnen sieben Ereignisse. Die Referenz führt daneben gut zwei Dutzend weitere, die an einem einzelnen Anlass hängen: vor und nach dem Verdichten, wenn sich eine beobachtete Datei ändert, wenn ein Worktree angelegt wird. Für die Arbeit mit Regeln zählen die drei Takte.

Die dritte Zeile ist der Ort für alles, was mit einzelnen Handlungen zu tun hat. Ein Formatierer nach jeder Dateiänderung sitzt hier, ebenso eine Prüfung, die eine Handlung abweist, bevor sie stattfindet.

Die zweite Zeile ist der Ort für den Riegel aus Kapitel 07: Am Ereignis für das Ende einer Antwort lässt ein Hook den Agenten weiterarbeiten, solange sein Skript scheitert, höchstens achtmal hintereinander. Die Hook-Referenz (externe Seite, code.claude.com) nennt diese Grenze ausdrücklich: Haben Stop-Hooks den Agenten achtmal in Folge weiterarbeiten lassen, übergeht Claude Code die nächste Abweisung und beendet die Antwort.

Der Zähler beginnt von vorn, sobald der Agent ein Tool aufruft. Gedeckelt ist also nur ein Agent, der auf jede Abweisung bloß antwortet. Über eine Umgebungsvariable lässt sich die Grenze anheben.

Wie ein Hook eine Handlung abweist

Die Verständigung läuft über den Rückgabewert des Programms, und die Regel dafür steht knapp in der Referenz (externe Seite, code.claude.com): Mit dem Rückgabewert 2 weist ein Hook die Handlung ab.

Unter den Rückgabewerten weist von sich aus nur die 2 ab, außer beim Anlegen und Entfernen eines Worktrees. Der übliche Fehlercode eines Programms ist 1, und der lässt die Handlung durch: Ohne gültiges JSON auf der Standardausgabe wertet Claude Code die 1 laut Referenz (externe Seite, code.claude.com) als Fehler, der nichts blockiert, obwohl sie unter Unix der gewohnte Fehlercode ist. Ausgenommen sind Hooks, deren Scheitern die Handlung abweist; davon handelt der übernächste Absatz.

Ein Prüfskript, das aus Gewohnheit mit 1 endet, meldet also einen Fehler, und die Handlung findet trotzdem statt. Dasselbe gilt für ein Skript, das gar nicht startet, etwa weil der Pfad in der Einstellungsdatei vertippt ist. Die Referenz (externe Seite, code.claude.com) sagt das selbst: Bei den meisten Ereignissen führt Claude Code die Handlung trotzdem aus, wenn ein Hook scheitert oder seine Frist überschreitet, und so lässt ein Hook, der eine Richtlinie durchsetzen soll, mit falschem Pfad oder abstürzendem Skript alles durch.

Seit Version 2.1.295 lässt sich das für Hooks als Befehl oder als HTTP-Aufruf umstellen. Mit "onFailure": "block" zählt jedes Scheitern als Abweisung: ein Rückgabewert außer 0 und 2, ein Skript, das nicht startet, eine Zeit­über­schrei­tung, eine Ausgabe, die sich nicht lesen lässt. Am Ende einer Antwort wirkt die Einstellung nicht. Dort schickt eine Abweisung den Agenten zurück an die Arbeit, und einen Hook, der nicht startet, kann er nicht reparieren.

Die Begründung nimmt denselben Weg zurück wie die Abweisung. Laut Referenz (externe Seite, code.claude.com) ist die Meldung zur Abweisung das, was der Hook auf den Fehlerkanal (stderr) schreibt; gibt er außerdem JSON mit einer abweisenden Entscheidung aus, nimmt Claude Code stattdessen deren Begründung.

Das ist eine bemerkenswerte Konstruktion. Vor einem Tool Call geht der Text, den das Programm auf den Fehlerkanal schreibt, an das Modell zurück und wird dort zur Begründung. Ein Hook kann also abweisen und im selben Atemzug sagen, warum, und der Agent kann darauf reagieren.

Wer solche Meldungen schreibt, schreibt sie deshalb für einen Leser. Eine Meldung wie „verboten“ beendet die Handlung. Eine Meldung, die die erlaubte Alternative nennt, beendet sie und zeigt den Weg.

Wo die Verlässlichkeit endet

Hier steht die Kante, die der Formel vom deterministischen Hook eine Grenze zieht. Hooks lassen sich auf bestimmte Aufrufe eingrenzen, etwa nur auf Kom­man­do­zei­len­be­fehle eines bestimmten Musters. Für diese Eingrenzung zerlegt Claude Code die Kommandozeile und prüft jeden Teilbefehl einzeln, auch Befehle in $() und in Backticks. Kommandozeilen bleiben dabei Text mit Variablen, Ersetzungen und Verschachtelung. Kann Claude Code nicht bestimmen, welche Befehle eine Kommandozeile ausführt, läuft der Hook laut Referenz (externe Seite, code.claude.com) unabhängig vom Muster.

Für die vorsichtige Richtung ist das gutartig: Im Zweifel läuft der Hook. Ein Muster, das mehr nennt als den Befehlsnamen, etwa Bash(git push *), lässt den Hook bei $(), Backticks oder $VAR in jedem Fall laufen. Die Doku (externe Seite, code.claude.com) zieht daraus trotzdem eine deutliche Empfehlung: Weil der if-Filter nur nach bestem Bemühen arbeitet, gehört ein hartes Erlauben oder Verbieten ins Berech­ti­gungs­system statt in einen Hook.

Eine zweite Kante liegt in der Zeit. Jeder Hook hat eine Frist. Läuft ein Skript vor einem Tool Call in diese Frist, verwirft das Werkzeug seine Ausgabe, und der Aufruf geht den gewöhnlichen Weg über die Berechtigungen weiter. Die Referenz (externe Seite, code.claude.com) sagt dazu knapp, dass man sich auf einen hängenden Hook als Schranke nicht verlassen soll.

Die Einstellung onFailure aus dem vorigen Abschnitt schließt auch diese Kante: Mit ihr weist ein Hook, der seine Frist überschreitet, den Aufruf ab. Ohne sie ist ein Hook verlässlich in dem, was er tut, wenn er läuft und rechtzeitig fertig wird. Ob er bei genau der Handlung läuft, die man im Sinn hatte, ist die zweite Frage, und dafür gibt es das Berech­ti­gungs­system aus Kapitel 08.

Wer einen Skill auslösen darf

Bei Skills liegt die entscheidende Einstellung woanders. Voreingestellt können beide Seiten einen Skill auslösen: der Mensch durch Aufruf, das Modell von selbst, wenn die Kurzbeschreibung zur Lage passt. Zwei Schalter engen das ein.

Der erste nimmt dem Modell das Auslösen. Er ist für alles gedacht, was nach außen wirkt, und die Skill-Doku (externe Seite, code.claude.com) nennt dafür das Beispiel der Auslieferung: Claude soll sie nicht von sich aus anstoßen, bloß weil der Code fertig aussieht.

Der zweite nimmt dem Menschen den Aufruf und lässt nur das Modell. Das passt für Hintergrundwissen, das keine Handlung ist. Eine Erläuterung zu einem alten Teilsystem soll der Agent kennen, wenn sie zur Sache gehört, als Befehl ergibt sie keinen Sinn.

Der Skill im eigenen Fenster

Ein Skill kann außerdem festlegen, dass er in einem eigenen Kontextfenster läuft. Das lohnt sich, wenn sein Verfahren viel Ausgabe erzeugt, die hinterher niemand mehr braucht. Was dabei zu beachten ist, gehört zu Kapitel 13.

Ob er wirkt

Zum Schluss ein Maßstab aus der Skill-Doku (externe Seite, code.claude.com), der über Skills hinaus gilt: Dass ein Skill anspringt, zeigt nur, dass Claude ihn gefunden hat; ob er dabei getan hat, was man vorhatte, bleibt offen.

Ob der Skill anspringt und ob das Ergebnis stimmt, sind zwei Messungen. Die Doku empfiehlt für beide denselben Weg: einige realistische Aufträge sammeln und jeden zweimal fahren, mit und ohne den Skill.

Der Hinweis der Doku (externe Seite, code.claude.com) dazu ist der eigentliche Fund: Es braucht eine frische Sitzung, weil der Kontext, der vom Schreiben des Skills übrig ist, die Lücken in der geschriebenen Anweisung verdeckt.

Wer einen Skill gerade geschrieben hat, hat den Zusammenhang im Fenster stehen. Der Agent ergänzt aus diesem Zusammenhang, was in der Anweisung fehlt, und das Ergebnis sieht gut aus. Beim nächsten Mal, in einer frischen Sitzung, fehlt es wirklich.

Die Kostenregel aus Kapitel 05 lautet: Was beim Start im Fenster liegt, wird bei jedem Schritt mitbezahlt. Skills sind die Einrichtung, die genau daran ansetzt, und ihre Rechnung hat zwei Posten.

Zwei Posten

Der erste ist der bekannte: Anders als der Inhalt der CLAUDE.md lädt der Rumpf eines Skills laut Skill-Doku (externe Seite, code.claude.com) erst, wenn er benutzt wird, und deshalb kostet langes Nach­schla­ge­ma­te­rial fast nichts, bis man es braucht.

Der zweite steht ein paar Absätze weiter in derselben Doku (externe Seite, code.claude.com) und wird beim Bauen gern übersehen: Ist ein Skill einmal geladen, bleibt sein Inhalt über alle folgenden Runden im Kontext.

Ein Skill ist also billig, bis er einmal gebraucht wird, und danach verhält er sich wie ein Stück Projektanweisung für den Rest der Sitzung. Die Ersparnis liegt darin, dass die meisten Skills in den meisten Sitzungen gar nicht vorkommen.

Eine Einschränkung gilt ab dem Verdichten. Wird das Gespräch zusammengefasst, um Kontext freizumachen, hängt Claude Code laut Skill-Doku (externe Seite, code.claude.com) den jüngsten Aufruf jedes Skills hinter die Zusammenfassung und behält davon jeweils die ersten 5.000 Token.

Alle zusammen bekommen höchstens 25.000 Token, und bei vielen Skills fallen die am längsten nicht aufgerufenen ganz heraus. Was ein Skill unbedingt sagen muss, steht deshalb oben. Folgt Claude einem Skill nach dem Verdichten nicht mehr, holt ein erneuter Aufruf seinen vollen Text zurück.

seitlich verschiebbar

eigene Darstellung, Stand 04.08.2026

Praktisch folgt daraus eine Schreibregel, die der Doku entspricht: Der Rumpf bleibt knapp und sagt, was zu tun ist. Ausführliches Begleitmaterial kommt in Zusatzdateien, die der Agent bei Bedarf öffnet.

Die Kurzbeschreibung ist der Türsteher

Damit ein Skill zur rechten Zeit geholt wird, muss etwas von ihm dauerhaft sichtbar sein. Das ist die Kurzbeschreibung: Beim Start lädt der Agent laut der Vorstellung der Skills (externe Seite, anthropic.com) Name und Beschreibung jedes installierten Skills in seinen Systemprompt. Diese Angaben bilden die erste Stufe der schrittweisen Offenlegung (progressive disclosure).

Die Kurzbeschreibung entscheidet also über alles Weitere. Sie sollte die Wörter enthalten, die jemand tatsächlich sagen würde, wenn er die Sache meint. Eine Beschreibung, die den Fall elegant umschreibt, wird nie getroffen.

Wie oft der Türsteher öffnet

Dass ein Skill kommt, wenn er gebraucht wird, ist eine Annahme, und gemessen wird sie selten. Dolores, ein weitgehend von Agenten gebautes System eines einzelnen Nutzers, hat es nachgezählt und im September 2026 mitgeteilt. Ausgewertet wurden alle 813 Sitzungen aus drei Wochen, vom 29. Juli bis zum 19. August 2026. In 86 davon fasste ein Datei-Werkzeug einen der Pfade an, für die ein ausgelagerter Skill geschrieben war, und 11 dieser Sitzungen luden ihn, 12,8 Prozent. Hatte die Sitzung zusätzlich einen passenden Vorgang aus dem Ticketsystem in Arbeit, was auf 21 der 86 zutraf, luden ihn 10, also 47,6 Prozent. Über alle 43 Sitzungen mit passendem Vorgang gezählt, gleich welche Dateien sie anfassten, waren es 11, also 25,6 Prozent.

Die Basis ist klein, und die zweite Gruppe ist nur ein Teil der ersten. Einen Beweis, dass der Vorgang den Skill holt, liefert die Zählung nicht: Wer mit einem Vorgang arbeitet, arbeitet vielleicht ohnehin gezielter. Die Richtung ist trotzdem deutlich, und sie wiederholt sich. Dieselbe Zählung für Architektur-Dokumente, die ebenfalls nur bei Bedarf gelesen werden, ergab über 217 Sitzungen dasselbe Band: 7 Prozent ohne und 11 Prozent mit Vorgang, wenn nur Datei-Werkzeuge zählen, 24 und 45 Prozent, wenn Zugriffe über die Shell mitzählen. Die Kurzbeschreibung ist nötig, damit ein Skill gefunden wird, allein holt sie ihn selten. Häufiger kommt er, wenn der Auftrag die Sache beim Namen nennt. Die Ersparnis aus dem ersten Abschnitt hat damit eine Kehrseite: Ein Skill, der in den meisten Sitzungen nicht vorkommt, fehlt auch in manchen, in denen er gebraucht würde.

Das Projekt hat daraus eine Schreibregel gemacht, die sich übertragen lässt. Eine Anweisung wandert nie in einen Skill, dorthin geht nur ihre Begründung. In der Projektanweisung bleiben die Regel selbst und eine Zeile mit dem Anlass, etwa „vor Arbeiten an X zuerst Y lesen“. Fehlt dem Agenten dann die Herleitung, handelt er trotzdem richtig. Fehlte ihm die Regel, fiele es niemandem auf.

Das Budget, das die Beschreibung kürzt

Hier liegt eine Grenze, die still zuschlägt und die man nur kennt, wenn man sie gelesen hat. Das Verzeichnis der Skills hat eine Obergrenze, und die Skill-Doku (externe Seite, code.claude.com) setzt sie bei einem Prozent des Kontextfensters des jeweiligen Modells an.

Wird sie überschritten, verschwinden die Erklärungen und die Skills bleiben: Läuft das Verzeichnis über, streicht Claude Code laut Doku (externe Seite, code.claude.com) die Beschreibungen, beginnend bei den am seltensten aufgerufenen Skills, damit die meistbenutzten ihren vollen Text behalten.

Das Ergebnis ist unangenehm treffsicher. Der Name steht weiter da, aufrufen lässt sich der Skill also. Was fehlt, sind die Stichwörter, an denen der Agent ihn von selbst erkennen würde, und betroffen ist zuerst, was man selten benutzt. Ein Skill für den seltenen Fall ist damit genau dann stumm, wenn der seltene Fall eintritt.

Wer viele Skills führt, sieht sich den Posten deshalb gelegentlich an. Die Werkzeuge weisen ihn in der Kontextübersicht aus, und zwar in der Größe nach Anwendung der Kürzung, also so, wie das Modell ihn wirklich bekommt. Der Befehl /skill-doctor zeigt dazu je Skill Kosten und Nutzung und nennt die, die nie aufgerufen wurden. Eine Schätzung für das ganze Verzeichnis gibt /doctor, samt den Skills, die am meisten davon belegen.

Die Grenze lässt sich verschieben. Der Anteil am Fenster ist eine Einstellung (skillListingBudgetFraction). Bei einem Skill, den nur der Mensch aufruft (disable-model-invocation), steht die Beschreibung gar nicht im Kontext. Einen selten gebrauchten kann man über skillOverrides auf den Namen allein setzen (name-only). Dann entscheidet man selbst, wessen Beschreibung wegfällt.

Wann eine Regel in Code wandert

Der Bericht von OpenAI (externe Seite, openai.com) über ein fünf Monate lang agen­ten­ge­schrie­benes Produkt enthält die Regel, die diesem Kapitel zugrunde liegt: Wo die Dokumentation nicht ausreicht, wird die Regel zu Code.

Mit Code meint der Bericht eigene Linter und Strukturtests. Deren Fehlermeldungen schreibt das Team so, dass sie dem Agenten die Abhilfe gleich mitgeben, wie eine gute Abweisung durch einen Hook. Ein Hook ist ein Weg, eine solche Prüfung in jede Runde zu holen.

Der Auslöser ist konkret: Eine Anweisung, die trotz klarer Formulierung immer wieder übergangen wird, ist ein Kandidat. Für eine Regel, die jedes Mal gelten muss und übergangen wurde, rät die Skill-Doku (externe Seite, code.claude.com) zum Hook: Claude Code führt einen Hook jedes Mal aus, wenn sein Ereignis eintritt, etwa vor jeder Dateiänderung, ob Claude dem Skill gerade folgt oder nicht. Wer die Regel beim Skill halten will, legt den Hook im Kopf des Skills an. Er gilt dann ab dem Aufruf des Skills bis zum Ende der Sitzung. Wie das aussieht, zeigt Claude Code, Kapitel 18.

Der Grund dafür ist die Konkurrenz um Platz. Text im Kontext steht neben allem anderen Text und verliert an Gewicht, je voller es wird. Ein Hook steht daneben und konkurriert mit nichts.

Das kostet etwas. Eine Regel in einer Datei liest jeder, der die Datei öffnet. Ein Hook liegt in einer Konfiguration oder im Kopf eines Skills, läuft unsichtbar und fällt erst auf, wenn er etwas abweist. Wer viele davon einrichtet, baut eine Umgebung, deren Verhalten sich aus keiner einzelnen Datei mehr erklärt.

Der Hook, der ordentlich läuft und nichts bewirkt

Zum Schluss die Fehlerklasse dieses Kapitels, und sie gehört zu derselben Familie wie die aus Kapitel 07.

Nicht jedes Ereignis erlaubt jede Wirkung. Die Übersichtstabelle der Doku (externe Seite, code.claude.com) führt eine Gruppe von Ereignissen, bei denen ein Hook zwar läuft, aber nichts entscheiden und nichts beisteuern kann. Vermerkt ist bei ihnen, dass es keine Entscheidung gibt und sie für Nebenwirkungen wie Protokollieren oder Aufräumen gedacht sind.

Das Ereignis nach dem Verdichten gehört zu dieser Gruppe. Das Ereignis davor kann das Verdichten immerhin anhalten. Beisteuern kann es ebenfalls nichts, denn seine Ausgabe geht ins Protokoll des Werkzeugs: Bei den meisten Ereignissen schreibt Claude Code die Standardausgabe laut Referenz (externe Seite, code.claude.com) ins Debug-Protokoll und zeigt sie im Verlauf nicht an.

Der Fall, an dem das auffällt, ist der Wunsch nach einer Übergabe über das Verdichten hinweg. Man baut einen Hook, der vor dem Verdichten das Wichtige zusammenschreibt, und hängt ihn an das Ereignis, das so heißt. Er läuft. Er beendet sich erfolgreich. Und er speist nichts ein, weil dieses Ereignis genau das nicht kann.

Von den drei Ereignissen rund ums Verdichten kann nur der Sitzungsstart einspeisen, über ein eigenes Feld für zusätzlichen Kontext, und dieses Ereignis kennt das Verdichten als einen seiner Auslöser. Die Datei schreibt man also am einen Ereignis und liest sie am anderen.

Von außen sind die beiden Fassungen nicht zu unterscheiden. Beide laufen, beide enden mit Erfolg, und nur eine wirkt.