Skills

Agent Skills stellen einem Agenten wiederverwendbare Anweisungen und ergänzende Dateien für eine Aufgabe bereit. Nutze sie mit Shell-Werkzeugen der Responses API oder stelle sie in einer Sandbox der Agents API bereit.

Die folgenden Anleitungen zum Hochladen, Einbinden und Versionieren beziehen sich auf Shell-Werkzeuge der Responses API. Sitzungen der Agents API finden Skills in Verzeichnissen ihrer Sandbox.

Was ist ein Skill?

Ein Skill ist ein Verzeichnis mit Dateien und einem SKILL.md-Manifest (Frontmatter + Anweisungen). Skills sind modulare Anweisungen, mit denen du Prozesse und Konventionen festhalten kannst, von unternehmensweiten Stilrichtlinien bis hin zu mehrstufigen Arbeitsabläufen. Hochgeladene Skills verwenden versionierte Pakete.

Skills sind mit dem offenen Agent Skills-Standard kompatibel.

1
2
3
4
5
6---
name: basic-math
description: Add or multiply numbers.
---

Use this skill when you need a quick sum or product of numbers.

Beim Erkennen von Skills sieht das Modell den Namen und die Beschreibung des jeweiligen Skills. Erkläre in der Beschreibung sowohl, was der Skill tut, als auch, wann er eingesetzt werden sollte. Zum Beispiel bietet „Prüfe Lieferantenverträge und überarbeite sie anhand der Ersatzklauseln mit Änderungsmarkierungen“ dem Modell nützlicheren Kontext als „Hilft bei juristischen Aufgaben“.

Halte die zentralen Anweisungen in SKILL.md fest und verlinke bei Bedarf auf 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, die genau einen Ordner auf oberster Ebene enthält.

Option 1: Verzeichnis hochladen (Multipart)

Lade mehrere files[]-Teile hoch. Jeder Teil enthält den Pfad innerhalb eines gemeinsamen Ordners auf oberster Ebene.

1
2
3
4curl -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 auf oberster Ebene in eine ZIP-Datei und lade sie hoch.

1
2
3curl -X POST 'https://api.openai.com/v1/skills' \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F 'files=@./basic_math.zip;type=application/zip'

Skills mit Hosted Shell verwenden

Um Skills in eine Hosted Shell-Umgebung einzubinden, füge sie beim Aufruf des Shell-Tools über tools[].environment.skills hinzu.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19curl -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."
  }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.create({
  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.",
});

console.log(response.output_text);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22response = client.responses.create(
    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.",
)

print(response.output_text)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	client := openai.NewClient()
	tool := responses.ToolUnionParam{OfShell: &responses.FunctionShellToolParam{
		Environment: responses.FunctionShellToolEnvironmentUnionParam{OfContainerAuto: &responses.ContainerAutoParam{
			Skills: []responses.ContainerAutoSkillUnionParam{
				{OfSkillReference: &responses.SkillReferenceParam{SkillID: "<skill_id>"}},
				{OfSkillReference: &responses.SkillReferenceParam{SkillID: "<skill_id>", Version: openai.String("2")}},
			},
		}},
	}}
	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: "gpt-6-astra",
		Tools: []responses.ToolUnionParam{tool},
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("Use the skills to add 144 and 377, then compute triangle area with base 9 height 13.")},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(response.OutputText())
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.responses.ResponseCreateParams;
import java.util.List;
import java.util.Map;

String skillId = "<skill_id>";

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .input(
            "Use the skills to add 144 and 377, then compute a triangle area with base 9 and height 13.")
        .putAdditionalBodyProperty(
            "tools",
            JsonValue.from(
                List.of(
                    Map.of(
                        "type",
                        "shell",
                        "environment",
                        Map.of(
                            "type",
                            "container_auto",
                            "skills",
                            List.of(
                                Map.of("type", "skill_reference", "skill_id", skillId),
                                Map.of(
                                    "type", "skill_reference",
                                    "skill_id", skillId,
                                    "version", "2")))))))
        .build();

client.responses().create(params).output().stream()
    .flatMap(item -> item.message().stream())
    .flatMap(message -> message.content().stream())
    .flatMap(content -> content.outputText().stream())
    .forEach(text -> System.out.println(text.text()));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28require "openai"

client = OpenAI::Client.new
response = client.responses.create(
  model: "gpt-6-astra",
  input: "Use the skills to add 144 and 377, then compute a triangle area with base 9 and height 13.",
  tools: [
    {
      type: :shell,
      environment: {
        type: :container_auto,
        skills: [
          {
            type: :skill_reference,
            skill_id: "<skill_id>"
          },
          {
            type: :skill_reference,
            skill_id: "<skill_id>",
            version: "2"
          }
        ]
      }
    }
  ]
)

puts(response.output_text)

Verhalten durch Prompts steuern

Sobald ein Skill eingebunden ist, kann das Modell entscheiden, wann es ihn verwendet. Wenn du ein deterministischeres 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 Hosted Shell akzeptieren jedoch unterschiedliche Formate zum Einbinden von Skills.

• Hosted Shell unterstützt hochgeladene Anhänge vom Typ skill_reference, einschließlich kuratierter Skills und explizit angegebener Versionen.
• Die lokale Shell unterstützt keine Anhänge vom Typ skill_reference. Stelle stattdessen Skill-Dateien über lokale Dateipfade in der von dir kontrollierten Laufzeitumgebung bereit.

Details zur lokalen Shell-Ausführung findest du im Shell-Leitfaden.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22curl -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."
  }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.create({
  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.",
});

console.log(response.output_text);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21response = client.responses.create(
    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.",
)

print(response.output_text)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	client := openai.NewClient()
	tool := responses.ToolUnionParam{OfShell: &responses.FunctionShellToolParam{
		Environment: responses.FunctionShellToolEnvironmentUnionParam{OfLocal: &responses.LocalEnvironmentParam{
			Skills: []responses.LocalSkillParam{{
				Name:        "csv-insights",
				Description: "Summarize CSV files and produce a markdown report.",
				Path:        "<path-to-skill-folder>",
			}},
		}},
	}}
	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: "gpt-6-astra",
		Tools: []responses.ToolUnionParam{tool},
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("Use the csv-insights skill and run locally to summarize today's CSV reports in this repo.")},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(response.OutputText())
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.responses.ResponseCreateParams;
import java.util.List;
import java.util.Map;

String skillPath = "<path-to-skill-folder>";

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .input("Use the csv-insights skill to summarize today's CSV reports.")
        .putAdditionalBodyProperty(
            "tools",
            JsonValue.from(
                List.of(
                    Map.of(
                        "type",
                        "shell",
                        "environment",
                        Map.of(
                            "type",
                            "local",
                            "skills",
                            List.of(
                                Map.of(
                                    "name", "csv-insights",
                                    "description",
                                        "Summarize CSV files and produce a Markdown report.",
                                    "path", skillPath)))))))
        .build();

client.responses().create(params).output().stream()
    .flatMap(item -> item.message().stream())
    .flatMap(message -> message.content().stream())
    .flatMap(content -> content.outputText().stream())
    .forEach(text -> System.out.println(text.text()));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24require "openai"

client = OpenAI::Client.new
response = client.responses.create(
  model: "gpt-6-astra",
  input: "Use the csv-insights skill to summarize today's CSV reports.",
  tools: [
    {
      type: :shell,
      environment: {
        type: :local,
        skills: [
          {
            name: "csv-insights",
            description: "Summarize CSV files and produce a Markdown report.",
            path: "<path-to-skill-folder>"
          }
        ]
      }
    }
  ]
)

puts(response.output_text)

Agents API

Um Skills in der Agents API zu verwenden, lege die Skill-Verzeichnisse in der Sandbox ab und registriere ihre übergeordneten Verzeichnisse beim Erstellen der Sitzung in environment.capability_directories. Diese werden als Funktionsverzeichnisse bezeichnet. Der Harness nutzt sie, um Skills zu finden. Dieses Setup verwendet nicht das Format skill_reference der Hosted Shell zum Einbinden von Skills.

Lege beispielsweise einen Skill zur Vertragsprüfung und einen Skill zur Überprüfung 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

Verwende diese Umgebungskonfiguration in der Anfrage zum Erstellen der Sitzung:

12345678910{
  "environment": {
    "type": "self_hosted",
    "workspace_directory": "/workspace",
    "capability_directories": [
      "/workspace/capabilities/legal",
      "/workspace/capabilities/engineering"
    ]
  }
}

Für Funktionsverzeichnisse gelten folgende Anforderungen:

• Pfade müssen auf Verzeichnisse innerhalb der Sandbox verweisen.
• Pfade müssen absolut und eindeutig sein und dürfen keine Pfadsegmente mit . oder .. enthalten.
• Pro Sitzung können bis zu 32 Funktionsverzeichnisse registriert werden.
• Verzeichnisse müssen bereits in der Umgebung vorhanden sein.

Sobald die Sandbox verfügbar ist, durchsucht der Harness diese Verzeichnisse nach SKILL.md-Dateien und fügt den Namen und die Beschreibung jedes gefundenen Skills dem Kontext hinzu. Das Modell kann relevante Skills auswählen und ihre vollständigen Anweisungen sowie die ergänzenden Dateien lesen.

Informationen zum Setup von Sitzungen findest du unter Agentenkonfiguration, zur Ausführungsumgebung unter Eine Sandbox verbinden. Prüfe die Skills und ihre ergänzenden Dateien, bevor du sie dem Agenten bereitstellst, und befolge die Hinweise zur Sandbox-Sicherheit.

Skills im Nutzer-Prompt

Bei Shell-Werkzeugen der Responses API fügt die Plattform für jeden verfügbaren Skill name, description und path zum Kontext des Nutzer-Prompts hinzu, damit das Modell weiß, dass der Skill existiert.

Anhand dieser Metadaten entscheidet das Modell, ob es einen Skill aufruft. Wenn es einen Skill aufruft, liest es über path die vollständigen Markdown-Anweisungen aus SKILL.md.

Skill-Anweisungen sind Teil des Nutzer-Prompts, nicht des System-Prompts. Sie werden daher mit derselben Priorität behandelt wie andere Anweisungen von Nutzenden. Für eine gezielte Steuerung kannst du das Modell weiterhin ausdrücklich anweisen: „Verwende den Skill <skill name>.“

Grenzen und Validierung

• Bei der Erkennung der Datei SKILL.md wird nicht zwischen Groß- und Kleinschreibung unterschieden.
• In einem Skill-Paket ist genau eine Datei namens skill.md/SKILL.md zulässig.
• Die Validierung der Frontmatter eines Skills folgt der Agent Skills-Spezifikation.
• Die maximale Größe einer ZIP-Datei beim Hochladen beträgt 50 MB.
• Pro Skill-Version sind maximal 500 Dateien zulässig.
• Die maximale unkomprimierte Dateigröße beträgt 25 MB.

Sicherheit bei Netzwerkzugriff

Versionierung und Verwaltung

Versionszeiger

• default_version wird verwendet, wenn keine Version angegeben ist.
• latest_version verweist auf die zuletzt hochgeladene Version.
• skill_reference.version akzeptiert eine Ganzzahl oder "latest".

Eine neue Version erstellen

1
2
3curl -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

1
2
3
4curl -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 zum Löschen

• Du kannst die Standardversion 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 auch alle zugehörigen 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" }

Inline-Skills

Wenn du keinen gehosteten Skill erstellen möchtest, kannst du ein ZIP-Paket (Base64) direkt in das skills-Array der Umgebung einbetten.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20INLINE_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

Es ist wichtig, jeden Skill zu prüfen, der mit der Responses API verwendet wird. Skills bringen Sicherheitsrisiken mit sich, etwa Datenexfiltration durch Prompt Injection.

Wenn du Skills mit Netzwerkzugriff verwendest, lies den Abschnitt zu Risiken und Sicherheit beim Netzwerkzugriff sorgfältig durch.

Behandle Skills als Code und Anweisungen mit erweiterten Berechtigungen

Der Inhalt eines Skills kann die Planung, die Nutzung von Tools und die Ausführung von Befehlen beeinflussen. Jeder Skill sollte als potenziell nicht vertrauenswürdige Eingabe geprüft werden, bis die für die Entwicklung zuständige Person ihn validiert hat.

Gib Endnutzenden keinen Zugriff auf ein offenes Skills-Repository

Vermeide Produktdesigns, bei denen Endnutzende beliebige Skills aus einem offenen Katalog frei durchsuchen, auswählen oder hinzufügen können. Das erhöht die folgenden Risiken erheblich:

• Prompt Injection und die Umgehung von Richtlinien durch bösartige Anweisungen in SKILL.md.
• Datenexfiltration oder destruktive Aktionen, die durch ungeprüfte Automatisierung ausgelöst werden.

Integriere Skills im Rahmen der Entwicklung

Skills sollten von den zuständigen Entwickelnden geprüft und integriert werden. Endnutzenden sollten sie anschließend nur über klar begrenzte Produktfunktionen zur Verfügung stehen. In der Praxis heißt das:

• Ordne Skills bestimmten Arbeitsabläufen oder Anwendungsfällen im Produkt zu.
• Verhindere, dass Endnutzende beliebige Skills selbst auswählen können.
• Mache Aktionen mit Schreibzugriff oder weitreichenden Auswirkungen von einer ausdrücklichen Genehmigung und der Prüfung auf Richtlinienkonformität abhängig.

Verlange eine Genehmigung für sensible Aktionen

Verlange bei Arbeitsabläufen, die Aktionen mit Schreibzugriff oder weitreichenden Auswirkungen ausführen können, vor der Ausführung eine ausdrückliche Genehmigung.

Prüfe die Anforderungen an Datenresidenz und Datenaufbewahrung

Die Responses API unterstützt Skills in zwei Ausführungsformen: lokal und gehostet in Containern. Gehostete Skills folgen demselben Container-Lebenszyklus wie die Hosted Shell: Eingebundene Skills und Container-Dateien bleiben verfügbar, solange der Container aktiv ist, und werden verworfen, wenn er abläuft oder gelöscht wird. Wenn die Ausführung vollständig auf der von dir verwalteten Infrastruktur bleiben soll, verwende den lokalen Shell-Modus. Informationen zu Sandboxes der Agents API findest du unter Sandbox-Lebenszyklus. Erfahre mehr über unsere Datenkontrollen.