Eigene Agent-Fähigkeit mit SKILL.md schreiben

Schreiben Sie anhand eines realen Fehlers Ihre eigene Agent-Fähigkeit

Die beste Methode, eine eigene Agent-Fähigkeit zu schreiben, besteht darin, sie aus einem realen Fehler abzuleiten. Suchen Sie eine Aufgabe, die Ihr Coding-Agent zweimal falsch ausgeführt hat, notieren Sie die Korrektur, die Sie beide Male eingegeben haben, und speichern Sie diese Korrektur als SKILL.md-Datei, die der Agent selbst laden kann. Danach geht es nur noch um die technischen Details: den Dateiaufbau und die eine Zeile, die entscheidet, ob die Fähigkeit überhaupt ausgelöst wird.

Diese Reihenfolge ist wichtig. Eine aus der Vorstellung heraus geschriebene Fähigkeit dokumentiert ein Problem, das Sie nie hatten, und verbraucht trotzdem in jeder Sitzung Kontext. Eine aus einem beobachteten Fehler abgeleitete Fähigkeit enthält bereits ihren eigenen Test: Stellen Sie dieselbe Frage erneut und prüfen Sie, ob der Agent sie diesmal richtig beantwortet. Wenn dieses Format für Sie neu ist, lesen Sie zuerst was Agent-Fähigkeiten sind und wie ein Agent sie lädt und schreiben Sie danach Ihre eigene.

Beginnen Sie mit einer Aufgabe, die der Agent zweimal falsch ausgeführt hat

Einmal kann Zufall sein. Zweimal ist ein Muster, und ein Muster ist eine Datei wert.

Hier ist ein Fehler, der auf echten Servern wiederholt auftritt. Sie weisen den Agenten an, einen Reverse-Proxy-Block zu nginx hinzuzufügen. Er bearbeitet /etc/nginx/conf.d/app.conf und führt anschließend sudo systemctl restart nginx aus. Die Änderung enthält einen Tippfehler. Deshalb verweigert nginx den Start, und die Website bleibt offline, bis Sie den Fehler beheben:

nginx: [emerg] unknown directive "proxy_pas" in /etc/nginx/conf.d/app.conf:12
Job for nginx.service failed because the control process exited with error code.

Sie korrigieren den Fehler im Chat. Testen Sie die Konfiguration mit sudo nginx -t, bevor Sie den Dienst ändern, und wenden Sie sie anschließend mit reload statt mit restart an. Eine Woche später tritt derselbe Fehler bei einer anderen Aufgabe erneut auf. Dieses zweite Auftreten ist das Signal.

Notieren Sie zwei Dinge, solange der Fehler noch vor Ihnen liegt: die von Ihnen eingegebene Anfrage und die von Ihnen gegebene Korrektur in genau den verwendeten Worten. Aus diesen beiden Zeilen entsteht der Skill. Die Anfrage legt fest, worauf der Trigger reagieren muss. Die Korrektur bildet den vollständigen Inhalt.

Die eigenen Authoring-Richtlinien von Anthropic stellen diesen Schritt an den Anfang. Führen Sie den Agenten bei repräsentativen Aufgaben zunächst ohne Skill aus und halten Sie fest, an welchen Stellen er Fehler macht. Schreiben Sie anschließend nur die Anweisungen, die diese Fehler beheben. Die Fehler bilden die Spezifikation. Deshalb ist ein Skill, den Sie nicht auf einen konkreten Fehler zurückführen können, in der Regel ein Skill, den niemand benötigt.

Ein durchgängiges Beispiel für dieselbe Ableitung finden Sie unter Ponytail macht aus einem wiederholten Fehler, bei dem ein Agent deutlich mehr umschreibt als angefordert, einen Skill. Lesen Sie es vollständig, bevor Sie Ihren eigenen Skill schreiben.

Aufbau eines Skills

Ein Skill ist ein Verzeichnis mit genau einer erforderlichen Datei.

.claude/skills/nginx-config-changes/
├── SKILL.md
├── reference/
│   └── proxy-headers.md
└── scripts/
    └── check-and-reload.sh

SKILL.md beginnt mit einem Frontmatter-Block. Dieser enthält einige in YAML geschriebene Einstellungen. YAML ist dasselbe Konfigurationsformat, das Docker-Compose-Dateien verwenden. Der Block steht zwischen den Markierungen ---. Darauf folgen die Anweisungen in Markdown. Hier ist der vollständige Skill für den oben beschriebenen Fehler.

---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
---

## Rules

Run `sudo nginx -t` after every edit under `/etc/nginx`. Do not touch the service until it prints `test is successful`.

Apply the change with `sudo systemctl reload nginx`. Never use `restart`. A reload keeps the running workers serving traffic until the new config parses, so a broken config leaves the site up. A restart stops nginx first, so a broken config takes the site down.

If `nginx -t` fails, fix the file and test again. Never reload a config that failed the test.

For the proxy header defaults this project expects, see [reference/proxy-headers.md](reference/proxy-headers.md).

Die Datei hat weniger als 20 Zeilen und ist ein vollständiger Skill. Die Bestandteile:

• name: maximal 64 Zeichen, nur Kleinbuchstaben, Ziffern und Bindestriche. Die Wörter claude oder anthropic dürfen nicht enthalten sein. Bei einem persönlichen oder projektspezifischen Skill ist dies nur die Bezeichnung, die angezeigt wird. Der einzugebende Befehl wird aus dem Verzeichnisnamen gebildet. Dieser Skill reagiert daher auf /nginx-config-changes.
• description: beschreibt, was der Skill tut und wann er verwendet werden soll, mit maximal 1.024 Zeichen. Diese Zeile übernimmt die eigentliche Steuerung. Im nächsten Abschnitt geht es ausschließlich darum.
• Der Hauptteil: die Anweisungen, die erst geladen werden, wenn der Skill tatsächlich ausgelöst wird.
• reference/: zusätzliche Dateien, die der Agent bei Bedarf liest. Verknüpfen Sie diese über SKILL.md und halten Sie die Verknüpfungen eine Ebene tief. Eine Datei, auf die aus einer anderen referenzierten Datei verwiesen wird, wird häufig nur teilweise gelesen.
• scripts/: Dateien, die der Agent ausführt, statt sie zu lesen. Nur deren Ausgabe verbraucht Kontext. Daher ist ein 300 Zeilen langes Skript kostengünstig.

Der Speicherort des Verzeichnisses legt fest, für wen der Skill verfügbar ist.

• .claude/skills/<name>/SKILL.md im Repository: nur für dieses Projekt. Der Skill wird an alle Personen weitergegeben, die das Repository klonen.
• ~/.claude/skills/<name>/SKILL.md: für jedes Projekt auf Ihrem Rechner, aber für niemanden sonst.
• <plugin>/skills/<name>/SKILL.md: innerhalb eines Plugins ausgeliefert und überall verfügbar, wo dieses Plugin aktiviert ist.

Erstellen Sie einen Skill mit mkdir -p .claude/skills/nginx-config-changes und schreiben Sie die Datei. Claude Code überwacht diese Verzeichnisse. Änderungen an einem vorhandenen Skill werden daher in der laufenden Sitzung wirksam. Wenn Sie ein übergeordnetes skills-Verzeichnis erstellen, das beim Start der Sitzung noch nicht vorhanden war, müssen Sie die Sitzung neu starten. Beim Sitzungsstart gab es noch nichts, das überwacht werden konnte.

Das Beschreibungsfeld ist die wichtigste Zeile in der Datei

Beim Start lädt der Agent die name und description jedes verfügbaren Skills in seinen Kontext. Die Inhalte lädt er nicht. Wenn Ihre Anfrage eintrifft, ist diese eine Zeile die vollständige Grundlage für die Entscheidung, ob dieser Skill relevant ist. Ein perfekter Inhalt hinter einer unklaren Beschreibung wird daher nie gelesen.

Formulieren Sie die Beschreibung in der dritten Person. „Testet Nginx sicher und lädt es neu“ ist geeignet. „Ich kann Sie bei Nginx unterstützen“ ist nicht geeignet, weil der Text in den System-Prompt eingefügt wird. Dort wirkt die erste Person so, als würde das Modell über sich selbst sprechen.

Nehmen Sie zwei Informationen auf: was der Skill tut und unter welcher Bedingung er angewendet wird. Nennen Sie den wichtigsten Anwendungsfall zuerst, weil Claude Code den Listeneintrag nach 1,536 Zeichen abschneidet. Optional gibt es das Feld when_to_use für zusätzliche Auslösephrasen und Beispielanfragen. Dieses Feld wird unter demselben Limit an die Beschreibung angehängt.

Verwenden Sie anschließend die Wörter, die Sie tatsächlich eingeben werden. description: Helps with nginx führt zu keiner Übereinstimmung, weil niemand „hilft bei“ eingibt. Die obige Version nennt /etc/nginx, server block, reverse proxy und TLS (transport layer security) certificate path. Das entspricht ungefähr dem Vokabular jeder Anfrage, die den Skill auslösen sollte.

So testen Sie eine Beschreibung: Geben Sie die einzelne Zeile zusammen mit der Anfrage, die Sie eingeben möchten, einer Person, die den Inhalt noch nie gesehen hat. Fragen Sie, ob der Skill angewendet werden soll. Wenn die Person das nicht erkennen kann, kann das Modell es ebenfalls nicht erkennen.

Den Inhalt klein halten, weil er im Kontext bleibt

Wenn ein Skill aufgerufen wird, wird sein gerenderter Inhalt als eine Nachricht in die Unterhaltung eingefügt und bleibt für den Rest der Sitzung dort. Claude Code liest die Datei in späteren Nachrichten nicht erneut ein. Jede geschriebene Zeile verursacht Kosten für die gesamte Sitzung, nicht nur für eine Antwort.

Anthropic empfiehlt, SKILL.md unter 500 Zeilen zu halten und Details in separate Dateien auszulagern. Die Komprimierung zeigt, warum diese Zahl nicht willkürlich ist. Wenn die Unterhaltung zusammengefasst wird, um Kontext freizugeben, hängt Claude Code den jeweils letzten Aufruf jedes Skills erneut an, behält davon nur die ersten 5,000 Token und füllt ein gemeinsames Budget von 25,000 Token, beginnend mit dem zuletzt aufgerufenen Skill. Ein langer Skill wird mitten im Inhalt abgeschnitten. Mehrere lange Skills verdrängen sich gegenseitig vollständig.

Schreiben Sie daher nur, was das Modell nicht bereits weiß. Es weiß, was nginx ist und was ein Reverse Proxy macht. Es weiß jedoch nicht, dass bei reload die Regel restart gilt. Nur deshalb existiert diese Datei.

Wenn der Skill den Agenten anweist, ein gebündeltes Skript auszuführen, geben Sie den Pfad mit ${CLAUDE_SKILL_DIR} an, damit er unabhängig vom Installationsort des Skills aufgelöst wird. Genehmigen Sie außerdem denselben Befehl vorab, damit die Ausführung nicht an einer Berechtigungsabfrage anhält.

---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/check-and-reload.sh *)
---

Die Freigabe gilt für den Durchlauf, der den Skill aufgerufen hat, und wird gelöscht, sobald Sie Ihre nächste Nachricht senden. Sie wird daher nicht unbemerkt zu einer dauerhaften Berechtigung.

So weisen Sie nach, dass das Skill ausgelöst wird

Wenn Sie beobachten, dass ein Skill geladen wird, wissen Sie, dass der Agent ihn gefunden hat. Das zeigt jedoch nicht, dass sich die Antwort geändert hat. Prüfen Sie beides und verwenden Sie eine neue Sitzung. Die Sitzung, in der Sie den Skill geschrieben haben, enthält bereits alle Informationen aus dieser Arbeit. Dieser verbleibende Kontext kann Lücken in der Datei verdecken.

1. Starten Sie im Projekt eine neue Sitzung mit claude.
2. Geben Sie die Anfrage so ein, wie Sie sie an einem normalen Arbeitstag formulieren würden, und verwenden Sie Ihre eigenen Worte. Nennen Sie den Skill nicht.
3. Achten Sie auf die Ausführung. Wenn der Skill nicht ausgelöst wird, korrigieren Sie die Beschreibung. Der Inhalt ist zu diesem Zeitpunkt noch nicht das Problem.
4. Führen Sie ihn testweise manuell mit /nginx-config-changes aus. Wenn das Verhalten bei manueller Ausführung korrekt ist, aber bei einer Anfrage nicht, liegt das Problem bei der Auslösung und nicht bei den Anweisungen.
5. Führen Sie dieselbe Anfrage mit deaktiviertem Skill aus und vergleichen Sie die beiden Antworten. Markieren Sie den Skill im Menü /skills und drücken Sie Space, um seinen Zustand auf off zu ändern. Drücken Sie anschließend Enter zum Speichern. Dadurch wird ein Eintrag skillOverrides in .claude/settings.local.json geschrieben. Wenn Sie fertig sind, drücken Sie erneut Space, um den Zustand wieder auf on zu ändern.
6. Schreiben Sie einige Anfragen, die den Skill nicht auslösen sollen, und prüfen Sie, dass er bei diesen Anfragen nicht aktiv wird.

Installieren Sie das skill-creator-Plugin aus dem offiziellen Marketplace, um diesen Ablauf zu automatisieren.

/plugin marketplace add anthropics/claude-plugins-official
/plugin install skill-creator@claude-plugins-official

Wenn die Installationsausgabe Run /reload-plugins to activate. meldet, führen Sie diesen Befehl aus. Bitten Sie Claude anschließend, Ihren Skill anhand seines Namens zu bewerten. Das Plugin speichert Testfälle unter evals/evals.json im Skill-Verzeichnis und führt jeden Fall in einem eigenen Subagent aus. Dadurch beginnt jeder Durchlauf mit einem sauberen Kontext. Anschließend erstellt es einen Vergleich zwischen der Ausführung mit und ohne Skill. Das ist die aussagekräftige Kennzahl: die Verbesserung der Erfolgsrate im Verhältnis zu den Tokens und der Zeit, die der Skill benötigt.

Fehlerbild: Die Skill wird nie aktiviert

Sie geben die Anforderung ein, der Agent führt weiterhin die alte falsche Aktion aus, und es erscheint keine Skill-Zeile. Arbeiten Sie diese Punkte in der angegebenen Reihenfolge durch.

• Die Beschreibung erklärt, was die Skill tut, nennt aber nie, wann sie verwendet werden soll. Daher passt nichts in Ihrer Anforderung zu ihr.
• In der Beschreibung fehlen die Wörter, die Sie eingeben. Wenn Sie „nginx“ sagen, muss die Beschreibung nginx enthalten.
• disable-model-invocation: true ist im Frontmatter gesetzt. Dadurch bleibt die Beschreibung vollständig aus dem Kontext des Modells heraus, und die Skill kann nur von Ihnen mit /name aufgerufen werden.
• Ein paths-Glob im Frontmatter beschränkt die Aktivierung auf passende Dateien. Die Datei, an der Sie arbeiten, passt nicht zu diesem Muster.
• Die Skill liegt in einem verschachtelten Verzeichnis .claude/skills/ unterhalb Ihres Startverzeichnisses. Solche Skills werden erst geladen, nachdem der Agent eine Datei in diesem Unterverzeichnis gelesen oder bearbeitet hat. Bis dahin ist die Skill überhaupt nicht verfügbar.

Fehlermodus: Der Skill wird ständig ausgelöst

Das umgekehrte Problem ist eine Beschreibung, die so allgemein ist, dass der Skill bei nicht zusammenhängenden Arbeiten ausgelöst wird. „Bei Arbeiten am Server verwenden“ passt auf nahezu jede Anfrage in einem Server-Repository. Der Inhalt wird dann für Aufgaben geladen, bei denen er nicht helfen kann, und bleibt für den Rest der Sitzung im Kontext.

Beschränken Sie die Beschreibung auf die tatsächlich relevante Bedingung und nennen Sie die Dateien oder Befehle, für die sie gilt. Fügen Sie einen paths-Glob hinzu, wenn der Skill nur auf bestimmte Dateien angewendet wird. Bei Vorgängen mit Seiteneffekten, etwa einem Deploy oder Commit, setzen Sie disable-model-invocation: true und rufen Sie den Skill selbst mit /name auf. Dadurch entscheidet der Agent nie eigenständig, dass jetzt ein geeigneter Zeitpunkt für ein Deployment ist.

Fehlerfall: Die Regel gehört in die Rules-Datei

Eine Rules-Datei wie CLAUDE.md oder AGENTS.md wird zu Beginn jeder Sitzung geladen und gilt für jede Aufgabe. Der Inhalt eines Skills wird nur geladen, wenn der Skill ausgelöst wird. Entscheidend ist die Häufigkeit. Eine Tatsache, die für jede Aufgabe im Repository gilt, beispielsweise der verwendete Paketmanager, gehört in die Rules-Datei. Ein Verfahren, das nur für einen kleinen Teil der Aufgaben gilt, beispielsweise die obige nginx-Regel, gehört in einen Skill. Dort verursacht es keinen Aufwand, wenn niemand nginx bearbeitet.

Der eigentliche Fehler besteht darin, die Regel an beiden Stellen abzulegen. Zwei Kopien entwickeln sich auseinander. Wenn der Agent dann etwas Falsches tut, lässt sich nicht feststellen, welcher Kopie er gefolgt ist. Legen Sie für jede Anweisung genau einen Ablageort fest. die Abgrenzung zwischen Skills, MCP-Servern und Rules-Dateien hilft auch bei schwierigeren Fällen weiter. Dazu gehört die Frage, wann ein MCP-Server (Model Context Protocol) die richtige Lösung ist, der dem Agenten ein neues Werkzeug statt einer neuen Anweisung bereitstellt.

Teilen Sie es erst, wenn es sich bewährt hat

Eine Fähigkeit, die eine Woche echter Arbeit übersteht, ist es wert, versioniert zu werden. Projektbezogene Fähigkeiten in .claude/skills/ werden wie Code geprüft und zusammen mit dem Repository ausgeliefert. Ein Teammitglied, das das Repository klont, erhält Ihre Korrektur daher ohne zusätzlichen Einrichtungsschritt. Eine Fähigkeit ohne Copy-and-paste zwischen Repositories zu verschieben, ist ein eigenes Problem. Es wird unter Agent-Fähigkeiten zwischen Repositories teilen behandelt.

Ein Hinweis zur Portabilität: Claude Code akzeptiert eine lange Liste von Frontmatter-Feldern. Der Agent Skills-Standard erlaubt jedoch nur sechs: name, description, license, compatibility, metadata und allowed-tools. Wenn Sie eine Fähigkeit mit anderen Frontmatter-Feldern zu claude.ai hochladen oder für die Skills API paketieren, schlägt der Vorgang vollständig fehl, anstatt das Feld zu ignorieren:

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

Beschränken Sie sich auf diese sechs Felder. Dann wird dieselbe Datei in Claude Code und in allen anderen Umgebungen geladen, die den Standard einlesen. Die Anweisungen selbst so zu formulieren, dass sie den Wechsel zu einem anderen Modell überstehen, ist eine separate Aufgabe. Fähigkeiten schreiben, die mit jedem Modell funktionieren behandelt dieses Thema.

FAQ

Wie lang sollte eine SKILL.md-Datei sein?

Halten Sie sie unter 500 Zeilen. Die meisten nützlichen Skills sind deutlich kürzer. Der Inhalt wird beim Aufruf des Skills in die Unterhaltung eingefügt und bleibt für den Rest der Sitzung dort. Jede Zeile verursacht daher wiederkehrende Kosten und nicht nur einmalige Kosten. Verschieben Sie umfangreiches Referenzmaterial in separate Dateien im Skill-Verzeichnis. Verknüpfen Sie diese Dateien über SKILL.md mit einer Verschachtelungstiefe von einer Ebene. So liest der Agent sie nur bei Bedarf. Mitgelieferte Skripte werden ausgeführt und nicht gelesen. Sie verursachen daher nur Kosten für ihre Ausgabe.

Warum wird mein Skill nie ausgelöst?

Die Beschreibung ist normalerweise die Ursache. Sie ist der einzige Teil des Skills, der sich im Kontext befindet, wenn das Modell die Entscheidung trifft. Schreiben Sie daher, wann der Skill verwendet werden soll, und nicht nur, was er tut. Die Beschreibung sollte außerdem die Wörter enthalten, die Sie tatsächlich in Ihren Anfragen verwenden. Wenn die Beschreibung korrekt aussieht, prüfen Sie im Frontmatter disable-model-invocation: true. Diese Einstellung blendet den Skill für das Modell vollständig aus. Prüfen Sie außerdem einen paths-Glob, der den Skill auf Dateien beschränkt, die Sie nicht bearbeiten. Ein Skill in einem verschachtelten .claude/skills/-Verzeichnis unterhalb Ihres Startverzeichnisses ist eine weitere mögliche Ursache. Er wird erst geladen, nachdem der Agent eine Datei in diesem Unterverzeichnis gelesen oder bearbeitet hat.

Sollte dies ein Skill oder eine Zeile in meiner Regeldatei sein?

Prüfen Sie, auf wie viele Ihrer Aufgaben die Anweisung zutrifft. Eine Regeldatei wird in jeder Sitzung geladen. Sie sollte daher Fakten enthalten, die für jede Aufgabe gelten, beispielsweise den Paketmanager oder die Konvention für Branch-Namen. Ein Skill wird nur geladen, wenn er ausgelöst wird. Er eignet sich daher für ein Verfahren, das nur bei einem kleinen Teil der Aufgaben erforderlich ist. Schreiben Sie dieselbe Anweisung niemals an beide Stellen. Die beiden Kopien können voneinander abweichen. Dann lässt sich nicht mehr feststellen, welcher Anweisung der Agent gefolgt ist.

Woran erkenne ich, dass ein Skill tatsächlich geholfen hat?

Vergleichen Sie ihn mit einer Baseline. Sammeln Sie einige reale Anfragen. Führen Sie jede Anfrage zunächst in einer neuen Sitzung mit verfügbarem Skill aus. Führen Sie sie anschließend erneut aus, wobei Sie den Skill im Menü /skills deaktivieren. Lesen Sie beide Antworten direkt nebeneinander. Eine neue Sitzung ist wichtig. Die Unterhaltung, in der Sie den Skill geschrieben haben, enthält weiterhin Ihre Erklärungen. Dadurch kann eine unvollständige Datei vollständig wirken. Das Plugin skill-creator führt diesen Vergleich für Sie aus und meldet die Erfolgsquote neben den Token-Kosten.

Kann ich dieselbe SKILL.md mit einem anderen Agenten verwenden?

Ja, sofern Sie sich auf die Felder beschränken, die der Agent Skills-Standard definiert: name, description, license, compatibility, metadata und allowed-tools. Claude Code akzeptiert viele weitere Felder. Außerdem unterstützt es Funktionen im Inhalt, beispielsweise die Injektion von Shell-Befehlen, die andere Tools nicht ausführen. Das Hochladen eines Skills mit einem Feld außerhalb des Standards schlägt mit einem expliziten Fehler fehl. Dieser listet die zulässigen Eigenschaften auf. Entscheiden Sie daher frühzeitig, ob ein Skill nur in Claude Code verwendet werden soll oder zwischen Tools übertragen werden muss.