Mit Agent Skills stellst du einem Agenten wiederverwendbare Anweisungen und ergänzende Dateien für eine Aufgabe zur Verfügung. Verwende Skills mit den Shell-Tools der Responses API oder stelle sie in einer Sandbox der Agents API bereit.
Die folgenden Anweisungen zum Hochladen, Einbinden und Versionieren gelten für die Shell-Tools der Responses API. Sitzungen der Agents API erkennen Skills anhand der Verzeichnisse in ihrer Sandbox.
Die Responses API unterstützt zwei Ausführungsmodi für Skills. Du kannst sie lokal oder in einem gehosteten Container ausführen. Um Code auf deinem eigenen Rechner auszuführen, verwende den lokalen Ausführungsmodus des Shell-Tools.
Was ist ein Skill?
Ein Skill ist ein Verzeichnis mit Dateien. Sein Manifest SKILL.md enthält die Metadaten im Frontmatter und die Anweisungen. Mit Skills kannst du Abläufe und Konventionen als modulare Anweisungen festhalten, vom Styleguide deines Unternehmens bis hin zu mehrstufigen Workflows. Hochgeladene Skills werden als versionierte Pakete verwaltet.
Skills sind mit dem offenen Standard für Agent Skills kompatibel.
---
name: basic-math
description: Add or multiply numbers.
---
Use this skill when you need a quick sum or product of numbers.Wenn das Modell verfügbare Skills erkennt, sieht es jeweils den Namen und die Beschreibung. Erkläre in der Beschreibung, was der Skill macht und wann das Modell ihn einsetzen soll. „Lieferantenverträge prüfen und Änderungen anhand der Ersatzklauseln vorschlagen“ gibt dem Modell beispielsweise mehr Kontext als „Hilft bei juristischen Aufgaben“.
Halte die zentralen Anweisungen in SKILL.md fest und verlinke bei Bedarf ergänzende Dateien.
review-pr/
├── SKILL.md
├── references/
│ └── review-guidelines.md
├── scripts/
│ └── check-changes.sh
└── assets/
└── review-template.md
Verwende references/ für Hintergrundmaterial, scripts/ für wiederholbare Aktionen und assets/ für wiederverwendbare Vorlagen.
Einen Skill erstellen
Du kannst ein Verzeichnis als Multipart-Formulardaten hochladen oder eine .zip-Datei mit genau einem Ordner auf der obersten Ebene hochladen.
Option 1: Verzeichnis als Multipart-Formulardaten hochladen
Lade mehrere files[]-Teile hoch. Jeder Teil enthält den Dateipfad innerhalb desselben Ordners auf der obersten Ebene.
curl -X POST 'https://api.openai.com/v1/skills' \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-F 'files[]=@./basic_math/SKILL.md;filename=basic_math/SKILL.md;type=text/markdown' \
-F 'files[]=@./basic_math/calculate.py;filename=basic_math/calculate.py;type=text/plain'Option 2: ZIP-Datei hochladen
Packe den Ordner der obersten Ebene in ein ZIP-Archiv und lade die ZIP-Datei hoch.
curl -X POST 'https://api.openai.com/v1/skills' \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-F 'files=@./basic_math.zip;type=application/zip'Warten, bis eine hochgeladene Version verfügbar ist
Eine Anfrage für eine neu hochgeladene Version kann kurzzeitig 404 zurückgeben, bis die Version verfügbar ist. Rufe die Version mit GET /v1/skills/{skill_id}/versions/{version} ab, bevor du sie in einen Container oder eine Live-Sitzung einbindest. Gibt die Anfrage unmittelbar nach dem erfolgreichen Upload 404 zurück, wiederhole sie nach einer kurzen Wartezeit und lege ein Zeitlimit für die Versuche fest. Sobald der Abruf erfolgreich ist, verwende die zurückgegebene Versionszeichenfolge in der Skill-Referenz.
Skills mit der Hosted Shell verwenden
Um Skills in die Umgebung der Hosted Shell einzubinden, gib sie beim Aufruf des Shell-Tools in tools[].environment.skills an.
curl -L 'https://api.openai.com/v1/responses' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "gpt-6-astra",
"tools": [
{
"type": "shell",
"environment": {
"type": "container_auto",
"skills": [
{ "type": "skill_reference", "skill_id": "<skill_id>" },
{ "type": "skill_reference", "skill_id": "<skill_id>", "version": "2" }
]
}
}
],
"input": "Use the skills to add 144 and 377, then compute triangle area with base 9 height 13."
}'Skill-Auswahl per Prompt steuern
Sobald ein Skill eingebunden ist, kann das Modell entscheiden, wann es ihn einsetzt. Wenn du ein vorhersehbareres Verhalten möchtest, weise das Modell bei Bedarf ausdrücklich an: „Verwende den Skill <skill name>.“
Skills im lokalen Shell-Modus verwenden
Skills funktionieren auch im lokalen Shell-Modus. Die lokale Shell und die Hosted Shell unterstützen unterschiedliche Formate zum Einbinden von Skills.
- Die Hosted Shell unterstützt Anhänge vom Typ
skill_referencefür hochgeladene Skills, einschließlich kuratierter Skills und explizit angegebener Versionen. - Die lokale Shell unterstützt keine Anhänge vom Typ
skill_reference. Stelle die Skill-Dateien stattdessen über lokale Dateipfade in der von dir verwalteten Laufzeitumgebung bereit.
Einzelheiten zur lokalen Ausführung findest du im Leitfaden zum Shell-Tool.
Für das TypeScript-Beispiel benötigst du Node.js ab Version 22.6 und einen laufenden Docker-Daemon. Speichere den Docker-Adapter als support/local-skill-sandbox.mjs und das Beispiel als tools/skills/local-shell.mts, damit der relative Import im Beispiel funktioniert. Setze OPENAI_API_KEY. Installiere dann das SDK, lade das im Adapter festgelegte Image herunter und führe das Beispiel aus. Verwende dafür das Verzeichnis, das support und tools enthält.
npm install openai
docker pull "$(node --input-type=module -e 'import { sandboxImage } from "./support/local-skill-sandbox.mjs"; console.log(sandboxImage)')"
node --experimental-strip-types tools/skills/local-shell.mts
Die Hilfsfunktionen des Adapters übernehmen folgende Aufgaben:
| Hilfsfunktion | Aufgabe in der Anwendung |
|---|---|
withLocalSkillSandbox(name, workflow) |
Erstellt eine isolierte Python-Umgebung mit /workspace/skills/csv-insights/SKILL.md und /workspace/reports.csv, ruft workflow mit einem AbortSignal auf und entfernt die Umgebung, sobald der Workflow endet. |
executeShellCall(name, call, signal) |
Führt die angeforderten Befehle in dieser Umgebung aus und gibt ein shell_call_output mit der ursprünglichen call_id, stdout, stderr und dem Exit-Status oder der Angabe einer Zeitüberschreitung zurück. |
readSkillReport(name, signal) |
Liest die erzeugte Datei /workspace/report.md aus der Umgebung und begrenzt dabei die gelesene Datenmenge. |
Der Adapter muss Zeitlimits für die Ausführung und Größenlimits für die Ausgabe durchsetzen. Im Beispiel werden generierte Befehle ausschließlich in der isolierten Laufzeitumgebung ausgeführt.
curl -L 'https://api.openai.com/v1/responses' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "gpt-6-astra",
"tools": [
{
"type": "shell",
"environment": {
"type": "local",
"skills": [
{
"name": "csv-insights",
"description": "Summarize CSV files and produce a markdown report.",
"path": "<path-to-skill-folder>"
}
]
}
}
],
"input": "Use the csv-insights skill and run locally to summarize today\'s CSV reports in this repo."
}'Agents API
Um Skills mit der Agents API zu verwenden, lege die Skill-Verzeichnisse in der Sandbox ab und registriere beim Erstellen der Sitzung ihre übergeordneten Verzeichnisse in environment.capability_directories. Diese heißen Capability-Verzeichnisse. Der Harness sucht dort nach Skills. Bei diesem Setup kommt das Anhangsformat skill_reference der Hosted Shell nicht zum Einsatz.
Lege beispielsweise einen Skill zum Prüfen von Verträgen und einen weiteren zum Prüfen von Pull Requests in der Sandbox ab:
/workspace/capabilities/
├── legal/
│ └── contract-redline/
│ ├── SKILL.md
│ └── references/
│ └── fallback-clauses.md
└── engineering/
└── review-pr/
├── SKILL.md
└── references/
└── review-guidelines.md
Gib in der Anfrage zum Erstellen der Sitzung diese Umgebungskonfiguration an:
{
"environment": {
"type": "self_hosted",
"workspace_directory": "/workspace",
"capability_directories": [
"/workspace/capabilities/legal",
"/workspace/capabilities/engineering"
]
}
}
Für Capability-Verzeichnisse gelten folgende Anforderungen:
- Die Pfade müssen auf Verzeichnisse innerhalb der Sandbox verweisen.
- Die Pfade müssen absolut und eindeutig sein. Sie dürfen weder
.noch..als Pfadsegment enthalten. - Pro Sitzung kannst du bis zu 32 Capability-Verzeichnisse registrieren.
- Die Verzeichnisse müssen in der Umgebung bereits vorhanden sein.
Sobald die Sandbox verfügbar ist, durchsucht der Harness diese Verzeichnisse nach SKILL.md-Dateien und fügt für jeden gefundenen Skill den Namen und die Beschreibung zum Kontext hinzu. Das Modell kann passende Skills auswählen und ihre vollständigen Anweisungen und ergänzenden Dateien lesen.
Wie du die Sitzung konfigurierst, erfährst du im Leitfaden zur Agentenkonfiguration. Informationen zur Ausführungsumgebung findest du im Leitfaden Eine Sandbox anbinden. Prüfe die Skills und ihre ergänzenden Dateien, bevor du sie dem Agenten zur Verfügung stellst, und beachte die Sicherheitshinweise für Sandboxes.
Skills im Nutzer-Prompt
Bei den Shell-Tools der Responses API fügt die Plattform für jeden verfügbaren Skill name, description und path zum Kontext des Nutzer-Prompts hinzu. So erfährt das Modell, welche Skills verfügbar sind.
Anhand dieser Metadaten entscheidet das Modell, ob es einen Skill aufruft. Ruft es einen Skill auf, verwendet es path, um die vollständigen Markdown-Anweisungen aus SKILL.md zu lesen.
Skill-Anweisungen sind Teil des Nutzer-Prompts und gehören nicht zum System-Prompt. Sie haben deshalb dieselbe Priorität wie andere Anweisungen der Person, die den Prompt eingibt. Du kannst die Auswahl weiterhin ausdrücklich vorgeben: „Verwende den Skill <skill name>.“
Grenzwerte und Validierung
- Bei der Suche nach
SKILL.mdspielt die Groß- und Kleinschreibung keine Rolle. - Ein Skill-Paket muss genau eine Datei namens
skill.md/SKILL.mdenthalten. - Für die Validierung des Frontmatters eines Skills gilt die Spezifikation für Agent Skills.
- Eine ZIP-Datei darf beim Upload maximal
50 MBgroß sein. - Pro Skill-Version sind maximal
500Dateien zulässig. - Eine einzelne Datei darf unkomprimiert maximal
25 MBgroß sein.
Sicherheit bei Netzwerkzugriff
Prüfe jeden Skill, den du mit der Responses API verwendest. Skills bergen Sicherheitsrisiken. Beispielsweise können durch Prompt Injection Daten abfließen. Lies den folgenden Abschnitt Risiken und Sicherheit sorgfältig durch, bevor du dieses Tool verwendest.
Versionierung und Verwaltung
Versionsverweise
default_versiongilt, wenn du keine Version angibst.latest_versionverweist immer auf die zuletzt hochgeladene Version.skill_reference.versionakzeptiert eine Versionsangabe als Zeichenfolge, etwa"2"oder"latest".default_versionerfordert beim Aktualisieren ebenfalls eine Zeichenfolge.
Eine neue Version erstellen
curl -X POST 'https://api.openai.com/v1/skills/<skill_id>/versions' \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-F 'files=@./geometry.zip;type=application/zip'Standardversion festlegen
curl -X POST 'https://api.openai.com/v1/skills/<skill_id>' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{"default_version": "2"}'Regeln für das Löschen
- Die aktuelle Standardversion lässt sich nicht löschen. Lege zuerst eine andere Version als Standard fest.
- Wenn du die letzte verbleibende Version löschst, wird auch der Skill gelöscht.
- Wenn du einen Skill löschst, werden alle seine Versionen gelöscht.
Kuratierte Skills
OpenAI pflegt eine Reihe eigener Skills, auf die du über ihre ID verweisen kannst (zum Beispiel openai-spreadsheets).
{ "type": "skill_reference", "skill_id": "openai-spreadsheets", "version": "latest" }Skills direkt einbetten
Wenn du keinen gehosteten Skill erstellen möchtest, kannst du ein Base64-kodiertes ZIP-Paket direkt in das Array skills der Umgebung einbetten.
INLINE_ZIP=$(base64 -i ./basic_math.zip)
curl -L 'https://api.openai.com/v1/containers' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"name": "inline-skill-container",
"skills": [
{
"type": "inline",
"name": "basic_math",
"description": "Add or multiply numbers.",
"source": {
"type": "base64",
"media_type": "application/zip",
"data": "'"$INLINE_ZIP"'"
}
}
]
}'Risiken und Sicherheit
Prüfe jeden Skill, den du mit der Responses API verwendest. Skills bergen Sicherheitsrisiken. Beispielsweise können durch Prompt Injection Daten abfließen.
Wenn du Skills mit Netzwerkzugriff verwendest, lies den Abschnitt zu Risiken und Sicherheit beim Netzwerkzugriff sorgfältig durch.
Skills als privilegierten Code und privilegierte Anweisungen behandeln
Der Inhalt eines Skills kann beeinflussen, wie der Agent plant, Tools einsetzt und Befehle ausführt. Behandle jeden Skill bei der Prüfung als potenziell nicht vertrauenswürdige Eingabe, bis du ihn bei der Entwicklung validiert hast.
Endnutzenden keinen Zugriff auf ein offenes Skill-Repository geben
Gestalte dein Produkt so, dass Personen, die es nutzen, nicht frei in einem offenen Katalog stöbern und daraus beliebige Skills auswählen oder einbinden können. Ein solcher Zugriff erhöht insbesondere die folgenden Risiken erheblich:
- Prompt Injection und Umgehung von Richtlinien durch bösartige Anweisungen in SKILL.md.
- Datenabfluss oder destruktive Aktionen durch ungeprüfte Automatisierungen.
Skills bei der Entwicklung integrieren
Prüfe und integriere die Skills bei der Entwicklung. Stelle sie anschließend nur über klar abgegrenzte Produktfunktionen bereit. Das bedeutet konkret:
- Ordne Skills bestimmten Workflows oder Anwendungsfällen im Produkt zu.
- Verhindere, dass Endnutzende beliebige Skills auswählen können.
- Lass Schreibzugriffe oder Aktionen mit weitreichenden Auswirkungen nur nach ausdrücklicher Genehmigung und Prüfung auf Einhaltung der geltenden Richtlinien zu.
Genehmigung für sensible Aktionen verlangen
Wenn ein Workflow Schreibzugriffe oder Aktionen mit weitreichenden Auswirkungen ausführen kann, verlange vor der Ausführung eine ausdrückliche Genehmigung.
Anforderungen an Datenresidenz und Datenaufbewahrung prüfen
Die Responses API unterstützt zwei Ausführungsmodi für Skills. Du kannst sie lokal oder in einem gehosteten Container ausführen. Für gehostete Skills gilt derselbe Container-Lebenszyklus wie für die Hosted Shell. Eingebundene Skills und Dateien im Container bleiben verfügbar, solange der Container aktiv ist. Sobald der Container abläuft oder gelöscht wird, werden sie verworfen. Wenn die Ausführung vollständig auf der von dir verwalteten Infrastruktur stattfinden soll, verwende den lokalen Shell-Modus. Informationen zu Sandboxes der Agents API findest du im Abschnitt Lebenszyklus einer Sandbox. Erfahre mehr über unsere Optionen zur Datenkontrolle.