如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

技能

为智能体提供可复用的指令和配套文件。

智能体技能为智能体提供完成特定任务所需的可复用指令和配套文件。您可以在 Responses API 的 Shell 工具中使用技能,也可以在 Agents API 沙盒中提供技能。

下文关于上传、附加和版本管理的说明适用于 Responses API 的 Shell 工具。Agents API 会话会从沙盒内的目录中发现技能。

Responses API 支持两种技能执行方式:在本地执行,或在托管容器中执行。要在自己的机器上运行代码,请使用 Shell 工具的本地执行模式。

什么是技能

技能是一个文件目录,其中包含 SKILL.md 清单(文件头部的元数据和正文中的指令)。技能以模块化指令的形式记录流程和规范,例如公司的写作风格指南或多步骤工作流。上传的技能以技能包为单位管理版本。

技能兼容开放的智能体技能标准。

SKILL.md 示例
---
name: basic-math
description: Add or multiply numbers.
---

Use this skill when you need a quick sum or product of numbers.

在发现技能时,模型能看到技能的名称和描述。请在描述中说明技能的用途以及何时应使用它。例如,与“协助处理法律事务”相比,“审查供应商协议,并使用备选条款标注修订内容”能为模型提供更有用的上下文。

将主要指令放在 SKILL.md 中,并按需链接到配套文件:

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

将背景资料放在 references/ 中,将可重复执行的操作脚本放在 scripts/ 中,将可复用的模板放在 assets/ 中。

创建技能

您可以使用多部分表单数据上传目录,也可以上传仅含一个顶层文件夹的 .zip 文件。

方式一:上传目录(多部分表单)

上传多个 files[] 表单部分。每个部分都包含对应文件在同一顶层文件夹内的路径。

创建技能(多部分表单)
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'

方式二:上传 ZIP 文件

将顶层文件夹压缩为 ZIP 文件,然后上传该文件。

创建技能(ZIP 文件)
curl -X POST 'https://api.openai.com/v1/skills' \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F 'files=@./basic_math.zip;type=application/zip'

等待上传的版本就绪

刚上传的版本可能需要短暂等待才能使用,在此期间请求该版本可能会返回 404。将其附加到容器或 Live 会话之前,请使用 GET /v1/skills/{skill_id}/versions/{version} 获取该版本。如果在上传成功后立即请求该版本时收到 404,请设置超时时间,并在短暂等待后重试。成功获取版本后,请在技能引用中使用返回的版本字符串。

在托管式 Shell 中使用技能

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

在托管式 Shell 中使用技能
curl -L 'https://api.openai.com/v1/responses' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-6.2-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."
  }'

通过提示词指定技能

挂载技能后,模型可以自行决定何时使用它。如果您希望模型的行为更可预测,可以在适当的时候明确指示模型“使用 <skill name> 技能”。

在本地 Shell 模式下使用技能

本地 Shell 模式也支持技能,但本地 Shell 与托管式 Shell 接受的技能附件格式不同。

  • 托管式 Shell 支持通过 skill_reference 附加已上传的技能,也支持引用精选技能和指定版本。
  • 本地 Shell 不支持 skill_reference 附件。请在您控制的运行环境中,通过本地文件路径提供技能文件。

有关本地 Shell 执行的详细说明,请参阅 Shell 指南。

运行 TypeScript 示例需要 Node.js 22.6 或更高版本,且 Docker 守护进程必须处于运行状态。请将 Docker 适配器保存为 support/local-skill-sandbox.mjs,并将示例保存为 tools/skills/local-shell.mts,以便正确解析示例中的相对导入路径。设置 OPENAI_API_KEY 后,在包含 support 和 tools 的目录中安装 SDK、拉取适配器指定的固定版本镜像并运行示例:

npm install openai
docker pull "$(node --input-type=module -e 'import { sandboxImage } from "./support/local-skill-sandbox.mjs"; console.log(sandboxImage)')"
node --experimental-strip-types tools/skills/local-shell.mts

适配器的辅助函数分别承担以下职责:

辅助函数 应用需要完成的操作
withLocalSkillSandbox(name, workflow) 创建包含 /workspace/skills/csv-insights/SKILL.md 和 /workspace/reports.csv 的隔离 Python 环境,调用 workflow 并传入一个 AbortSignal,在工作流结束时移除该环境。
executeShellCall(name, call, signal) 在该环境中执行请求的命令,并返回 shell_call_output,其中包含原始 call_id、标准输出、标准错误输出以及命令退出或超时的结果。
readSkillReport(name, signal) 从环境中读取生成的 /workspace/report.md,并限制读取的数据量。

适配器必须强制执行时限和输出上限。示例中生成的命令仅在隔离的运行环境中执行。

在本地 Shell 模式下使用技能
curl -L 'https://api.openai.com/v1/responses' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-6.2-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."
  }'

Agents API

要在 Agents API 中使用技能,请将技能目录放入沙盒,并在创建会话时通过 environment.capability_directories 注册这些目录的父目录。这些父目录称为能力目录。执行框架会在其中发现技能。这种配置不使用托管式 Shell 的 skill_reference 附件格式。

例如,您可以在沙盒中分别放置用于审查合同和审查 Pull Request 的技能:

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

在创建会话的请求中使用以下环境配置:

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

能力目录必须满足以下要求:

  • 路径必须指向沙盒内的目录。
  • 路径必须是绝对路径且不能重复,也不能包含 . 或 .. 路径段。
  • 每个会话最多可注册 32 个能力目录。
  • 目录必须已经存在于环境中。

沙盒就绪后,执行框架会在这些目录中搜索 SKILL.md 文件,并将找到的每个技能的名称和描述添加到上下文中。模型可以选择相关技能,阅读其完整指令和配套文件。

有关会话设置,请参阅智能体配置。有关执行环境,请参阅连接沙盒。向智能体提供技能前,请先审查技能及其配套文件,并遵循沙盒安全指南。

用户提示词中的技能

使用 Responses API 的 Shell 工具时,平台会将每个可用技能的 name、description 和 path 添加到用户提示词的上下文中,让模型知道有哪些技能可用。

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

技能指令属于用户提示词输入,而非系统提示词输入,因此与用户提供的其他指令具有相同的优先级。如果您希望明确指定技能,仍然可以指示模型“使用 <skill name> 技能”。

限制与验证

  • 匹配 SKILL.md 文件名时不区分大小写。
  • 每个技能包必须有且只有一个 skill.md/SKILL.md 文件。
  • 技能文件头部元数据的验证遵循智能体技能规范。
  • 上传的 ZIP 文件最大为 50 MB。
  • 每个技能版本最多包含 500 个文件。
  • 单个文件的未压缩大小不能超过 25 MB。

启用网络访问时的安全注意事项

请审查与 Responses API 配合使用的每一项技能。技能会带来安全风险,例如攻击者可能通过提示词注入窃取数据。使用此工具前,请仔细阅读下文的风险与安全一节。

版本控制与管理

版本指针

  • 未指定版本时,使用 default_version。
  • latest_version 指向最近上传的版本。
  • skill_reference.version 接受版本字符串,例如 "2" 或 "latest"。
  • 更新 default_version 时,也必须使用字符串。

创建新版本

创建新的技能版本
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'

设置默认版本

设置技能的默认版本
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" }

内联技能

如果您不想创建托管技能,可以将经过 Base64 编码的 ZIP 技能包直接放入环境的 skills 数组中。

内联技能包
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 指令实施提示词注入或绕过策略。
  • 未经审查的自动化操作导致数据被窃取或触发破坏性操作。

由开发者集成技能

开发者应先审查并集成技能,再仅通过使用范围明确的产品功能向最终用户提供这些技能。具体做法如下:

  • 将技能与具体的产品工作流或使用场景对应起来。
  • 限制最终用户的选择范围,防止其任意选用技能。
  • 只有在获得明确审批并通过策略检查后,才允许执行写入操作或其他影响重大的操作。

敏感操作必须经过审批

对于可执行写入操作或其他影响重大的操作的工作流,必须在执行前获得明确审批。

核实数据驻留和保留要求

Responses API 支持两种技能执行方式:在本地执行,或在托管容器中执行。托管技能遵循与托管式 Shell 相同的容器生命周期。容器处于活动状态时,已挂载的技能和容器文件均可使用。容器到期或被删除时,这些技能和文件也会被丢弃。如果您希望整个执行过程都在自己管理的基础设施上完成,请使用本地 Shell 模式。有关 Agents API 沙盒,请参阅沙盒生命周期。您还可以进一步了解我们的数据控制措施。