Skills

Agent Skills let you upload and reuse versioned bundles of files in hosted and local shell environments.

What’s a skill

A skill is a versioned bundle of files plus a SKILL.md manifest (front matter + instructions). Skills are modular instructions you can use to codify processes and conventions, from company style guides to multi-step workflows.

Skills are compatible with the open Agent Skills standard.

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.

Create a skill

You can upload a directory as multipart form data or upload a .zip that contains a single top-level folder.

Option 1: Directory upload (multipart)

Upload multiple files[] parts. Each part includes the path inside a single top-level folder.

1
2
3
4
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 upload

Zip the top-level folder and upload the zip file.

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

Use skills with hosted shell

To mount skills in a hosted shell environment, attach them via tools[].environment.skills when calling the shell tool.

curl -L 'https://api.openai.com/v1/responses' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-5.2",
    "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."
  }'

import OpenAI from "openai";

const client = new OpenAI();

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

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.2",
    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)

Prompting behavior

Once a skill is mounted, the model can decide when to use it. If you want more deterministic behavior, explicitly instruct the model to “use the <skill name> skill” when appropriate.

Use skills with local shell mode

Skills also work with local shell mode. The skill selection and prompt behavior are the same as hosted shell mode, but command execution and filesystem access are still handled by your local runtime.

Use the Shell guide for local shell execution details.

curl -L 'https://api.openai.com/v1/responses' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-5.2",
    "tools": [
      {
        "type": "shell",
        "environment": {
          "type": "local",
          "skills": [
            { "type": "skill_reference", "skill_id": "<skill_id>" },
            { "type": "skill_reference", "skill_id": "<skill_id>", "version": 2 }
          ]
        }
      }
    ],
    "input": "Use the configured skills and run locally to summarize today\'s CSV reports in this repo."
  }'

import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-5.2",
  tools: [
    {
      type: "shell",
      environment: {
        type: "local",
        skills: [
          { type: "skill_reference", skill_id: "<skill_id>" },
          { type: "skill_reference", skill_id: "<skill_id>", version: 2 },
        ],
      },
    },
  ],
  input: "Use the configured skills and run locally to summarize today's CSV reports in this repo.",
});

console.log(response.output_text);

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.2",
    tools=[
        {
            "type": "shell",
            "environment": {
                "type": "local",
                "skills": [
                    {"type": "skill_reference", "skill_id": "<skill_id>"},
                    {"type": "skill_reference", "skill_id": "<skill_id>", "version": 2},
                ],
            },
        }
    ],
    input="Use the configured skills and run locally to summarize today's CSV reports in this repo.",
)

print(response.output_text)

Skills in the system prompt

When skills are available to the tool, the platform adds each skill’s name, description, and path to hidden system prompt context so the model knows the skill exists.

The model decides whether to invoke a skill based on this metadata. If the model invokes a skill, it uses the path to read the full Markdown instructions from SKILL.md. For explicit control, you can instruct the model to “use the <skill name> skill.”

Limits and validation

• SKILL.md file matching is case-insensitive.
• Exactly one skill.md/SKILL.md file is allowed in a skill bundle.
• Skill front matter validation follows the agent skills specification.
• Maximum zip upload size is 50 MB.
• Maximum file count per skill version is 500.
• Maximum uncompressed file size is 25 MB.

Safety with network access

Versioning and management

Version pointers

• default_version is used when a version isn’t provided.
• latest_version tracks the newest upload.
• skill_reference.version accepts an integer or "latest".

Create a new version

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

Set default version

1
2
3
4
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}'

Delete rules

• You can’t delete the default version; set another default first.
• Deleting the last remaining version deletes the skill.
• Deleting a skill cascades to remove all versions.

Curated skills

OpenAI maintains a set of first-party skills that can be referenced by id (for example, openai-spreadsheets).

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

Inline skills

If you don’t want to create a hosted skill, you can inline a zip bundle (base64) in the environment’s skills array.

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

Risks and safety

It is very important to inspect any Skill used with the Responses API. Skills introduce security risks such as prompt injection-driven data exfiltration.

For Skills used in conjunction with network access, carefully review the Risks and safety section for networking.

Treat Skills as privileged code and instructions

Skill content can influence planning, tool usage, and command execution. Any Skill should be reviewed as potentially untrusted input until validated by the developer.

Do not expose an open Skills repository to end-users

Avoid product designs where consumer end-users can freely browse, select, or attach arbitrary Skills from an open catalog. This materially increases risk from:

• Prompt-injection and policy bypass via malicious SKILL.md instructions.
• Data exfiltration or destructive actions triggered by unvetted automation.

Integrate Skills at the developer level

Skills should be inspected and integrated by the developer, then exposed to end-users only through bounded product experiences. In practice:

• Map Skills to specific product workflows/use cases.
• Prevent end-user control over arbitrary Skill selection.
• Gate write or high-impact actions behind explicit approval and policy checks.

Require approval for sensitive actions

For workflows that can perform write or high-impact actions, require explicit approval before execution.

Validate data residency and retention requirements

We support Skills in two form factors, both local execution and hosted container-based execution. Skills running in OpenAI hosted containers cannot be used when Zero Data Retention is enabled. Read more about our data controls.