技能 | OpenAI API

代理技能（Agent Skills）允许您在托管和本地 Shell 环境中上传并复用带版本控制的文件包。

我们支持两种形式的技能：本地执行和基于容器的托管执行。若要在您自己的机器上运行代码，请使用 Shell 工具的本地执行模式。

什么是技能

技能是一个带版本控制的文件包，包含 SKILL.md 清单文件（元数据 + 指令）。技能是模块化的指令，您可以利用它们将流程和规范（从公司风格指南到多步工作流）进行代码化。

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.

创建技能

您可以将目录作为多部分表单数据（multipart form data）上传，或上传包含单个顶级文件夹的 .zip 文件。

选项 1：目录上传（多部分）

上传多个 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）

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 环境中挂载技能，请在调用 Shell 工具时通过 tools[].environment.skills 附加它们。

在托管 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)

提示行为

技能挂载后，模型可以决定何时使用它。如果您希望行为更具确定性，请显式指示模型在适当的时候“使用 <技能名称> 技能”。

在本地 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 从 SKILL.md 中读取完整的 Markdown 指令。

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

限制与验证

SKILL.md 文件匹配不区分大小写。
技能包中只允许存在一个 skill.md/SKILL.md 文件。
技能元数据（Front matter）验证遵循 Agent Skills 规范。
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 数组中内联一个 zip 包（base64 编码）。

内联技能包

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.md 指令进行提示注入和策略绕过。
由未经审查的自动化操作引发的数据窃取或破坏性行为。

在开发者层面集成技能

技能应由开发者审查并集成，然后仅通过受限的产品体验暴露给最终用户。在实践中：

将技能映射到特定的产品工作流/用例。
防止最终用户控制任意技能的选择。
将写入或高影响操作置于显式批准和策略检查之后。

对敏感操作要求批准

对于可以执行写入或高影响操作的工作流，要求在执行前进行显式批准。

验证数据驻留和保留要求

我们支持两种形式的技能：本地执行和基于容器的托管执行。托管技能遵循与托管 Shell 相同的容器生命周期：挂载的技能和容器文件在容器活跃期间可用，并在容器过期或删除时被丢弃。如果您希望执行完全停留在您管理的架构上，请使用本地 Shell 模式。阅读更多关于我们的数据控制信息。

推荐

开始使用

核心概念

Agents SDK

工具

运行与扩展

评估

实时与音频

模型优化

专用模型

上线

遗留 API

资源

开始使用

使用 Codex

配置

管理

自动化

学习

发布版本

核心概念

规划

构建

部署

转化类应用

指南

资源

指南

文件上传

API

衡量

广告主 API

API 参考

最近

主题

主题

贡献

分类

主题

项目

活动

什么是技能

创建技能

选项 1：目录上传（多部分）

选项 2：Zip 上传

在托管 Shell 中使用技能

提示行为

在本地 Shell 模式下使用技能

用户提示中的技能

限制与验证

网络访问的安全性

版本控制与管理

版本指针

创建新版本

设置默认版本

删除规则

精选技能

内联技能

风险与安全

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

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

在开发者层面集成技能

对敏感操作要求批准

验证数据驻留和保留要求