AI Native搜索…
Phase 3 · 上下文与技能

技能 | OpenAI API

OpenAI·2026/7/21·7 阅读

技能 | OpenAI API

来源: https://developers.openai.com/api/docs/guides/tools-skills 抓取时间: 2026-07-21 16:19:27

Agent 技能允许您在托管和本地 shell 环境中上传和重用版本化的文件包。 我们支持两种形式的技能：本地执行和托管的基于容器的执行。要在您自己的机器上运行代码，请使用 shell 工具 的本地执行模式。

什么是技能

技能是版本化的文件包加上 SKILL.md 清单（前置元数据 + 指令）。技能是模块化指令，您可以用它来编纂流程和约定，从公司风格指南到多步骤工作流。 技能与开放的 Agent 技能标准 兼容。 示例 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.

创建技能

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

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

上传多个 files[] 部分。每个部分包含单个顶级文件夹内的路径。 创建技能（多部分）

1
2
3
4
curl -X POST 'https://api.openai.com/v1/skills' \
  -H "Authorization: Bearer ***" \
  -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 ***" \
  -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 ***" \
  -d '{
    "model": "gpt-5.6",
    "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
23
import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-5.6",
  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.6",
    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 ***" \
  -d '{
    "model": "gpt-5.6",
    "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
26
import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-5.6",
  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.6",
    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 name> 技能”。

限制和验证

  • SKILL.md 文件匹配不区分大小写。
  • 技能包中只允许一个 skill.md/SKILL.md 文件。
  • 技能前置元数据验证遵循 Agent 技能规范。
  • 最大 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 ***" \
  -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 ***" \
  -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 ***" \
  -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 模式。阅读更多关于我们的 数据控制。

#P0 必读#OpenAI

评论 (0)

暂无评论，快来抢沙发吧！

学91学AI

© 2026 91学AI · 按岗位学 AI 与大数据. All rights reserved.