For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
メインナビゲーション
Theme

スキル

再利用可能な指示と補助ファイルをエージェントに提供します。

エージェントスキルを使うと、タスクに必要な指示と補助ファイルをまとめてエージェントに提供し、繰り返し利用できます。スキルは Responses API のシェルツールで使用することも、Agents API のサンドボックスに配置して利用することもできます。

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

Responses API は、スキルのローカル実行とホスト型コンテナでの実行に対応しています。手元のマシンでコードを実行するには、シェルツールのローカル実行モードを使用します。

スキルとは

スキルは、SKILL.md マニフェスト(フロントマターと指示)と関連ファイルをまとめたディレクトリです。社内のスタイルガイドから複数のステップを含むワークフローまで、手順や規約をスキル単位で明文化できます。アップロードしたスキルは、バージョン付きのバンドルとして管理されます。

スキルは、オープンな Agent Skills 標準と互換性があります。

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/ には再利用するテンプレートを配置します。

スキルの作成

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

方法 1:ディレクトリのアップロード(マルチパート)

複数の 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'

方法 2:zip ファイルのアップロード

最上位フォルダーを 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 を返した場合は、タイムアウトを設定し、短い待機時間を挟んで再試行します。取得に成功したら、返されたバージョン文字列をスキル参照に指定します。

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

ホスト型シェル環境にスキルをマウントするには、シェルツールを呼び出す際に tools[].environment.skills でスキルをアタッチします。

ホスト型シェルでのスキルの使用
curl -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."
  }'

プロンプトによるスキルの指定

スキルをマウントすると、モデルはいつ使うかを自ら判断できます。スキルを使うタイミングをより確実に制御したい場合は、必要な場面で「<skill name> スキルを使ってください」とモデルに明示的に指示します。

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

スキルはローカルシェルモードでも利用できます。ただし、ローカルシェルとホスト型シェルでは、対応するスキルのアタッチ形式が異なります。

  • ホスト型シェルでは、アップロード済みのスキルを skill_reference でアタッチできます。厳選スキルの参照やバージョンの明示的な指定にも対応しています。
  • ローカルシェルは skill_reference によるアタッチに対応していません。自身で管理するランタイム内のローカルファイルパスを使って、スキルのファイルを提供してください。

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

JavaScript のサンプルを実行するには、Node.js と起動済みの Docker デーモンが必要です。相対パスでインポートできるように、Docker アダプターを support/local-skill-sandbox.mjs に、サンプルを tools/skills/local-shell.mjs に保存します。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 tools/skills/local-shell.mjs

アダプターの各ヘルパーが担う処理は次のとおりです。

ヘルパー アプリケーション側で行う処理
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 を、読み取りサイズに上限を設けて読み込みます。

アダプターでは、実行時間と出力量の上限を必ず適用してください。このサンプルでは、生成されたコマンドは隔離されたランタイム内でのみ実行されます。

ローカルシェルモードでのスキルの使用
curl -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."
  }'

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

セッション作成リクエストでは、次の環境設定を指定します。

{
  "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 には、"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" }

インラインスキル

ホスト型スキルを作成せずに利用する場合は、環境の skills 配列に base64 でエンコードした zip バンドルを直接埋め込むことができます。

スキルバンドルの埋め込み
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 は、スキルのローカル実行とホスト型コンテナでの実行に対応しています。ホスト型スキルのライフサイクルは、ホスト型シェルのコンテナと同じです。マウントしたスキルとコンテナ内のファイルは、コンテナがアクティブな間は利用でき、有効期限が切れるかコンテナが削除されると破棄されます。すべての処理を自身で管理するインフラ上で実行したい場合は、ローカルシェルモードを使用してください。Agents API のサンドボックスについては、サンドボックスのライフサイクルを参照してください。OpenAI のデータ管理についてもご覧ください。