スキル | OpenAI API

Agent Skills は、タスクに必要な再利用可能な指示と補助ファイルをエージェントに提供します。Responses API のシェルツールと組み合わせて使うか、Agents API のサンドボックス内で利用できるようにします。

以下のアップロード、添付、バージョン管理の手順は、Responses API のシェルツールを対象としています。Agents API のセッションでは、サンドボックス内のディレクトリからスキルが検出されます。

Responses API は、ローカル実行とホスト型のコンテナベース実行という 2 つの形態でスキルをサポートしています。自分のマシンでコードを実行するには、シェルツールのローカル実行モードを使います。

スキルとは

スキルは、SKILL.md マニフェスト（フロントマターと指示）を含むファイル群をまとめたディレクトリです。スキルはモジュール化された指示であり、社内のスタイルガイドから複数のステップにわたるワークフローまで、さまざまな手順や規約を明文化するために使えます。アップロードされたスキルには、バージョン管理されたバンドルが使われます。

スキルは、オープンなAgent 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.md に記載し、必要に応じて補助ファイルへのリンクを追加します：

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

背景資料には references/、繰り返し実行する処理には scripts/、再利用可能なテンプレートには assets/ を使います。

スキルの作成

ディレクトリをマルチパートフォームデータとしてアップロードするか、最上位フォルダーを 1 つ含む .zip ファイルをアップロードできます。

方法 1：ディレクトリのアップロード（マルチパート）

複数の files[] パートをアップロードします。各パートには、同じ最上位フォルダー内のパスを含めます。

スキルの作成（マルチパート）

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

ホスト型シェルでのスキルの使用

ホスト型シェル環境にスキルをマウントするには、シェルツールの呼び出し時に tools[].environment.skills を介してスキルを追加します。

ホスト型シェルでのスキルの使用

curl

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23import OpenAI from "openai";

const client = new OpenAI();

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

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

print(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
26
27
28
29
30package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	client := openai.NewClient()
	tool := responses.ToolUnionParam{OfShell: &responses.FunctionShellToolParam{
		Environment: responses.FunctionShellToolEnvironmentUnionParam{OfContainerAuto: &responses.ContainerAutoParam{
			Skills: []responses.ContainerAutoSkillUnionParam{
				{OfSkillReference: &responses.SkillReferenceParam{SkillID: "<skill_id>"}},
				{OfSkillReference: &responses.SkillReferenceParam{SkillID: "<skill_id>", Version: openai.String("2")}},
			},
		}},
	}}
	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: "gpt-6-astra",
		Tools: []responses.ToolUnionParam{tool},
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("Use the skills to add 144 and 377, then compute triangle area with base 9 height 13.")},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(response.OutputText())
}

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
27
28
29
30
31
32
33
34
35
36
37
38
39import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.responses.ResponseCreateParams;
import java.util.List;
import java.util.Map;

String skillId = "<skill_id>";

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .input(
            "Use the skills to add 144 and 377, then compute a triangle area with base 9 and height 13.")
        .putAdditionalBodyProperty(
            "tools",
            JsonValue.from(
                List.of(
                    Map.of(
                        "type",
                        "shell",
                        "environment",
                        Map.of(
                            "type",
                            "container_auto",
                            "skills",
                            List.of(
                                Map.of("type", "skill_reference", "skill_id", skillId),
                                Map.of(
                                    "type", "skill_reference",
                                    "skill_id", skillId,
                                    "version", "2")))))))
        .build();

client.responses().create(params).output().stream()
    .flatMap(item -> item.message().stream())
    .flatMap(message -> message.content().stream())
    .flatMap(content -> content.outputText().stream())
    .forEach(text -> System.out.println(text.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
26
27
28require "openai"

client = OpenAI::Client.new
response = client.responses.create(
  model: "gpt-6-astra",
  input: "Use the skills to add 144 and 377, then compute a triangle area with base 9 and height 13.",
  tools: [
    {
      type: :shell,
      environment: {
        type: :container_auto,
        skills: [
          {
            type: :skill_reference,
            skill_id: "<skill_id>"
          },
          {
            type: :skill_reference,
            skill_id: "<skill_id>",
            version: "2"
          }
        ]
      }
    }
  ]
)

puts(response.output_text)

プロンプトによる動作の指定

スキルがマウントされると、モデルはそのスキルを使うタイミングを判断できます。動作をより確実に指定したい場合は、必要に応じて「<skill name> スキルを使用してください」とモデルに明示的に指示します。

ローカルシェルモードでのスキルの使用

スキルはローカルシェルモードでも使用できますが、ローカルシェルとホスト型シェルでは、スキルを追加する際に利用できる形式が異なります。

ホスト型シェルでは、アップロードしたスキルを skill_reference 形式で追加できます。厳選されたスキルの利用や、バージョンの明示的な指定にも対応しています。
ローカルシェルでは、skill_reference 形式での追加に対応していません。代わりに、自分で管理するランタイム内のローカルファイルパスからスキルファイルを提供します。

ローカルシェルでの実行について詳しくは、シェルガイドを参照してください。

ローカルシェルモードでのスキルの使用

curl

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

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
26import OpenAI from "openai";

const client = new OpenAI();

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

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

print(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
26
27
28
29
30
31package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	client := openai.NewClient()
	tool := responses.ToolUnionParam{OfShell: &responses.FunctionShellToolParam{
		Environment: responses.FunctionShellToolEnvironmentUnionParam{OfLocal: &responses.LocalEnvironmentParam{
			Skills: []responses.LocalSkillParam{{
				Name:        "csv-insights",
				Description: "Summarize CSV files and produce a markdown report.",
				Path:        "<path-to-skill-folder>",
			}},
		}},
	}}
	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: "gpt-6-astra",
		Tools: []responses.ToolUnionParam{tool},
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("Use the csv-insights skill and run locally to summarize today's CSV reports in this repo.")},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(response.OutputText())
}

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
27
28
29
30
31
32
33
34
35
36
37
38import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.responses.ResponseCreateParams;
import java.util.List;
import java.util.Map;

String skillPath = "<path-to-skill-folder>";

ResponseCreateParams params =
    ResponseCreateParams.builder()
        .model("gpt-6-astra")
        .input("Use the csv-insights skill to summarize today's CSV reports.")
        .putAdditionalBodyProperty(
            "tools",
            JsonValue.from(
                List.of(
                    Map.of(
                        "type",
                        "shell",
                        "environment",
                        Map.of(
                            "type",
                            "local",
                            "skills",
                            List.of(
                                Map.of(
                                    "name", "csv-insights",
                                    "description",
                                        "Summarize CSV files and produce a Markdown report.",
                                    "path", skillPath)))))))
        .build();

client.responses().create(params).output().stream()
    .flatMap(item -> item.message().stream())
    .flatMap(message -> message.content().stream())
    .flatMap(content -> content.outputText().stream())
    .forEach(text -> System.out.println(text.text()));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24require "openai"

client = OpenAI::Client.new
response = client.responses.create(
  model: "gpt-6-astra",
  input: "Use the csv-insights skill to summarize today's CSV reports.",
  tools: [
    {
      type: :shell,
      environment: {
        type: :local,
        skills: [
          {
            name: "csv-insights",
            description: "Summarize CSV files and produce a Markdown report.",
            path: "<path-to-skill-folder>"
          }
        ]
      }
    }
  ]
)

puts(response.output_text)

Agents API

Agents API でスキルを使うには、スキルのディレクトリをサンドボックス内に配置し、セッションの作成時にその親ディレクトリを environment.capability_directories に登録します。この親ディレクトリを ケイパビリティディレクトリと呼びます。ハーネスは、これらのディレクトリを使ってスキルを検出します。この構成では、ホスト型シェルの skill_reference 添付形式は使いません。

たとえば、契約書レビュー用のスキルと Pull Request レビュー用のスキルをサンドボックス内に配置します：

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

セッション作成リクエストには、次の環境構成を使います：

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

ケイパビリティディレクトリには、次の要件があります：

パスは、サンドボックス内のディレクトリを指している必要があります。
パスは重複のない絶対パスである必要があり、. または .. のパスセグメントを含めることはできません。
1 つのセッションに登録できるケイパビリティディレクトリは、最大 32 個です。
ディレクトリは、環境内にあらかじめ存在している必要があります。

サンドボックスが利用可能になると、ハーネスはこれらのディレクトリ内で SKILL.md ファイルを検索し、検出した各スキルの名前と説明をコンテキストに追加します。モデルは関連するスキルを選び、指示の全文と補助ファイルを読み込めます。

セッションのセットアップについては「エージェントの構成」、実行環境については「サンドボックスの接続」を参照してください。エージェントがスキルを利用できるようにする前に、スキルとその補助ファイルをレビューし、サンドボックスのセキュリティガイダンスに従ってください。

ユーザープロンプト内のスキル

Responses API のシェルツールでは、モデルがスキルの存在を認識できるよう、プラットフォームが利用可能な各スキルの name、description、path をユーザープロンプトのコンテキストに追加します。

モデルは、このメタデータに基づいてスキルを呼び出すかどうかを判断します。スキルを呼び出す場合は、path を使って SKILL.md から Markdown 形式の指示の全文を読み込みます。

スキルの指示はシステムプロンプトではなくユーザープロンプトへの入力なので、ユーザーが提供する他の指示と同じ優先順位で扱われます。明示的に制御したい場合は、ここでも「<skill name> スキルを使用してください」とモデルに指示できます。

制限と検証

SKILL.md ファイルの照合では、大文字と小文字は区別されません。
スキルのファイル一式に含められる skill.md/SKILL.md ファイルは、必ず 1 つだけです。
スキルのフロントマターは、Agent Skills の仕様に従って検証されます。
アップロードできる zip ファイルの最大サイズは 50 MB です。
スキルの各バージョンに含められるファイル数の上限は 500 です。
非圧縮時のファイルサイズの上限は 25 MB です。

ネットワークアクセス時の安全性

Responses API で使用するスキルは、どれも内容を確認することが非常に重要です。スキルには、プロンプトインジェクションによるデータの不正流出などのセキュリティリスクがあります。このツールを使用する前に、以下のリスクと安全性のセクションをよく確認してください。

バージョン管理と管理操作

バージョンポインター

バージョンを指定しない場合は、default_version が使用されます。
latest_version は、最新のアップロードを指します。
skill_reference.version には、整数または "latest" を指定できます。

新しいバージョンの作成

スキルの新しいバージョンの作成

1
2
3curl -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
4curl -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
20INLINE_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 は、ローカル実行とホスト型のコンテナベース実行という 2 つの形態でスキルをサポートしています。ホスト型スキルは、ホスト型シェルと同じコンテナのライフサイクルに従います。マウントされたスキルとコンテナ内のファイルは、コンテナがアクティブな間は利用可能で、コンテナの有効期限が切れるか、コンテナが削除されると破棄されます。すべての実行を自分で管理するインフラストラクチャ内で完結させたい場合は、ローカルシェルモードを使います。Agents API のサンドボックスについては、「サンドボックスのライフサイクル」を参照してください。OpenAI のデータ管理についても詳しくご覧ください。

おすすめ

はじめに

基本コンセプト

SDK と CLI

リソース

レガシー API

モデルの選び方

テキストとコード

プロンプト

推論

画像と動画

リアルタイムと音声

特化型モデル

Agents API

Agents SDK

ChatKit

検索と取得

ツールとデータの接続

ツールを使ったワークフローの構築

コンピューターとコード

メディア

GPT-Live

Realtime API

音声を活用した開発

接続

音声処理

本番運用の開始

性能と品質

コストとスループット

安全性とガバナンス

インフラとアクセス

オペレーション

基本コンセプト

Plan

Build

Test and publish

Conversion specs

ガイド

リソース

はじめに

ガイド

File Upload

API

Measurement

Advertiser API

API リファレンス

はじめに

基礎

詳しく見る

利用可能な環境

リリース

ワークフロー

できること

リファレンス

カスタマイズ

設定ファイル

エージェントの構成

ChatGPT と Codex の機能拡張

Linux

Windows

開発ワークフロー

拡張と自動化

環境

Codex を使った開発

サードパーティ連携

リファレンス

権限

Codex Security

サイバーセーフティ

はじめに

ChatGPT Work

ID と認証

ワークスペースのアクセス、ポリシー、モデル

プラグインとコネクタの制御

利用状況、ガバナンス、コンプライアンス

展開とモデルプロバイダー

コミュニティ

ブログ

コミュニティ

ブログ