Skills

Les Agent Skills fournissent à un agent des instructions réutilisables et des fichiers complémentaires pour une tâche. Utilisez-les avec les outils shell de l’API Responses ou mettez-les à disposition dans un bac à sable de l’API Agents.

Les instructions de téléversement, de rattachement et de gestion des versions ci-dessous concernent les outils shell de l’API Responses. Les sessions de l’API Agents découvrent les skills dans les répertoires de leur bac à sable.

Qu’est-ce qu’une skill ?

Une skill est un répertoire de fichiers contenant un manifeste SKILL.md (métadonnées d’en-tête et instructions). Les skills sont des instructions modulaires qui permettent de formaliser des processus et des conventions, des guides de style d’entreprise aux workflows en plusieurs étapes. Les skills téléversées utilisent des paquets versionnés.

Les skills sont compatibles avec le standard ouvert Agent Skills.

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.

Lors de la découverte des skills, le modèle voit le nom et la description de chacune. Rédigez une description qui explique à la fois ce que fait la skill et quand l’utiliser. Par exemple, « Révisez les contrats fournisseurs avec le suivi des modifications en utilisant les clauses de substitution » donne au modèle un contexte plus utile que « Aide aux tâches juridiques ».

Conservez les instructions principales dans SKILL.md et ajoutez des liens vers les fichiers complémentaires au besoin :

review-pr/
├── SKILL.md
├── references/
│   └── review-guidelines.md
├── scripts/
│   └── check-changes.sh
└── assets/
    └── review-template.md

Utilisez references/ pour la documentation de référence, scripts/ pour les actions répétables et assets/ pour les modèles réutilisables.

Créez une skill

Vous pouvez importer un répertoire sous forme de données de formulaire multipart ou un fichier .zip contenant un seul dossier de premier niveau.

Option 1 : importation d’un répertoire (multipart)

Importez plusieurs parties files[]. Chaque partie inclut le chemin à l’intérieur d’un même dossier de premier niveau.

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 : importation d’un fichier zip

Compressez le dossier de premier niveau au format zip, puis importez le fichier zip.

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'

Utilisez des skills avec le shell distant

Pour monter des skills dans un environnement shell distant, associez-les via tools[].environment.skills lors de l’appel à l’outil shell.

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)

Influence du prompt sur le comportement

Une fois une skill montée, le modèle peut décider quand l’utiliser. Si vous souhaitez un comportement plus déterministe, demandez explicitement au modèle d’« utiliser la skill <skill name> » lorsque c’est pertinent.

Utilisez des skills en mode shell local

Les skills fonctionnent également en mode shell local, mais le shell local et le shell distant n’acceptent pas les mêmes formats pour associer des skills.

• Le shell distant prend en charge l’association de skills importées via skill_reference, y compris des skills sélectionnées et des versions explicitement spécifiées.
• Le shell local ne prend pas en charge l’association de skills via skill_reference. Fournissez plutôt les fichiers des skills à partir de chemins de fichiers locaux dans l’environnement d’exécution que vous contrôlez.

Consultez le guide Shell pour en savoir plus sur l’exécution en shell local.

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)

API Agents

Pour utiliser des skills dans l’API Agents, placez leurs répertoires dans le bac à sable et enregistrez leurs répertoires parents dans environment.capability_directories lors de la création de la session. Ces derniers sont appelés répertoires de capacités. Le harnais les utilise pour découvrir les skills ; cette configuration n’utilise pas le format de rattachement skill_reference du shell distant.

Par exemple, placez dans le bac à sable une skill de révision de contrats et une skill de revue de pull requests :

/workspace/capabilities/
├── legal/
│   └── contract-redline/
│       ├── SKILL.md
│       └── references/
│           └── fallback-clauses.md
└── engineering/
    └── review-pr/
        ├── SKILL.md
        └── references/
            └── review-guidelines.md

Utilisez cette configuration d’environnement dans la requête de création de session :

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

Les répertoires de capacités doivent respecter les exigences suivantes :

• Les chemins doivent pointer vers des répertoires situés dans le bac à sable.
• Les chemins doivent être absolus et uniques, et ne peuvent pas contenir de segments . ou ...
• Une session peut enregistrer jusqu’à 32 répertoires de capacités.
• Les répertoires doivent déjà exister dans l’environnement.

Une fois le bac à sable disponible, le harnais recherche les fichiers SKILL.md dans ces répertoires et ajoute au contexte le nom et la description de chaque skill découverte. Le modèle peut sélectionner les skills pertinentes et lire l’intégralité de leurs instructions ainsi que leurs fichiers complémentaires.

Consultez Configuration des agents pour configurer la session et Connectez un bac à sable pour l’environnement d’exécution. Examinez les skills et leurs fichiers complémentaires avant de les mettre à disposition de l’agent, et suivez les consignes de sécurité du bac à sable.

Les skills dans le prompt utilisateur

Pour les outils shell de l’API Responses, la plateforme ajoute les champs name, description et path de chaque skill disponible au contexte du prompt utilisateur afin que le modèle sache que cette skill existe.

Le modèle décide d’invoquer ou non une skill à partir de ces métadonnées. S’il invoque une skill, il utilise path pour lire l’intégralité des instructions Markdown contenues dans SKILL.md.

Les instructions des skills font partie du prompt utilisateur (et non du prompt système). Elles sont donc traitées avec la même priorité que les autres instructions fournies par l’utilisateur. Pour garder un contrôle explicite, vous pouvez toujours demander au modèle d’« utiliser la skill <skill name> ».

Limites et validation

• La détection du fichier SKILL.md est insensible à la casse.
• Un ensemble de fichiers de skill doit contenir exactement un fichier skill.md/SKILL.md.
• La validation de l’en-tête de métadonnées d’une skill suit la spécification Agent Skills.
• La taille maximale d’un fichier zip à importer est de 50 MB.
• Le nombre maximal de fichiers par version de skill est de 500.
• La taille maximale d’un fichier non compressé est de 25 MB.

Sécurité avec l’accès réseau

Gestion des skills et de leurs versions

Pointeurs de version

• default_version est utilisé lorsqu’aucune version n’est fournie.
• latest_version pointe vers la version importée la plus récente.
• skill_reference.version accepte un entier ou "latest".

Créez une nouvelle version

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'

Définissez la version par défaut

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}'

Règles de suppression

• Vous ne pouvez pas supprimer la version par défaut ; définissez d’abord une autre version par défaut.
• La suppression de la dernière version restante supprime le skill.
• La suppression d’un skill entraîne celle de toutes ses versions.

Skills sélectionnés

OpenAI maintient un ensemble de skills développés en interne que vous pouvez référencer par leur identifiant (par exemple, openai-spreadsheets).

{ "type": "skill_reference", "skill_id": "openai-spreadsheets", "version": "latest" }

Skills intégrés directement

Si vous ne souhaitez pas créer de skill hébergé, vous pouvez intégrer directement une archive zip (base64) dans le tableau skills de l’environnement.

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"'"
        }
      }
    ]
  }'

Risques et sécurité

Il est important d’examiner tout Skill utilisé avec l’API Responses. Les Skills présentent des risques de sécurité, tels que l’exfiltration de données provoquée par une attaque par injection de prompt.

Pour les Skills utilisés avec un accès réseau, consultez attentivement la section Risques et sécurité consacrée à l’accès réseau.

Traitez les Skills comme du code et des instructions disposant de privilèges

Le contenu d’un Skill peut influencer la planification, l’utilisation des outils et l’exécution des commandes. Tout Skill doit être examiné comme une entrée potentiellement non fiable tant que le développeur ne l’a pas validé.

Ne donnez pas aux utilisateurs finaux accès à un dépôt ouvert de Skills

Évitez de concevoir des produits qui permettent aux utilisateurs finaux de parcourir librement un catalogue ouvert et de sélectionner ou de joindre n’importe quel Skill. Cela augmente considérablement les risques suivants :

• Attaques par injection de prompt et contournement des règles au moyen d’instructions malveillantes dans SKILL.md.
• Exfiltration de données ou actions destructrices déclenchées par une automatisation non vérifiée.

Intégrez les Skills au niveau du développement

Les Skills doivent être examinés et intégrés par le développeur, puis mis à la disposition des utilisateurs finaux uniquement dans le cadre de fonctionnalités bien délimitées du produit. En pratique :

• Associez les Skills à des workflows ou à des cas d’utilisation précis du produit.
• Empêchez les utilisateurs finaux de sélectionner librement n’importe quel Skill.
• Soumettez les actions d’écriture ou à fort impact à une approbation explicite et à des contrôles de conformité aux règles.

Exigez une approbation pour les actions sensibles

Pour les workflows susceptibles d’effectuer des actions d’écriture ou à fort impact, exigez une approbation explicite avant leur exécution.

Vérifiez les exigences de résidence et de conservation des données

L’API Responses prend en charge les skills selon deux modes : l’exécution locale et l’exécution hébergée dans des conteneurs. Les skills hébergées suivent le même cycle de vie du conteneur que le shell distant : les skills montées et les fichiers du conteneur restent disponibles tant que le conteneur est actif et sont supprimés lorsque celui-ci expire ou est supprimé. Si vous souhaitez que l’exécution reste entièrement sur une infrastructure que vous gérez, utilisez le mode shell local. Pour les bacs à sable de l’API Agents, consultez Cycle de vie du bac à sable. Découvrez nos contrôles des données.