Codex Agent Skills Skill-System
Agent Skills sind Codex' Mechanismus zur Aufgabenerweiterung. Durch das Verpacken von Anweisungen, Ressourcen und optionalen Skripten in standardisierte Skill-Pakete ermöglichen sie Codex, bestimmte Workflows zuverlässig auszuführen.
Ein Agent Skill ist im Wesentlichen ein Ordner, der eineSKILL.md-Datei enthalten muss. Die Datei muss mindestens Metadaten wie Name und Beschreibung sowie eine Anleitung bereitstellen, die dem KI-Agenten erklärt, wie er eine bestimmte Aufgabe erledigt. Skill-Pakete können auch Skripte, Referenzmaterialien, Vorlagen und verschiedene andere Ressourcen integrieren.
my-skill/ ├── SKILL.md # 必备文件：元数据 + 执行指引 ├── scripts/ # 可选：可执行脚本 ├── references/ # 可选：参考文档 ├── assets/ # 可选：模板、各类资源文件 └── ... # 其他额外文件与目录
Terminologie
- KI-Agenten: KI-intelligenter Agent (gängige Branchenübersetzung)
- Agent Skills: Agent Skill (proprietäres Konzept, feste Bezeichnung beibehalten)
- Metadaten: Metadaten
- Workflows: Geschäftsprozess/Ausführungsablauf
Was sind Agent Skills
Skills sind ein Autorenformat für wiederverwendbare Workflows.
Jeder Skill ist im Wesentlichen ein Verzeichnis, das eineSKILL.md-Datei enthält. Codex liest die darin enthaltenen Anweisungen und führt sie Schritt für Schritt aus.
Du kannst dir einen Skill als eine für Codex geschriebene „Standard Operating Procedure“ vorstellen – sie legt klar fest, was zu tun ist, wann es zu tun ist und wie es zu tun ist. Codex kann ihn dann automatisch zum richtigen Zeitpunkt aktivieren oder ausführen, wenn du ihn explizit aufrufst.
Skills sind ein „Authoring-Format“, während Plugins ein „Distribution-Format“ sind. Nutze zuerst Skills, um den Workflow selbst zu entwerfen; paketiere ihn als Plugin, wenn du ihn an andere Entwickler verteilen musst.
Skills sind in der Codex CLI, der IDE-Erweiterung und der Codex App verfügbar.
Du kannst Skills im Plugin anzeigen oder erstellen:
Codex verfügt über einen integriertenSkill Creator; klicke aufSkill erstellen, um zum Skill-Erstellungsfenster zu springen, wo wir ihm direkt sagen können, welchen Skill es erstellen soll:
Installierte Skills anzeigen:
So funktionieren Skills
Codex verwendet einenProgressive Disclosure-Mechanismus, um das Kontextfenster zu verwalten, wodurch vermieden wird, den gesamten Skill-Inhalt auf einmal zu laden und den Prompt-Platz zu verdrängen.
Progressiver Ladeprozess
Beim Start lädt Codex nur den Namen, die Beschreibung und den Dateipfad jedes Skills als initiale Liste.
Erst wenn Codex entscheidet, einen Skill zu verwenden, lädt es den vollständigenSKILL.md-Anweisungsinhalt.
Um zu vermeiden, dass der Prompt-Platz verdrängt wird, ist die Zeichenanzahl der initialen Skill-Liste aufetwa 2% des Kontextfensters des Modells, oder auf 8,000 Zeichen begrenzt, wenn das Kontextfenster unbekannt ist.
Wenn zu viele Skills installiert sind, kürzt Codex zuerst die Beschreibungen; wird das Limit weiterhin überschritten, erscheinen einige Skills möglicherweise nicht in der initialen Liste, und Codex zeigt eine Warnung an.
Diese Budgetbeschränkung gilt nur für die anfängliche Skill-Liste. Nachdem Codex einen Skill ausgewählt hat, liest es weiterhin die vollständige SKILL.md-Datei für diesen Skill.
Zwei Trigger-Methoden
Codex unterstützt zwei Möglichkeiten zum Aktivieren von Skills:
Expliziter Aufruf
Referenzieren Sie den Skill direkt im Prompt. Verwenden Sie in der CLI oder IDE den Befehl/skillsoder geben Sie$ein Symbol ein, um einen Skill anzugeben.
Bei einem expliziten Aufruf muss Codex keine Abgleichsentscheidung treffen; es lädt direkt die vollständige SKILL.md und führt sie aus.
Impliziter Abgleich
Wenn die von Ihnen angegebene Task-Beschreibung mit demdescription-Feld eines Skills übereinstimmt, wählt Codex diesen Skill automatisch aus.
Die Genauigkeit des impliziten Abgleichs hängt vollständig von der Qualität des description-Felds ab.
Wenn Sie die Beschreibung schreiben, stellen Sie die zentralen Anwendungsfälle und Trigger-Schlüsselwörter an den Anfang, damit Codex auch dann noch korrekt zuordnen kann, wenn die Beschreibung abgeschnitten wird.
Skill-Verzeichnisstruktur
Ein Skill ist ein Verzeichnis, dasSKILL.md-Dateien enthält und optionale Skripte, Referenzdokumentation, Ressourcendateien und Metadatenkonfiguration enthalten kann.
my-skill/
├── SKILL.md # 必备项：使用指引 + 元数据
├── scripts/ # 可选：可执行代码
├── references/ # 可选：参考文档
├── assets/ # 可选：模板、各类资源
└── agents/
└── openai.yaml
Die Zuständigkeiten der einzelnen Dateien/Verzeichnisse sind wie folgt:
| Datei/Verzeichnis | Erforderlich? | Beschreibung |
|---|---|---|
| SKILL.md | Erforderlich | Die zentrale Anweisungsdatei für den Skill; muss dasname- unddescription-Feld enthalten |
| scripts/ | Optional | Enthält ausführbaren Code, der für Szenarien verwendet wird, die deterministisches Verhalten oder den Aufruf externer Tools erfordern |
| references/ | Optional | Enthält zusätzliche Referenzdokumentation, die Codex während der Ausführung des Skills konsultieren kann |
| assets/ | Optional | Enthält statische Ressourcendateien wie Vorlagen und Bilder |
| agents/openai.yaml | Optional | Konfiguriert UI-Metadaten, Aufrufrichtlinie und Tool-Abhängigkeitsdeklarationen |
Schnellstart: Erstellen Sie Ihren ersten Skill
Es wird empfohlen, den integrierten Skill-Ersteller zu verwenden, um schnell ein Skill-Framework zu generieren.
Mit skill-creator erstellen
Geben Sie den folgenden Befehl in Codex ein, um den interaktiven Erstellungsablauf zu starten:
Beispiel
$skill-creator
Der Ersteller wird die folgenden Fragen in dieser Reihenfolge stellen:
| Schritt | Frage | Beschreibung |
|---|---|---|
| 1 | Was macht dieser Skill? | Definieren Sie die Aufgabe, die der Skill erfüllen soll |
| 2 | Wann soll er ausgelöst werden? | Entscheiden Sie, ob er durch expliziten Aufruf oder implizites Matching ausgelöst wird |
| 3 | Reine Anweisungen oder enthält Skripte? | Reiner Instruktionsmodus wird standardmäßig empfohlen, da er prägnant und einfach zu pflegen ist |
Manuelle Erstellung
Sie können das Skill-Verzeichnis und die SKILL.md-Datei auch manuell erstellen:
Beispiel
name: my-skill
description: Erklären Sie, wann dieser Skill ausgelöst werden sollte und wann nicht.
---
Codex führt die Aufgabe aus, indem es die folgenden Skill-Anweisungen befolgt.
Codex erkennt Änderungen an Skill-Dateien automatisch. Wenn ein Skill nach einer Aktualisierung nicht sofort wirksam wird, starten Sie Codex bitte neu.
Konfigurationsanleitung
Speicherort für Skills
Codex liest Skills aus vier Geltungsbereichen: Repository-Ebene, Benutzerebene, Admin-Ebene und Systemebene.
Auf Repository-Ebene durchsucht Codex vom aktuellen Arbeitsverzeichnis aus aufwärts bis zum Repository-Stamm und sucht nach dem.agents/skills-Verzeichnis.
Wenn zwei Skills denselbennamehaben, führt Codex sie nicht zusammen; beide werden im Skill-Auswahlmenü angezeigt.
| Geltungsbereich | Speicherpfad | Anwendungsszenario |
|---|---|---|
| REPO | $CWD/.agents/skills | Skills im aktuellen Arbeitsverzeichnis, geeignet für teamweit geteilte Skills für ein bestimmtes Modul oder einen Microservice |
| REPO | $CWD/../.agents/skills | Skills in übergeordneten Verzeichnissen, geeignet für gemeinsam genutzte Bereiche in verschachtelten Verzeichnisstrukturen |
| REPO | $REPO_ROOT/.agents/skills | Skills im Repository-Stammverzeichnis, geeignet für Basis-Skills, die in allen Unterverzeichnissen des gesamten Repositorys gemeinsam genutzt werden |
| USER | $HOME/.agents/skills | Ein persönliches Skill-Set eines Benutzers, geeignet für Skills, die der Benutzer in jedem Repository verwenden kann |
| ADMIN | /etc/codex/skills | Gemeinsam genutzte Skills auf Maschinen- oder Containerebene, geeignet für SDK-Skripte, Automatisierung und Admin-Standard-Skills |
| SYSTEM | Standardmäßig von OpenAI mitgeliefert | Integrierte Skills für ein breites Publikum, wie skill-creator und Plan-Skills, verfügbar für alle Benutzer, sobald sie Codex starten |
Codex unterstützt symbolische Links für Skill-Verzeichnisse und folgt beim Scannen dem Symlink-Ziel.
Der obige Pfad gilt für die lokale Entwicklung und Erkennung. Wenn Sie Skills an Benutzer außerhalb eines einzelnen Repositorys verteilen oder sie zusammen mit einer Anwendungsintegration paketieren möchten, verwenden Sie den Plugins-Mechanismus.
Aktivieren und Deaktivieren von Skills
In~/.codex/config.tomlkönnen Sie einen Skill deaktivieren, ohne Dateien zu löschen, indem Sie die[[skills.config]]-Konfigurationsoption verwenden:
Beispiel
[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false
Nach dem Ändern der Konfigurationsdatei müssen Sie Codex neu starten, damit die Änderungen wirksam werden.
Optionale Metadaten-Konfiguration
Inagents/openai.yamlkönnen Sie UI-Metadaten, Aufrufrichtlinien und Tool-Abhängigkeitsdeklarationen für Skills konfigurieren:
Beispiel
# UI-Konfiguration: steuert, wie das Skill in der Codex App angezeigt wird
interface:
display_name: "Anzeigename für Benutzer"
short_description: "Kurzbeschreibung für Benutzer"
icon_small: "./assets/s-logo.svg"
icon_large: "./assets/large-logo.png"
brand_color: "#3B82F6"
default_prompt: "Optionaler zusätzlicher Prompt zur Verwendung mit dem Skill"
# Richtlinienkonfiguration: steuert das Aufrufverhalten des Skills
Richtlinie:
allow_implicit_invocation: false # Auf false setzen, um implizites Matching zu deaktivieren
# Abhängigkeitskonfiguration: deklariert die für den Skill erforderlichen Tools
dependencies:
tools:
- type: "mcp"
value: "openaiDeveloperDocs" # MCP-Servername
description: "OpenAI Docs MCP-Server"
transport: "streamable_http" # Transportprotokoll
url: "https://developers.openai.com/mcp" # MCP-Dienstadresse
allow_implicit_invocationDer Standardwert vontrueist. Wenn er auffalsegesetzt wird, ruft Codex den Skill nicht implizit basierend auf Benutzeraufforderungen auf, sondern der explizite$skill-Aufruf funktioniert weiterhin.
| Konfigurationseintrag | Type | Standardwert | Beschreibung |
|---|---|---|---|
| interface.display_name | String | Leer | Der in der Codex App angezeigte Name |
| interface.short_description | String | Leer | Die in der Codex App angezeigte Kurzbeschreibung |
| interface.icon_small | Pfad | Leer | Pfad zum kleinen Symbol (SVG-Format) |
| interface.icon_large | Pfad | Leer | Pfad zum großen Symbol (PNG-Format) |
| interface.brand_color | Farbwert | Leer | Für die UI-Anzeige verwendete Markenfarbe |
| interface.default_prompt | String | Leer | Der standardmäßige periphere Prompt, der verwendet wird, wenn dieser Skill verwendet wird |
| policy.allow_implicit_invocation | Boolean | wahr | Ob Codex den Skill implizit zuordnen und aufrufen darf |
| dependencies.tools | Array | Leer | Deklariert die MCP-Tools, von denen der Skill abhängt; jedes Element muss Typ, Wert, Beschreibung usw. angeben. |
Verteilung und Installation von Skills
Verteilung von Skills über Plugins
Ein direkter Skill-Ordner eignet sich für lokales Authoring und repositorybezogene Workflows.
Wenn du wiederverwendbare Skills verteilen, mehrere Skills zusammen bündeln oder Skills gemeinsam mit Anwendungsintegration veröffentlichen möchtest, solltest du sie als einPlugin paketieren。
Ein Plugin kann einen oder mehrere Skills enthalten und optional Anwendungszuordnungen, MCP-Server-Konfigurationen und Präsentations-Assets bündeln.
Installation empfohlener Skills
Du kannst$skill-installerverwenden, um kuratierte Skills über die integrierten hinaus in der lokalen Codex-Umgebung zu installieren.
Zum Beispiel installieren Sie den$linearSkill:
Beispiel
$skill-installer linear
Sie können Skills auch über skill-installer aus anderen Repositories herunterladen.
Codex erkennt neu installierte Skills automatisch. Wenn sie nicht sofort erscheinen, starten Sie Codex neu.
skill-installer eignet sich für lokale Einrichtung und Experimente. Um Ihre eigenen Skills zur Wiederverwendung zu verteilen, bevorzugen Sie den Plugins-Mechanismus.
Best Practices
| Prinzip | Beschreibung | Anwendungsszenario |
|---|---|---|
| Ein Skill erledigt eine Sache | Konzentrieren Sie jeden Skill auf eine einzige Verantwortlichkeit; vermeiden Sie, einen Skill mit zu vielen unzusammenhängenden Aufgaben zu laden | Alle Skills sollten Folgendes befolgen |
| Anweisungen statt Skripte | Wenn ein Prozess mit Anweisungen beschrieben werden kann, schreiben Sie kein Skript, es sei denn, deterministisches Verhalten oder der Aufruf externer Tools ist erforderlich | Der reine Anweisungsmodus wird für die meisten Szenarien empfohlen |
| Verwende imperativische Satzmuster | Schreibe Schritte mit imperativen Sätzen und gib Eingabe und Ausgabe jedes Schritts klar an | Beim Schreiben von SKILL.md-Anweisungen |
| Teste die Treffsicherheit von description | Verwende echte Prompts, um zu testen, ob der Skill korrekt ausgelöst wird, und stelle die Präzision von description sicher | Nach dem Schreiben des Skills |
| Erforderliche zentrale Triggerwörter | Setze wichtige Anwendungsfälle und Triggerwörter an den Anfang von description, um sicherzustellen, dass auch nach einer Kürzung ein Matching erfolgt. | Wenn die description gekürzt werden kann |
Häufig gestellte Fragen
Skill-Updates werden nicht wirksam?
Codex erkennt Änderungen an Skill-Dateien automatisch.
Wenn der Skill nach der Aktualisierung nicht in der Liste erscheint, starte Codex neu.
Was passiert, wenn zwei Skills denselben Namen haben?
Codex führt Skills mit demselben Namen nicht zusammen; beide werden in der Skill-Auswahl angezeigt.
Es wird empfohlen, die Verwendung desselben Skill-Namens in verschiedenen Bereichen zu vermeiden, um Verwirrung zu vermeiden.
Was ist, wenn das implizite Matching ungenau ist?
Prüfe zuerstBeschreibung, ob die Nutzungsszenarien und Grenzen des Skills klar beschrieben sind.
Setze die wichtigsten Trigger-Wörter an den Anfang und vermeide, dass wichtige Informationen in der zweiten Hälfte der Beschreibung auftauchen.
Wenn kein implizites Matching benötigt wird, kannst du inagents/openai.yamldie Einstellungallow_implicit_invocationauffalse setzen。
Wann verwendet man Skills und wann Plugins?
Skills ist ein Authoring-Format, geeignet für lokale Entwicklung und Team-Sharing innerhalb eines Repositorys.
Wenn du Skills an andere Entwickler verteilen, mehrere Skills bündeln oder sie zusammen mit einer Anwendungsintegration veröffentlichen möchtest, verwende das Plugins-Format.
Wie geht man mit einer abgeschnittenen anfänglichen Skill-Liste um?
Vereinfache die Beschreibung jedes Skills, um sie kurz und präzise zu machen.
Stelle sicher, dass die wichtigsten Auslösewörter ganz am Anfang der Beschreibung stehen, damit die Zuordnung auch bei Kürzung korrekt funktioniert.
Für Fähigkeiten, die für die aktuelle Aufgabe nicht häufig verwendet werden, ziehe in Betracht, sie vorübergehend zu deaktivieren.
Weitere Erweiterungen