技能 | OpenAI API

Agent Skills 允许你在托管和本地 shell 环境中上传并复用带有版本控制的文件包。

我们支持两种形式的 Skills：本地执行和基于托管容器的执行。要在你自己的机器上运行代码，请使用以下工具的本地执行模式： shell 工具.

什么是 skill

一个 skill 是一个带有版本控制的文件包以及一个 SKILL.md 清单（前置元数据 + 指令）。Skills 是模块化的指令，您可以使用它们将流程和约定编纂成文，涵盖从公司风格指南到多步骤工作流的各个方面。

示例 SKILL.md

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.

创建一个 skill

您可以将目录作为 multipart 表单数据上传，或者上传一个包含单个顶级文件夹的 .zip 其中包含一个顶级文件夹。

选项 1：目录上传 (multipart)

上传多个 files[] 部分。每个部分包含单个顶层文件夹内的路径。

创建技能（多部分）

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'

选项 2：Zip 上传

将顶层文件夹压缩为 Zip 并上传该 Zip 文件。

创建技能（Zip）

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'

在托管 Shell 中使用技能

要在托管 Shell 环境中挂载技能，请通过以下方式进行附加 tools[].environment.skills 在调用 Shell 工具时。

在托管 Shell 中使用技能

curl

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
curl -L 'https://api.openai.com/v1/responses' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-5.5",
    "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
import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-5.5",
  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
22
from openai import OpenAI

client = OpenAI()

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

提示行为

技能挂载后，模型可自行决定何时使用。若需更具确定性的行为，请明确指示模型在适当时“使用该 <skill name> 技能”。

在本地 Shell 模式下使用技能

技能也可在本地 Shell 模式下使用，但本地 Shell 和托管 Shell 不支持相同的技能附加格式。

托管的 shell 支持上传的 skill_reference 附件，包括经过筛选的技能和显式版本。
本地 shell 不支持 skill_reference 附件。相反，请在您控制的运行时环境中通过本地文件路径提供技能文件。

使用 Shell 指南以了解本地 shell 执行的详细信息。

在本地 shell 模式下使用技能

curl

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
curl -L 'https://api.openai.com/v1/responses' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-5.5",
    "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
import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-5.5",
  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
21
22
23
24
25
from openai import OpenAI

client = OpenAI()

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

用户提示词中的技能

当技能可用于该工具时，平台会将每个技能的 name, description，且 path 添加到用户提示词上下文中，以便模型知道该技能的存在。

模型会根据此元数据决定是否调用技能。如果模型调用技能，它会使用 path 从读取完整的 Markdown 指令 SKILL.md.

技能指令属于用户提示词输入（而非系统提示词输入），因此它们会与其他用户提供的指令享有相同的处理优先级。为了进行显式控制，您仍然可以指示模型“使用 <skill name> 技能”。

限制与验证

SKILL.md 文件匹配不区分大小写。
每个技能包中恰好只允许包含一个 skill.md/SKILL.md 文件。
技能前置数据验证遵循代理技能规范.
ZIP 压缩包的最大上传大小为 50 MB.
每个技能版本的最大文件数量为 500.
未压缩文件的最大大小为 25 MB.

网络访问的安全性

检查与 Responses API 配合使用的任何技能至关重要。技能会带来安全风险，例如由提示词注入驱动的数据泄露。请仔细审查风险与安全部分。

版本控制与管理

版本指针

default_version 在未提供版本时使用。
latest_version 追踪最新上传的内容。
skill_reference.version 接受整数或 "latest".

创建新版本

创建新技能版本

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'

设置默认版本

设置技能的默认版本

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

删除规则

您无法删除默认版本；请先设置另一个默认版本。
删除最后剩余的版本将删除该技能。
删除某项技能会级联移除其所有版本。

精选技能

OpenAI 维护着一组第一方技能，可以通过 id 引用（例如， openai-spreadsheets).

引用精选技能

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

内联技能

如果您不想创建托管技能，可以在环境的 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"'"
        }
      }
    ]
  }'

风险与安全

检查与 Responses API 配合使用的任何 Skill 非常重要。技能会引入安全风险，例如由提示注入驱动的数据泄露。

对于与网络访问结合使用的技能，请仔细查看网络风险与安全部分.

将技能视为特权代码和指令

技能内容可以影响规划、工具使用和命令执行。任何技能在开发者验证之前，都应被视为潜在的不可信输入加以审查。

不要向最终用户暴露开放的技能库

避免让消费者最终用户能够从开放目录中自由浏览、选择或附加任意技能的产品设计。这会显著增加以下风险：

通过恶意 SKILL.md 指令进行提示注入和绕过策略。
由未审查的自动化触发的数据泄露或破坏性操作。

在开发者层面集成技能

技能应由开发者检查和集成，然后仅通过有边界的产品体验暴露给最终用户。在实践中：

将技能映射到特定的产品工作流/用例。
防止最终用户控制任意技能的选择。
对写入或高影响的操作进行把关，要求其经过明确的批准和策略检查。

要求批准敏感操作

对于可以执行写入或高影响操作的工作流，要求在执行前获得明确批准。

验证数据驻留和保留要求

我们支持两种形式的 Skill：本地执行和基于托管容器的执行。托管技能遵循与托管 shell 相同的容器生命周期：已挂载的技能和容器文件在容器处于活动状态时保持可用，并在容器过期或被删除时被丢弃。如果您希望执行完全在您管理的基础设施上进行，请使用本地 shell 模式。了解更多关于我们的数据控制.

推荐

入门

核心概念

Apps SDK

工具

运行与扩展

评估

实时与音频

模型优化

专业模型

正式上线

旧版 API

资源

入门指南

使用 Codex

配置

管理

自动化

学习

发布

核心概念

规划

构建

部署

转化应用

指南

资源

指南

文件上传

API

衡量

广告主 API

API 参考

最新

主题

主题

贡献

分类

主题

项目

活动

什么是 skill

创建一个 skill

选项 1：目录上传 (multipart)

选项 2：Zip 上传

在托管 Shell 中使用技能

提示行为

在本地 Shell 模式下使用技能

用户提示词中的技能

限制与验证

网络访问的安全性

版本控制与管理

版本指针

创建新版本

设置默认版本

删除规则

精选技能

内联技能

风险与安全

将技能视为特权代码和指令

不要向最终用户暴露开放的技能库

在开发者层面集成技能

要求批准敏感操作

验证数据驻留和保留要求