Skip to main content
Skills werden als SKILL.md-Dateien in einem entsprechend benannten Verzeichnis definiert. Auf dieser Seite finden Sie alles, was Sie wissen müssen, um wirkungsvolle Skills zu schreiben.

Dateistruktur

Lege Skills je nach Geltungsbereich im entsprechenden Verzeichnis ab:
Der Verzeichnisname ist die Kennung des Skills (wird für den Aufruf von /my-skill verwendet). Die Datei SKILL.md enthält optionales YAML-Frontmatter und den Prompt-Inhalt des Skills.
Unter Windows bezieht sich %APPDATA% typischerweise auf C:\Users\<YourUser>\AppData\Roaming.

Frontmatter-Referenz

Alle Frontmatter-Felder


Modell-Override

Verwenden Sie das Feld model, um ein Skill mit einem anderen Modell auszuführen als dem aktiven Modell der aktuellen Sitzung. Das ist nützlich, wenn Sie für einfache Aufgaben ein schnelleres Modell oder für komplexe Aufgaben ein leistungsfähigeres Modell verwenden möchten:
Der Modellname verwendet dieselben Werte wie das CLI-Flag --model (z. B. opus, sonnet, swe, codex). Die vollständige Liste finden Sie unter Models.

Skills als Subagents ausführen

Das Ausführen von Skills als Subagents ist experimentell. Die Frontmatter-Felder subagent und agent können sich in zukünftigen Releases ändern.
Standardmäßig wird der Prompt eines Skills in die aktuelle Unterhaltung eingefügt — der Agent verarbeitet ihn inline. Alternativ können Sie einen Skill als Subagent ausführen. Dabei wird ein unabhängiger Worker mit eigenem Kontextfenster gestartet. Das ist nützlich für Skills, die fokussierte, in sich abgeschlossene Aufgaben ausführen und deren Ausgabe die Hauptunterhaltung nicht überladen soll. Es gibt zwei Möglichkeiten, einen Skill als Subagent auszuführen:

subagent: true

Setze subagent: true, um den Skill mit dem Standardprofil subagent_general als Subagent auszuführen:
Wenn dieses Skill aufgerufen wird, startet es einen Subagenten im Vordergrund, der den Prompt des Skills als Aufgabe ausführt. Der übergeordnete Agent wartet, bis der Subagent seine Arbeit abgeschlossen hat, liest anschließend die Ergebnisse und fasst sie zusammen.
Wenn ein Skill als Subagent ausgeführt wird, werden dessen Frontmatter-Einträge allowed-tools und permissions nicht angewendet. Der Subagent läuft mit dem Tool-Satz seines Profils — subagent_general hat Zugriff auf alle Tools. Um einzuschränken, welche Tools ein Subagent-Skill verwenden darf, definiere ein benutzerdefiniertes Subagent-Profil mit allowed-tools und verweise darauf mit agent: statt mit subagent: true.

agent: <profile>

Verwende das Feld agent, um den Skill als Subagent mit einem bestimmten benutzerdefinierten Subagent-Profil auszuführen:
Der Wert agent muss dem Namen eines registrierten Subagent-Profils entsprechen (entweder eines integrierten Profils wie subagent_explore / subagent_general oder eines benutzerdefinierten Profils, das Sie definiert haben). Der Subagent übernimmt den System-Prompt, die Tool-Einschränkungen und das Modell des Profils — der Inhalt des Skills wird dabei zur Aufgabe. Die allowed-tools eines benutzerdefinierten Profils stellen eine echte Einschränkung dar (nicht aufgeführte Tools stehen dem Subagenten nicht zur Verfügung) — auf diese Weise führen Sie einen Skill mit einem begrenzten Tool-Satz aus.
Wenn sowohl agent als auch subagent gesetzt sind, hat agent Vorrang. Das Feld model im Skill überschreibt das Modell des Subagent-Profils, wenn beide angegeben sind.
Skills, die als Subagenten ausgeführt werden, erzeugen keine verschachtelten Subagenten — wenn ein Skill bereits innerhalb eines Subagenten ausgeführt wird, wird er stattdessen inline ausgeführt, um eine unendliche Rekursion zu verhindern.

Subagents mithilfe von Skills orchestrieren

Da Skills als Subagenten ausgeführt werden können, lassen sie sich zum Orchestrieren mehrstufiger Abläufe verwenden. Definieren Sie eine Reihe von Subagent-Skills, die jeweils eine klar abgegrenzte Aufgabe übernehmen, und schreiben Sie dann einen regulären Skill, der sie aufruft. Der übergeordnete Skill fungiert als Orchestrator — er ruft jeden Subagenten auf, sammelt die Ergebnisse und entscheidet, was als Nächstes zu tun ist. Zum Beispiel finden Sie hier zwei Subagent-Skills und einen Orchestrator, der sie koordiniert:
Das Aufrufen von /health-check führt den Orchestrator im Haupt-Agenten aus. Dabei wird /research-changes aufgerufen, das einen Subagenten startet, um das Repo zu untersuchen. Sobald das abgeschlossen ist, wird /validate-tests aufgerufen, das einen weiteren Subagenten startet, um die Tests auszuführen. Der Orchestrator führt anschließend beide Ergebnisse in einer abschließenden Zusammenfassung zusammen. Ein Subagenten-Skill setzt beim Aufrufen anderer Skills niemals einen Subagenten ein, selbst wenn diese Skills subagent: true haben — sie werden stattdessen inline ausgeführt. Das bedeutet, dass du dir keine Gedanken über unbegrenzte Verschachtelung machen musst. Das Orchestrierungsmuster geht immer nur eine Ebene tief: Der Orchestrator startet Subagenten, und diese Subagenten führen alles andere inline aus.

Prompt-Inhalt

Der Inhalt der Datei SKILL.md (nach dem frontmatter) ist der Prompt, der beim Aufrufen des Skills eingefügt wird.

Berechtigungen

Skills können ihren eigenen Geltungsbereich mit derselben Syntax wie die Hauptkonfiguration der Berechtigungen definieren:
So funktionieren Skill-Berechtigungen:
  • allow — Diese Geltungsbereiche werden bei der Skill-Ausführung automatisch freigegeben
  • deny — Diese Geltungsbereiche werden bei der Skill-Ausführung blockiert
  • ask — Bei diesen Geltungsbereichen wird der Nutzer immer zur Bestätigung aufgefordert
Mit deny lässt sich ein Tool für einen Inline-Skill vollständig sperren. Einträge mit Tool-Namen wie exec oder edit blockieren das gesamte Tool, und mcp__server__tool-Muster blockieren MCP-Tools — siehe Tool-basierte Berechtigungen.
Skill-Berechtigungen sind additiv zu den Basisberechtigungen der Sitzung (sie ersetzen sie nicht). Ein Skill kann keine Berechtigungen gewähren, die auf einer höheren Ebene verweigert werden (in der Projekt- oder Organisationskonfiguration).
Skill-Berechtigungen gelten nur, wenn der Skill inline ausgeführt wird. Sie werden nicht angewendet, wenn der Skill als Subagent ausgeführt wird (subagent: true oder agent:).

Automatisch genehmigte Tools

allowed-tools listet Tools auf, die während der Ausführung des Skills automatisch genehmigt sind, sodass der Agent sie ohne Berechtigungsabfrage verwenden kann:
Jeder Eintrag entspricht einem permissions.allow-Eintrag für den jeweiligen Tool-Namen. Verfügbare Tool-Namen: read, edit, grep, glob, exec Sie können auch MCP-Tools automatisch genehmigen:
allowed-tools ist keine Einschränkung. Tools, die nicht aufgeführt sind, bleiben für den Skill verfügbar und durchlaufen die normalen Berechtigungsprüfungen (Rückfrage beim Nutzer oder Ausführung ohne Rückfrage, sofern die Berechtigungen der Sitzung dies bereits erlauben). Das Weglassen von allowed-tools ändert nichts daran, welche Tools der Skill verwenden kann – es bedeutet lediglich, dass kein Tool vorab genehmigt ist.Um einen Skill tatsächlich an der Nutzung eines Tools zu hindern:
  • Fügen Sie bei Inline-Skills den Tool-Namen zu permissions.deny hinzu (siehe Berechtigungen).
  • Definieren Sie bei Subagent-Skills ein benutzerdefiniertes Subagent-Profil mit allowed-tools und führen Sie den Skill mit agent: <profile> aus. Bei einem Subagent-Profil schränkt allowed-tools den Tool-Satz ein, bei einem Skill hingegen nicht.

Beispiele

Code-Review-Skill

Komponentengenerator

Bereitstellungs-Checkliste

Suchprofi


Tipps

Prompts fokussiert halten

Ein Skill sollte eine Sache gut machen. Erstelle mehrere Skills statt eines Mega-Skills.

Beispiele hinzufügen

Zeige dem Agenten in deinem Prompt, wie eine gute Ausgabe aussieht.

Verweigern, was ein Skill nicht tun darf

Verwende permissions.deny (oder ein benutzerdefiniertes Subagent-Profil), um Tools zu blockieren. allowed-tools überspringt lediglich Prompts.

Mit /skill-name testen

Führe deinen Skill aus und passe den Prompt iterativ an, bis die Ausgabe deinen Vorstellungen entspricht.