スキル作成ガイド (Skill Creator)
このスキルは、効果的なスキルを作成するためのガイダンスを提供します。
スキルについて
スキルは、専門知識、ワークフロー、ツールを提供することでCodexの機能を拡張する、モジュール化された自己完結型フォルダです。それらは特定のドメインやタスクのための「オンボーディングガイド」と考えてください。スキルは、汎用エージェントであるCodexを、どのモデルも完全には持ち得ない手続き的知識を備えた特化エージェントに変えます。
スキルが提供するもの
- 専門ワークフロー - 特定ドメインのための複数ステップの手順
- ツール連携 - 特定のファイル形式やAPIを扱うための指示
- ドメイン知識 - 企業固有の知識、スキーマ、ビジネスロジック
- バンドルリソース - 複雑で反復的なタスクのためのスクリプト、リファレンス、アセット
コア原則
簡潔さが鍵
コンテキストウィンドウは公共財です。スキルは、システムプロンプト、会話履歴、他のスキルのメタデータ、実際のユーザーリクエストなど、Codexが必要とする他のすべてのものとコンテキストウィンドウを共有します。
デフォルトの前提: Codexはすでに非常に賢い。 Codexがまだ持っていないコンテキストのみを追加してください。情報のひとつひとつに問いかけてください: 「Codexは本当にこの説明を必要としているか？」「この段落はそのトークンコストに見合う価値があるか？」
冗長な説明よりも簡潔な例を優先してください。
適切な自由度を設定する
タスクの脆弱性と変動性に応じて、詳細度のレベルを合わせてください:
高自由度 (テキストベースの指示): 複数のアプローチが有効な場合、決定が文脈に依存する場合、またはヒューリスティックがアプローチを導く場合に使用します。
中自由度 (パラメータ付きの疑似コードまたはスクリプト): 好ましいパターンが存在する場合、ある程度のバリエーションが許容される場合、または設定が動作に影響を与える場合に使用します。
低自由度 (特定のスクリプト、少数のパラメータ): 操作が脆弱でエラーが発生しやすい場合、一貫性が重要な場合、または特定の順序に従う必要がある場合に使用します。
Codexが道を探索していると考えてください: 崖のある狭い橋には特定のガードレール（低自由度）が必要ですが、広い野原では多くのルート（高自由度）が可能です。
検証の整合性を保護する
イテレーション中にサブエージェントを使用して、スキルが現実的なタスクで機能するかどうか、または疑わしい問題が実際に存在するかどうかを検証しても構いません。これは、改訂後にスキルの動作、出力、または障害モードについて独立した評価を受けたい場合に最も役立ちます。新しいサブエージェントを開始できる場合にのみこれを行ってください。
検証のためにサブエージェントを使用する場合は、それを評価面として扱ってください。目標は、スキルが一般化するかどうかを学ぶことであり、別のエージェントが漏洩したコンテキストから答えを再構築できるかどうかではありません。
検証を実行するために必要な最小限のタスクローカルコンテキストのみを提供してください。意図した答え、疑わしいバグ、意図した修正、または以前の結論を、検証で明示的に必要とされない限り渡さないでください。
スキルの構造
すべてのスキルは、必須の SKILL.md ファイルとオプションのバンドルリソースで構成されます:
skill-name/
├── SKILL.md (必須)
│ ├── YAML フロントマターメタデータ (必須)
│ │ ├── name: (必須)
│ │ └── description: (必須)
│ └── Markdown 指示 (必須)
├── agents/ (推奨)
│ └── openai.yaml - スキルリストとチップ用のUIメタデータ
└── バンドルリソース (オプション)
├── scripts/ - 実行可能コード (Python/Bash/など)
├── references/ - 必要に応じてコンテキストにロードすることを目的としたドキュメント
└── assets/ - 出力で使用されるファイル (テンプレート、アイコン、フォントなど)
SKILL.md (必須)
すべての SKILL.md は以下で構成されます:
- フロントマター (YAML):
nameとdescriptionフィールドを含みます。これらはCodexがスキルをいつ使用するかを判断するために読み取る唯一のフィールドであるため、スキルが何であるか、そしていつ使用すべきかを説明する際、明確かつ包括的であることが非常に重要です。 - 本文 (Markdown): スキルを使用するための指示とガイダンス。スキルがトリガーされた後にのみロードされます（ロードされる場合）。
エージェントメタデータ (推奨)
- スキルリストとチップ用のUI向けメタデータ
- 値を生成する前に
references/openai_yaml.mdを読み、その説明と制約に従ってください - スキルを読んで、人間向けの
display_name、short_description、default_promptを作成してください scripts/generate_openai_yaml.pyまたはscripts/init_skill.pyに値--interface key=valueとして渡すことで、決定論的に生成してください- 更新時:
agents/openai.yamlがまだSKILL.mdと一致しているか検証し、古くなっていたら再生成してください - 明示的に提供された場合にのみ、他のオプションのインターフェースフィールド (アイコン、ブランドカラー) を含めてください
- フィールドの定義と例については
references/openai_yaml.mdを参照してください
バンドルリソース (オプション)
スクリプト (scripts/)
決定論的な信頼性が必要なタスクや、繰り返し書き直されるタスクのための実行可能コード (Python/Bash/など)。
- 含めるタイミング: 同じコードが繰り返し書き直されている場合、または決定論的な信頼性が必要な場合
- 例: PDF回転タスクのための
scripts/rotate_pdf.py - 利点: トークン効率が良く、決定論的で、コンテキストにロードせずに実行できる可能性がある
- 注意: パッチ適用や環境固有の調整のために、Codexがスクリプトを読み取る必要がある場合があります
リファレンス (references/)
Codexのプロセスと思考に情報を提供するために、必要に応じてコンテキストにロードされることを目的としたドキュメントと参考資料。
- 含めるタイミング: Codexが作業中に参照すべきドキュメントがある場合
- 例: 財務スキーマ用の
references/finance.md、会社のNDAテンプレート用のreferences/mnda.md、会社のポリシー用のreferences/policies.md、API仕様用のreferences/api_docs.md - 使用例: データベーススキーマ、APIドキュメント、ドメイン知識、会社のポリシー、詳細なワークフローガイド
- 利点:
SKILL.mdをスリムに保ち、Codexが必要と判断した場合にのみロードされる - ベストプラクティス: ファイルが大きい場合（>1万語）、
SKILL.mdにgrep検索パターンを含めてください - 重複を避ける: 情報は
SKILL.mdまたはリファレンスファイルのいずれかに存在し、両方には存在しないようにしてください。詳細情報は、それがスキルの真に核となる部分でない限り、リファレンスファイルを優先してください。これにより、SKILL.mdはスリムに保たれ、コンテキストウィンドウを占有せずに情報を見つけられるようになります。真に核となる手続き上の指示とワークフローガイダンスのみをSKILL.mdに保持し、詳細な参考資料、スキーマ、例はリファレンスファイルに移動してください。
アセット (assets/)
コンテキストにロードされることを意図しておらず、Codexが生成する出力内で使用されるファイル。
- 含めるタイミング: スキルが最終出力で使用されるファイルを必要とする場合
- 例: ブランドアセット用の
assets/logo.png、PowerPointテンプレート用のassets/slides.pptx、HTML/Reactボイラープレート用のassets/frontend-template/、タイポグラフィ用のassets/font.ttf - 使用例: テンプレート、画像、アイコン、ボイラープレートコード、フォント、コピーまたは変更されるサンプルドキュメント
- 利点: 出力リソースをドキュメントから分離し、Codexがコンテキストにロードせずにファイルを使用できるようにする
スキルに含めてはいけないもの
スキルには、その機能を直接サポートする必須ファイルのみを含める必要があります。以下のような、場違いなドキュメントや補助ファイルを作成しないでください:
- README.md
- INSTALLATION_GUIDE.md
- QUICK_REFERENCE.md
- CHANGELOG.md
- など
スキルには、AIエージェントが目前のジョブを実行するために必要な情報のみを含める必要があります。作成プロセス、セットアップとテスト手順、ユーザー向けドキュメントなどに関する補助的なコンテキストを含めるべきではありません。追加のドキュメントファイルを作成すると、ただ散らかりと混乱を招くだけです。
段階的開示の設計原則
スキルは3レベルのロードシステムを使用して、コンテキストを効率的に管理します:
- メタデータ (name + description) - 常にコンテキスト内 (~100語)
- SKILL.md 本文 - スキルがトリガーされたとき (<5000語)
- バンドルリソース - Codexが必要に応じて (スクリプトはコンテキストウィンドウに読み込まずに実行できるため、無制限)
段階的開示のパターン
SKILL.md の本文は、コンテキストの肥大化を最小限に抑えるために、必須事項のみに抑え、500行未満に保ってください。この制限に近づいたら、内容を別のファイルに分割してください。内容を他のファイルに分割する場合、SKILL.md からそれらを参照し、いつ読むべきかを明確に説明することが非常に重要です。これにより、スキルの読み手がそれらの存在と使用タイミングを確実に認識できます。
重要な原則: スキルが複数のバリエーション、フレームワーク、またはオプションをサポートする場合、コアワークフローと選択ガイダンスのみを SKILL.md に保持してください。バリアント固有の詳細（パターン、例、設定）は、個別のリファレンスファイルに移動してください。
パターン 1: リファレンス付きの高レベルガイド
# PDF 処理
## クイックスタート
pdfplumberでテキストを抽出:
[コード例]
## 高度な機能
- **フォーム入力**: 完全なガイドは [FORMS.md](https://raw.githubusercontent.com/openai/codex/main/FORMS.md) を参照
- **APIリファレンス**: 全メソッドは [REFERENCE.md](https://raw.githubusercontent.com/openai/codex/main/REFERENCE.md) を参照
- **例**: 一般的なパターンは [EXAMPLES.md](https://raw.githubusercontent.com/openai/codex/main/EXAMPLES.md) を参照
Codexは、必要になったときにのみ FORMS.md、REFERENCE.md、または EXAMPLES.md をロードします。
パターン 2: ドメイン別の整理
複数のドメインを持つスキルの場合、無関係なコンテキストのロードを避けるために、ドメインごとにコンテンツを整理してください:
bigquery-skill/
├── SKILL.md (概要とナビゲーション)
└── reference/
├── finance.md (収益、請求メトリクス)
├── sales.md (商談、パイプライン)
├── product.md (API使用状況、機能)
└── marketing.md (キャンペーン、アトリビューション)
ユーザーが売上メトリクスについて尋ねた場合、Codexは sales.md のみを読み取ります。
同様に、複数のフレームワークやバリアントをサポートするスキルの場合は、バリアントごとに整理してください:
cloud-deploy/
├── SKILL.md (ワークフロー + プロバイダー選択)
└── references/
├── aws.md (AWS デプロイパターン)
├── gcp.md (GCP デプロイパターン)
└── azure.md (Azure デプロイパターン)
ユーザーがAWSを選択した場合、Codexは aws.md のみを読み取ります。
パターン 3: 条件付き詳細
基本コンテンツを表示し、高度なコンテンツへのリンクを提供:
# DOCX 処理
## ドキュメントの作成
新しいドキュメントには docx-js を使用します。[DOCX-JS.md](https://raw.githubusercontent.com/openai/codex/main/DOCX-JS.md) を参照。
## ドキュメントの編集
簡単な編集の場合は、XMLを直接変更します。
**変更履歴:** [REDLINING.md](https://raw.githubusercontent.com/openai/codex/main/REDLINING.md) を参照
**OOXMLの詳細:** [OOXML.md](https://raw.githubusercontent.com/openai/codex/main/OOXML.md) を参照
Codexは、ユーザーがそれらの機能を必要とした場合にのみ REDLINING.md または OOXML.md を読み取ります。
重要なガイドライン:
- 深くネストされた参照を避ける - 参照は
SKILL.mdから1レベルの深さに保ってください。すべての参照ファイルはSKILL.mdから直接リンクされる必要があります。 - 長いリファレンスファイルを構造化する - 100行を超えるファイルの場合、先頭に目次を含めて、Codexがプレビュー時に全体の範囲を把握できるようにしてください。
スキル作成プロセス
スキル作成には以下の手順が含まれます:
- 具体的な例を用いてスキルを理解する
- 再利用可能なスキルコンテンツを計画する (スクリプト、リファレンス、アセット)
- スキルを初期化する (
init_skill.pyを実行) - スキルを編集する (リソースを実装し
SKILL.mdを記述) - スキルを検証する (
quick_validate.pyを実行) - 実際の使用状況に基づいて反復し、複雑なスキルはフォワードテストする。
これらの手順を順に実行し、明らかに該当しない理由がある場合のみスキップしてください。
スキルの命名
- 小文字、数字、ハイフンのみを使用し、ユーザーが指定したタイトルはハイフンケースに正規化してください (例: "Plan Mode" ->
plan-mode)。 - 名前を生成する際は、64文字未満 (文字、数字、ハイフン) の名前を生成してください。
- アクションを説明する、短く動詞で始まるフレーズを優先してください。
- 明確性やトリガーが向上する場合は、ツールで名前空間を修飾してください (例:
gh-address-comments、linear-address-issue)。 - スキルフォルダの名前はスキル名と正確に一致させてください。
ステップ 1: 具体的な例を用いてスキルを理解する
スキルの使用パターンがすでに明確に理解されている場合にのみ、このステップをスキップしてください。既存のスキルを扱う場合でも、このステップは価値があります。
効果的なスキルを作成するには、スキルがどのように使用されるかについての具体的な例を明確に理解してください。この理解は、ユーザーからの直接の例、またはユーザーのフィードバックで検証された生成例のいずれかから得られます。
例えば、画像編集スキルを構築する場合、関連する質問は次のとおりです:
- "画像エディタースキルはどのような機能をサポートすべきですか？編集、回転、他に何か？"
- "このスキルがどのように使用されるかの例をいくつか教えていただけますか？"
- 「ユーザーが 'この画像の赤目を除去して' や 'この画像を回転して' といったことを尋ねるのが想像できます。他にこのスキルが使用される方法はありますか？」
- "このスキルをトリガーするために、ユーザーは何を言うでしょうか？"
- "このスキルはどこに作成すべきですか？特にご希望がなければ、Codexが自動的に発見できるように
$CODEX_HOME/skills(またはCODEX_HOMEが設定されていない場合は~/.codex/skills) に配置します。"
ユーザーを圧倒しないように、1つのメッセージで多くの質問をするのは避けてください。最も重要な質問から始め、必要に応じてフォローアップすることで、効果を高めてください。
スキルがサポートすべき機能について明確な感覚が得られたら、このステップを終了します。
ステップ 2: 再利用可能なスキルコンテンツの計画
具体的な例を効果的なスキルに変換するには、各例を以下の方法で分析します:
- 例をゼロから実行する方法を検討する
- これらのワークフローを繰り返し実行する際に役立つスクリプト、リファレンス、アセットを特定する
例: 「このPDFを回転して」のようなクエリを処理するための pdf-editor スキルを構築する場合、分析は次のようになります:
- PDFの回転には毎回同じコードを書き直す必要がある
scripts/rotate_pdf.pyスクリプトをスキルに保存すると便利
例: 「Todoアプリを作って」や「ダッシュボードを作って…
…