コンテンツにスキップ

スキルを作成する

エージェントスキルを使用して、Codex をタスク固有の機能で拡張します。スキルは、Codex がワークフローに沿って確実に実行できるよう、手順、リソース、オプションのスクリプトをパッケージ化したものです。スキルは オープンエージェントスキル標準 を基盤としています。

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

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

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

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

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

この上限が適用されるのは、スキルの初期リストだけです。Codex がスキルを選択すると、そのスキルの完全な SKILL.md 手順を引き続き読み込みます。

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

<FileTree class="mt-4" tree={[ { name: "my-skill/", open: true, children: [ { name: "SKILL.md", comment: "必須: 手順 + メタデータ", }, { name: "scripts/", comment: "オプション: 実行可能なコード", }, { name: "references/", comment: "オプション: ドキュメント", }, { name: "assets/", comment: "オプション: テンプレート、リソース", }, { name: "agents/", open: true, children: [ { name: "openai.yaml", comment: "オプション: 外観と依存関係", }, ], }, ], },

]} />

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 は、リポジトリ、ユーザー、管理者、システムの各場所からスキルを読み込みます。リポジトリの場合、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 に同梱されています。 スキル作成ツールや計画スキルなど、幅広いユーザーに役立つスキルです。Codex を起動すると、すべてのユーザーが利用できます。

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

これらの場所は、作成とローカル検出のためのものです。単一のリポジトリを超えて再利用可能なスキルを配布したい場合、またはスキルをコネクターとともにオプションでバンドルしたい場合は、プラグイン を使用します。

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

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

プラグインには、1 つ以上のスキルを含めることができます。また、アプリのマッピング、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、エージェントスキル仕様 を参照してください。インストール可能な配布には、プラグイン を推奨します。