Agent Skills

Progressive Disclosure

Drei Stufen, dieselben drei, die die Spezifikation beschreibt:

• Der Katalog. In jedem Turn enthält der Prompt des Agenten ein Menü der Skills, die relevant aussehen: Titel, einzeilige Beschreibung, Slug. Nie den Text. Standardmäßig drei Skills pro Turn, höchstens sechs.
• Aktivierung. Der Agent ruft das Tool load_playbook mit einem Slug auf, um die vollständigen Schritte zu lesen. Das Slug-Argument ist pro Turn an ein Enum aus genau den Slugs des Menüs dieses Turns gebunden – ein erfundener Name wird vor dem Versand abgelehnt, statt den Agenten einen Roundtrip zu kosten. Gibt es kein Menü, wird das Tool gar nicht erst registriert.
• Ressourcen. Noch nicht. Eine Skill ist hier eine einzelne SKILL.md; mitgelieferte Ordner scripts/, references/ und assets/ werden geparst und ignoriert, statt halb unterstützt zu werden.

Ist eine Skill einmal geladen, bleibt sie geladen. Agentenläufe verdichten ältere Tool-Ergebnisse, um Kosten zu sparen, und aktivierte Skills sind davon ausgenommen: Ihre Anweisungen bleiben für den Rest des Laufs wortgetreu erhalten, wie lang er auch wird. Eine Skill, die mitten in der Aufgabe stillschweigend verschwindet, ist schlimmer als eine, die nie geladen wurde.

Welche Skills ins Menü kommen

Zwei Durchgänge. Trigger-Stichwörter werden ohne Beachtung der Groß- und Kleinschreibung als Teilstrings mit dem Turn abgeglichen; danach füllt ein semantischer Durchgang die Liste anhand eines Embeddings aus Titel, Beschreibung, Triggern und dem Anfang des Textes jeder Skill auf, zugelassen erst oberhalb einer kalibrierten Ähnlichkeitsschwelle. Eine Skill ohne Trigger ist immer aktiv und wird immer angeboten. Das Modell entscheidet, was es aktiviert – nichts hier zwingt ihm eine Skill auf.

Eine Skill hineinbringen

• Die Bibliothek. Kuratierte Pakete, mit einem Klick auf einem Agenten installiert. Das ist die Entdeckungsfläche, die die meisten nutzen.
• Selbst schreiben. Titel, Beschreibung, Trigger-Wörter und die Schritte, im Tab Playbooks des Agenten.
• Die API. POST /api/agents/:id/playbooks/import nimmt { files: [{ name, content }] } entgegen und importiert jede Datei unabhängig – eine fehlerhafte Datei scheitert allein, der Rest kommt trotzdem an. Jede Datei wird sicherheitsgeprüft, bevor irgendetwas gespeichert wird, und ein Import überschreibt nie eine bestehende Skill: Eine Slug-Kollision kommt als übersprungen zurück.
• Aus einem Dokument eine Skill kompilieren. POST /api/agents/:id/playbooks/generate nimmt { artifactId } – ein Dokument, das schon im Workspace liegt – oder { content, sourceName } entgegen und schreibt einen Ablauf aus dem, was das Dokument vermittelt: wann er greift, die Schritte, die Entscheidungsregeln, das Vokabular. Das ist nicht die Upload-Pipeline, die ein Dokument in Passagen verwandelt, die ein Agent nachschlagen kann; hier wird daraus etwas, das der Agent tut. Der Ablauf wird neu geschrieben, nie ausgezogen: Die Quelle kann das urheberrechtlich geschützte Handbuch eines anderen sein, und ein Playbook, das daraus zitiert, wäre eine Kopie davon. Lange Dokumente werden vom Anfang bis zu einer Grenze gelesen, und die Antwort sagt, wann gekürzt wurde. Das Ergebnis kommt inaktiv an: Niemand hat diese Worte geschrieben, also liest ein Mensch den Entwurf und schaltet ihn ein, oder er läuft nie.

Es gibt absichtlich keinen Upload-Button in der Oberfläche. Eine SKILL.md wird zur dauerhaften Anweisung für einen Agenten, der die Tools eines Workspaces hält; eine beliebige hochgeladene Datei ist deshalb ein Prompt-Injection-Vektor und keine Bequemlichkeit. Die oben genannte API-Route nur für Eigentümer ist die bewusste Ausnahme.

Eine Skill herausholen

Jede Skill lässt sich als Zip exportieren, das <name>/SKILL.md enthält – die Verzeichnisform aus der Spezifikation, keine lose Datei. Entpacke sie nach ~/.agents/skills/ oder .claude/skills/, und sie lädt in diesem Client, ohne dass etwas umbenannt werden muss, und skills-ref validate besteht sie unverändert. API-Aufrufer, die nur die einzelne Datei wollen, können stattdessen text/markdown anfordern.

Das Frontmatter enthält name und description. Unsere eigenen Erweiterungen – Trigger-Wörter, Reihenfolge und eine Markierung, dass die Datei von hier stammt – laufen unter metadata mit, weil der Referenz-Validator der Spezifikation unbekannte Schlüssel auf oberster Ebene ablehnt und ein Export von uns nie die Datei sein soll, an der er scheitert.

Was wir nicht übernehmen

• allowed-tools wird immer verworfen. Die Spezifikation definiert es als Tools, die für eine Skill vorab freigegeben werden – genau das Falsche, wenn es aus einer Datei kommt, die über eine API oder aus einem geteilten Paket eintrifft: Importierte Inhalte könnten damit ihre eigene Tool-Berechtigung erweitern. Welche Tools ein Agent aufrufen darf, ist eine Eigenschaft seiner Rolle, nie einer Datei, die er gelesen hat.
• compatibility wird verworfen aus einem nüchterneren Grund: Es beschreibt die Umgebung, für die die Skill geschrieben wurde, und sagt nichts über unsere.
• Alles außerhalb des dokumentierten Frontmatters wird ignoriert, statt erraten zu werden. Der Parser akzeptiert die kleine, feste Form, die die Spezifikation definiert, und nichts Exotisches.

Limits

Dreißig Skills pro Agent, 64 kB pro importierter Datei und ein begrenzter Text – eine Skill, die nicht mehr in dieses Budget passt, sind zwei Skills. Namen bestehen aus Kleinbuchstaben, Ziffern und einzelnen Bindestrichen: Die Spezifikation erlaubt mehr, aber der Name ist hier auch eine URL.

Anderswo

Die Spezifikation ist maßgeblich für das Format. Zur HTTP-API, mit der Agenten im Netzwerk handeln, siehe die API-Dokumentation.