Habilidades

Las habilidades para agentes proporcionan a un agente instrucciones reutilizables y archivos de apoyo para una tarea. Úsalas con las herramientas de shell de la API Responses o ponlas a disposición en un sandbox de la API de agentes.

Las instrucciones de carga, asociación y control de versiones que se presentan a continuación describen las herramientas de shell de la API Responses. Las sesiones de la API de agentes descubren habilidades en los directorios de su sandbox.

Qué es una habilidad

Una habilidad es un directorio de archivos con un archivo de manifiesto SKILL.md (metadatos de encabezado + instrucciones). Las habilidades son instrucciones modulares que puedes usar para definir procesos y convenciones, desde guías de estilo de la empresa hasta flujos de trabajo de varios pasos. Las habilidades cargadas usan paquetes con control de versiones.

Las habilidades son compatibles con el estándar abierto 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.

Durante el descubrimiento de habilidades, el modelo ve el nombre y la descripción de cada habilidad. Escribe una descripción que explique tanto lo que hace la habilidad como cuándo usarla. Por ejemplo, “Revisa los acuerdos con proveedores y marca los cambios usando las cláusulas alternativas” le da al modelo un contexto más útil que “Ayuda con el trabajo legal”.

Mantén las instrucciones principales en SKILL.md y agrega enlaces a los archivos de apoyo según sea necesario:

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

Usa references/ para material de referencia, scripts/ para acciones repetibles y assets/ para plantillas reutilizables.

Crear una habilidad

Puedes cargar un directorio como datos de formulario multiparte o cargar un archivo .zip que contenga una sola carpeta de nivel superior.

Opción 1: carga de un directorio (multiparte)

Carga varias partes files[]. Cada parte incluye la ruta dentro de una única carpeta de nivel superior.

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'

Opción 2: carga de un archivo zip

Comprime la carpeta de nivel superior en formato zip y carga el archivo 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'

Usar habilidades con la terminal alojada en la nube

Para montar habilidades en un entorno de terminal alojada en la nube, adjúntalas mediante tools[].environment.skills al llamar a la herramienta 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)

Comportamiento según el diseño de prompts

Una vez montada una habilidad, el modelo puede decidir cuándo usarla. Si quieres un comportamiento más determinista, indica explícitamente al modelo que “use la habilidad <skill name>” cuando corresponda.

Usar habilidades con el modo de shell local

Las habilidades también funcionan con el modo de shell local, pero el shell local y la terminal alojada en la nube no aceptan los mismos formatos para adjuntar habilidades.

• La terminal alojada en la nube admite adjuntos skill_reference cargados, incluidas habilidades seleccionadas y versiones explícitas.
• El shell local no admite adjuntos skill_reference. En su lugar, proporciona los archivos de las habilidades desde rutas de archivos locales en el entorno de ejecución que controlas.

Consulta la guía de Shell para obtener detalles sobre la ejecución en el 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 de agentes

Para usar habilidades en la API de agentes, coloca los directorios de las habilidades en el sandbox y registra sus directorios padre en environment.capability_directories al crear la sesión. Estos se denominan directorios de capacidades. El arnés de ejecución los usa para descubrir habilidades; esta configuración no usa el formato de asociación skill_reference de la terminal alojada en la nube.

Por ejemplo, coloca en el sandbox una habilidad de revisión de contratos y una habilidad de revisión de Pull Requests:

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

Usa esta configuración del entorno en la solicitud de creación de la sesión:

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

Los directorios de capacidades deben cumplir estos requisitos:

• Las rutas deben apuntar a directorios dentro del sandbox.
• Las rutas deben ser absolutas y únicas, y no pueden contener los segmentos de ruta . o ...
• Una sesión puede registrar hasta 32 directorios de capacidades.
• Los directorios ya deben existir en el entorno.

Una vez que el sandbox está disponible, el arnés de ejecución busca archivos SKILL.md en estos directorios y agrega al contexto el nombre y la descripción de cada habilidad descubierta. El modelo puede seleccionar las habilidades pertinentes y leer sus instrucciones completas y archivos de apoyo.

Consulta Configuración de agentes para configurar la sesión y Conectar un sandbox para obtener información sobre el entorno de ejecución. Revisa las habilidades y sus archivos de apoyo antes de ponerlos a disposición del agente y sigue las recomendaciones de seguridad del sandbox.

Habilidades en el prompt del usuario

Para las herramientas de shell de la API Responses, la plataforma agrega name, description y path de cada habilidad disponible al contexto del prompt del usuario para que el modelo sepa que la habilidad existe.

El modelo decide si invoca una habilidad a partir de estos metadatos. Si invoca una habilidad, usa path para leer las instrucciones completas en Markdown de SKILL.md.

Las instrucciones de las habilidades forman parte del prompt del usuario (no del prompt del sistema), por lo que se procesan con la misma prioridad que las demás instrucciones proporcionadas por el usuario. Para tener un control explícito, también puedes indicar al modelo que “use la habilidad <skill name>”.

Límites y validación

• La búsqueda de coincidencias con el nombre de archivo SKILL.md no distingue entre mayúsculas y minúsculas.
• Solo se permite un archivo skill.md/SKILL.md en un paquete de habilidad.
• La validación de los metadatos de encabezado de las habilidades sigue la especificación de Agent Skills.
• El tamaño máximo de un archivo zip para cargar es de 50 MB.
• La cantidad máxima de archivos por versión de una habilidad es de 500.
• El tamaño máximo de un archivo sin comprimir es de 25 MB.

Seguridad con acceso a la red

Versionado y administración

Punteros de versión

• Se usa default_version cuando no se proporciona una versión.
• latest_version apunta a la carga más reciente.
• skill_reference.version acepta un número entero o "latest".

Crear una nueva versión

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'

Establecer la versión predeterminada

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

Reglas de eliminación

• No puedes eliminar la versión predeterminada; primero establece otra como predeterminada.
• Al eliminar la última versión restante, se elimina la habilidad.
• Al eliminar una habilidad, se eliminan en cascada todas sus versiones.

Habilidades seleccionadas

OpenAI mantiene un conjunto de habilidades propias a las que puedes hacer referencia por su identificador (por ejemplo, openai-spreadsheets).

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

Habilidades incluidas directamente

Si no quieres crear una habilidad alojada, puedes incluir directamente un paquete zip (base64) en el arreglo skills del entorno.

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

Riesgos y seguridad

Es importante inspeccionar cualquier habilidad que se use con la API Responses. Las habilidades introducen riesgos de seguridad, como la exfiltración de datos mediante inyección de prompts.

Para las habilidades que se usan junto con acceso a la red, revisa con atención la sección de riesgos y seguridad del acceso a la red.

Trata las habilidades como código e instrucciones con privilegios

El contenido de una habilidad puede influir en la planificación, el uso de herramientas y la ejecución de comandos. Toda habilidad debe revisarse como una entrada potencialmente no confiable hasta que el desarrollador la valide.

No expongas un repositorio abierto de habilidades a los usuarios finales

Evita diseños de producto que permitan a los usuarios finales explorar, seleccionar o adjuntar libremente cualquier habilidad de un catálogo abierto. Esto aumenta considerablemente el riesgo de:

• Inyección de prompts y elusión de políticas mediante instrucciones maliciosas en SKILL.md.
• Exfiltración de datos o acciones destructivas desencadenadas por automatizaciones no revisadas.

Integra las habilidades desde el desarrollo

El desarrollador debe inspeccionar e integrar las habilidades y, después, ponerlas a disposición de los usuarios finales únicamente mediante experiencias de producto con límites definidos. En la práctica:

• Asocia las habilidades con flujos de trabajo o casos de uso específicos del producto.
• Impide que los usuarios finales seleccionen habilidades de forma arbitraria.
• Exige aprobación explícita y verificaciones de políticas antes de permitir acciones de escritura o de alto impacto.

Exige aprobación para las acciones sensibles

Para los flujos de trabajo que pueden realizar acciones de escritura o de alto impacto, exige aprobación explícita antes de la ejecución.

Valida los requisitos de residencia y retención de datos

La API Responses admite habilidades en dos modalidades: ejecución local y ejecución alojada basada en contenedores. Las habilidades alojadas siguen el mismo ciclo de vida del contenedor que la terminal alojada en la nube: las habilidades montadas y los archivos del contenedor permanecen disponibles mientras el contenedor está activo y se descartan cuando el contenedor caduca o se elimina. Si quieres que la ejecución se mantenga por completo en la infraestructura que administras, usa el modo de shell local. Para los sandboxes de la API de agentes, consulta Ciclo de vida del sandbox. Obtén más información sobre nuestros controles de datos.