ChatGPT ドキュメント
日本語
お問い合わせ goolvyouyou@gmail.com

スキルを構築する

Codex に新しい機能と専門知識を追加します

エージェントスキルを使用して、タスク固有の機能を Codex に追加できます。スキルは、指示、リソース、オプションのスクリプトをパッケージ化し、Codex がワークフローを確実に実行できるようにします。スキルはオープンなエージェントスキル標準に基づいています。

スキルは、再利用可能なワークフローを作成するための形式です。プラグインは、再利用可能なスキルとコネクターを、ウェブの ChatGPT Work、およびデスクトップアプリの ChatGPT Work と Codex に配布します。Codex CLI でもプラグインをインストールできます。スキルを使用してワークフロー自体を設計し、ワークスペース内のほかのユーザーがインストールできるようにする場合は、プラグインとしてパッケージ化してください。

スキルは、ChatGPT デスクトップアプリ、Codex CLI、IDE 拡張機能で利用できます。

ChatGPT デスクトップアプリでは、サイドバーの Skills を開くと、プロジェクト全体で作成されたスキルを表示して確認できます。

ChatGPT デスクトップアプリで利用可能なスキルを表示するスキルピッカー（ライトモード）

スキルは、コンテキストを効率的に管理するために段階的開示を使用します。Codex は各スキルの名前、説明、ファイルパスを最初に確認します。スキルを使用すると判断した場合にのみ、完全な SKILL.md の指示を読み込みます。

Codex はタスクに適したスキルを選択できるように、利用可能なスキルの初期一覧をコンテキストに含めます。プロンプトのほかの部分を圧迫しないよう、この一覧に使用するのはモデルのコンテキストウィンドウの最大 2%、コンテキストウィンドウが不明な場合は 8,000 文字までです。多数のスキルがインストールされている場合、Codex はまずスキルの説明を短縮します。大規模なスキルセットでは、初期一覧から一部のスキルが省略され、警告が表示されることがあります。

この上限は、スキルの初期一覧にのみ適用されます。Codex がスキルを選択すると、そのスキルの完全な SKILL.md の指示を読み込みます。

スキルは、SKILL.md ファイルと、オプションのスクリプトおよびリファレンスを含むディレクトリです。SKILL.md ファイルには name と description を含める必要があります。

my-skill/
├── SKILL.md          # Required: instructions and metadata
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates and resources
└── agents/
    └── openai.yaml   # Optional: appearance and dependency declarations

Codex がスキルを使用する仕組み

Codex は、次の2つの方法でスキルを有効にできます。

  1. 明示的な呼び出し: プロンプトにスキルを直接含めます。CLI/IDE では、/skills を実行するか、$ と入力してスキルをメンションします。
  2. 暗黙的な呼び出し: タスクがスキルの description と一致する場合、Codex がスキルを選択できます。

暗黙的な一致は description に依存するため、スコープと境界が明確な簡潔な説明を記述してください。説明が短縮された場合でも Codex がスキルを照合できるよう、主要なユースケースとトリガーワードを説明の先頭に置いてください。

スキルを作成する

ワークフローをすでに把握していて、説明するより実演するほうが簡単な場合は、 Record & Replayを使用してください。Codex がワークフローを記録し、 手順を調べて、実演から再利用可能なスキルの下書きを作成します。

スキルを文章で説明する場合は、組み込みの作成ツールを使用します。

$skill-creator

作成ツールは、スキルの機能、スキルが呼び出される条件、指示のみの構成にするかスクリプトを含めるかを尋ねます。デフォルトは指示のみです。

SKILL.md ファイルを含むフォルダーを作成し、スキルを手動で作成することもできます。

---
name: skill-name
description: Explain exactly when this skill should and should not trigger.
---

Skill instructions for Codex to follow.

Codex はスキルへの変更を自動的に検出します。更新が表示されない場合は、Codex を再起動してください。

スキルの保存場所

Codex は、リポジトリ、ユーザー、管理者、システムの各場所からスキルを読み取ります。リポジトリでは、現在の作業ディレクトリからリポジトリルートまでの各ディレクトリにある .agents/skills をスキャンします。2つのスキルが同じ name を共有していても、Codex はそれらをマージしません。両方がスキルセレクターに表示されることがあります。

スキルのスコープ 場所 推奨用途
REPO $CWD/.agents/skills
現在の作業ディレクトリ: Codex を起動した場所です。		 リポジトリまたはコード環境で作業している場合、チームは作業フォルダーに関連するスキルをチェックインできます。たとえば、特定のマイクロサービスやモジュールにのみ関連するスキルです。
REPO $CWD/../.agents/skills
Git リポジトリ内で Codex を起動した場合の CWD より上位のフォルダーです。		 ネストされたフォルダーを持つリポジトリでは、組織は親フォルダーの共有領域に関連するスキルをチェックインできます。
REPO $REPO_ROOT/.agents/skills
Git リポジトリ内で Codex を起動した場合の最上位ルートフォルダーです。		 ネストされたフォルダーを持つリポジトリでは、組織はリポジトリを使用するすべてのユーザーに関連するスキルをチェックインできます。これらは、リポジトリ内のどのサブフォルダーでも利用可能なルートスキルです。
USER $HOME/.agents/skills
ユーザーの個人フォルダーにチェックインされた任意のスキルです。		 ユーザーが作業する可能性のあるあらゆるリポジトリに適用できる、そのユーザー向けのスキルを整理するために使用します。
ADMIN /etc/codex/skills
共有システム領域にある、マシンまたはコンテナへチェックインされた任意のスキルです。		 SDK スクリプトや自動化、およびマシン上の各ユーザーが利用できるデフォルトの管理者スキルをチェックインするために使用します。
SYSTEM OpenAI によって Codex に同梱されています。 skill-creator や plan スキルなど、幅広いユーザーに役立つスキルです。Codex を起動すると、すべてのユーザーが利用できます。

Codex はシンボリックリンクされたスキルフォルダーに対応し、これらの場所をスキャンするときにリンク先をたどります。

これらの場所は、作成とローカル検出のためのものです。単一のリポジトリを越えて 再利用可能なスキルを配布する場合や、必要に応じてコネクターもまとめる場合は、 プラグインを使用してください。

プラグインでスキルを配布する

スキルフォルダーを直接使用する方法は、ローカルでの作成やリポジトリ固有のワークフローに最適です。 再利用可能なスキルを配布する、2つ以上のスキルをまとめる、または スキルとコネクターを一緒に提供する場合は、 プラグインとしてパッケージ化してください。

プラグインには、1つ以上のスキルを含めることができます。必要に応じて、app マッピング、MCP サーバー構成、プレゼンテーションアセットを1つの パッケージにまとめることもできます。

ローカルで使用する厳選スキルをインストールする

個人のローカル Codex 環境に組み込み以外の厳選スキルを追加するには、$skill-installer を使用します。たとえば、$linear スキルをインストールするには、次のようにします。

$skill-installer linear

ほかのリポジトリからスキルをダウンロードするよう、インストーラーに指示することもできます。 Codex は新しくインストールされたスキルを自動的に検出します。表示されない場合は、 Codex を再起動してください。

これはローカル環境のセットアップと実験に使用してください。独自スキルを再利用可能な形で 配布する場合は、プラグインを推奨します。

スキルを有効または無効にする

~/.codex/config.toml の [[skills.config]] エントリを使用すると、スキルを削除せずに無効化できます。

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

~/.codex/config.toml を変更した後は Codex を再起動してください。

オプションのメタデータ

agents/openai.yaml を追加すると、ChatGPT デスクトップアプリの UI メタデータを構成し、呼び出しポリシーを設定し、ツールの依存関係を宣言して、スキルをよりシームレスに使用できるようになります。

interface:
  display_name: "Optional user-facing name"
  short_description: "Optional user-facing description"
  icon_small: "./assets/small-logo.svg"
  icon_large: "./assets/large-logo.png"
  brand_color: "#3B82F6"
  default_prompt: "Optional surrounding prompt to use the skill with"

policy:
  allow_implicit_invocation: false

dependencies:
  tools:
    - type: "mcp"
      value: "openaiDeveloperDocs"
      description: "OpenAI Docs MCP server"
      transport: "streamable_http"
      url: "https://developers.openai.com/mcp"

allow_implicit_invocation（デフォルト: true）: false の場合、Codex はユーザープロンプトに基づいてスキルを暗黙的に呼び出しません。明示的な $skill による呼び出しは引き続き機能します。

ベストプラクティス

  • 各スキルの目的を1つの作業に絞ってください。
  • 決定論的な動作や外部ツールが必要な場合を除き、スクリプトより指示を優先してください。
  • 入力と出力を明示し、命令形で手順を記述してください。
  • スキルの説明に対してプロンプトをテストし、意図したトリガー動作になることを確認してください。

その他の例については、 GitHub CI の修復、 PDF、 Linear、 openai/skills、 エージェントスキル仕様をご覧ください。 インストール可能な形で配布する場合は、プラグインを推奨します。