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 Runde. Der Hersteller stellt den Unterschied in einem Satz gegenüber:

Unlike CLAUDE.md instructions which are advisory, hooks are deterministic and guarantee the action happens. (externe Seite, code.claude.com)

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

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:

Create a skill when you keep pasting the same instructions, checklist, or multi-step procedure into chat, or when a section of CLAUDE.md has grown into a procedure rather than a fact. (externe Seite, code.claude.com)

Der zweite Halbsatz 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 mit einem treffenden Vergleich:

Building a skill for an agent is like putting together an onboarding guide for a new hire. (externe Seite, anthropic.com)

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?

Fall	Wohin
Nach jeder Dateiänderung soll die Formatierung laufen	Hook
Vor dem Löschen soll etwas geprüft werden	Hook
Die Vorgehensweise beim Veröffentlichen	Skill
Wissen über ein altes Teilsystem	Skill
Die Namenskonventionen des Projekts	Projektanweisung

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 an einer Stelle, die Projektanweisung zusammenzustreichen und einen Teil davon umzuziehen: Was der Agent ohnehin richtig macht, kommt heraus, und was zwingend gelten muss, wird ein Hook.

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 teilen sich in drei Gruppen, und der Takt entscheidet, was man sinnvoll hineinlegt.

Takt	Wann	Wofür
einmal je Sitzung	Start und Ende	Umgebung vorbereiten, aufräumen
einmal je Runde	Eingabe abgeschickt, Runde zu Ende	Kontext beisteuern, Ende blockieren
bei jedem Tool Call	vor und nach dem Aufruf	abweisen, ersetzen, protokollieren

seitlich verschiebbar

eigene Darstellung nach Anthropic, Hooks reference, Stand 04.08.2026

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 Rundenende hält ein Hook die Runde offen, solange sein Skript scheitert.

Wie ein Hook eine Handlung abweist

Die Verständigung läuft über den Rückgabewert des Programms, und die Regel dafür ist knapp:

Exit 2 means a blocking error. (externe Seite, code.claude.com)

Die Begründung nimmt denselben Weg zurück:

The blocking message is the reason from your JSON’s blocking decision when it makes one, and your stderr text otherwise. (externe Seite, code.claude.com)

Das ist eine bemerkenswerte Konstruktion. Der Text, den das Programm auf den Fehlerkanal schreibt, geht 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 Kommandozeilenbefehle eines bestimmten Musters. Diese Eingrenzung ist eine Textprüfung, und Kommandozeilen sind Text mit Variablen, Ersetzungen und Verschachtelung:

When Claude Code can’t determine which commands the Bash input runs, it runs your hook regardless of the pattern. (externe Seite, code.claude.com)

Für die vorsichtige Richtung ist das gutartig: Im Zweifel läuft der Hook. Die Doku zieht daraus trotzdem eine deutliche Empfehlung:

Because the if filter is best-effort, use the permission system rather than a hook to enforce a hard allow or deny. (externe Seite, code.claude.com)

Ein Hook ist damit verlässlich in dem, was er tut, wenn er läuft. Ob er bei genau der Handlung läuft, die man im Sinn hatte, ist die zweite Frage, und dafür gibt es das Berechtigungssystem.

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:

You don’t want Claude deciding to deploy because your code looks ready. (externe Seite, code.claude.com)

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 09.

Ob er wirkt

Zum Schluss ein Maßstab, der über Skills hinaus gilt:

Seeing a skill trigger tells you Claude found it, not that it did what you intended. (externe Seite, code.claude.com)

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 dazu ist der eigentliche Fund:

A fresh session matters because leftover context from authoring the skill will mask gaps in the written instructions. (externe Seite, code.claude.com)

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:

Unlike CLAUDE.md content, a skill’s body loads only when it’s used, so long reference material costs almost nothing until you need it. (externe Seite, code.claude.com)

Der zweite steht ein paar Absätze weiter und wird beim Bauen gern übersehen:

Once a skill loads, its content stays in context across turns (externe Seite, code.claude.com)

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.

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:

At startup, the agent pre-loads the name and description of every installed skill into its system prompt. (externe Seite, anthropic.com)

This metadata is the first level of progressive disclosure (externe Seite, anthropic.com)

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. Ein anderes Projekt, ein weitgehend von Agenten gebautes System eines einzelnen Nutzers, hat es nachgezählt und im September 2026 mitgeteilt. Gezählt wurden Sitzungen, die eine Datei aus dem Bereich anfassten, für den ein ausgelagerter Skill geschrieben war. Von 86 solchen Sitzungen luden ihn 12,8 Prozent. Trug die Sitzung zusätzlich einen passenden Vorgang aus dem Ticketsystem, waren es 47,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. 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:

The budget scales at 1% of the model’s context window. (externe Seite, code.claude.com)

Wird sie überschritten, verschwinden die Erklärungen und die Skills bleiben:

When the listing overflows, Claude Code drops descriptions starting with the skills you invoke least, so the skills you use most keep their full text. (externe Seite, code.claude.com)

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.

Wann eine Regel in Code wandert

Der Bericht von OpenAI über ein fünf Monate lang agentengeschriebenes Produkt enthält die Regel, die diesem Kapitel zugrunde liegt:

When documentation falls short, we promote the rule into code (externe Seite, openai.com)

Der Auslöser ist konkret: Eine Anweisung, die trotz klarer Formulierung immer wieder übergangen wird, ist ein Kandidat. 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.

Der Preis ist ebenso konkret. Eine Regel in einer Datei liest jeder, der die Datei öffnet. Ein Hook liegt in einer Konfiguration, 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 führt eine Gruppe von Ereignissen, bei denen ein Hook zwar läuft, aber nichts entscheiden und nichts beisteuern kann:

No decision control. Used for side effects like logging or cleanup (externe Seite, code.claude.com)

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.

Einspeisen kann nur der Sitzungsstart, ü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.