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](FORMS.md) を参照
- **APIリファレンス**: すべてのメソッドについては [REFERENCE.md](REFERENCE.md) を参照
- **例**: 一般的なパターンについては [EXAMPLES.md](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](DOCX-JS.md) を参照してください。
## ドキュメントの編集
簡単な編集の場合は、XMLを直接変更します。
**変更履歴について**: [REDLINING.md](REDLINING.md) を参照
**OOXMLの詳細について**: [OOXML.md](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アプリを作って」や「歩数を追跡するダッシュボードを作って」などのクエリのための frontend-webapp-builder スキルを設計する場合、分析は次のようになります:
- フロントエンドウェブアプリを作成するには、毎回同じHTML/Reactボイラープレートが必要である
- スキルに保存するための、ボイラープレートのHTML/Reactプロジェクトファイルを含む
assets/hello-world/テンプレートが役立つ
例: 「四半期ごとの収益レポートをBigQueryで実行して」などのクエリを処理するための big-query スキルを構築する場合、分析は次のようになります:
- BigQueryクエリは毎回異なるが、スキーマとパターンは標準化できる
reference/queries/にSQLスニペットとベストプラクティスを含むリファレンスファイルが役立つreference/schemas/に主要テーブルのスキーマドキュメントも有用
ステップ3: スキルの初期化 (init_skill.py を実行)
scripts/init_skill.py を実行してスキルの骨格を作成します。これにより、適切な構造とプレースホルダーを持つ新しいスキルフォルダが生成されます。
python scripts/init_skill.py --name my-new-skill --description "My new skill description"
このスクリプトは以下を作成します:
my-new-skill/SKILL.md(最小限のテンプレート)my-new-skill/agents/openai.yaml(空のテンプレート)- 必要に応じて
scripts/、references/、assets/ディレクトリ
ステップ4: スキルの編集
スキルの骨格ができたら、次の作業を行います:
- リソースの実装: ステップ2で特定したスクリプト、リファレンス、アセットを作成します
- SKILL.mdの記述: プログレッシブディスクロージャの原則に従い、以下の内容を含めます:
- 正確なYAMLフロントマター (
name、description) - 必須の手続き手順とワークフローガイダンス
- リファレンスファイルとその読み取りタイミングへの明確なリンク
- 正確なYAMLフロントマター (
リファレンスファイルが長くなる場合は、セクション1に目次を含めてください。
ステップ5: スキルの検証 (quick_validate.py を実行)
scripts/quick_validate.py を実行して、スキルが正しく構造化されていることを確認します:
python scripts/quick_validate.py --skill-path my-new-skill
このスクリプトは以下をチェックします:
- SKILL.mdが存在し、有効なYAMLフロントマターを持つこと
nameとdescriptionが存在することagents/openai.yamlが存在し有効であること（存在する場合）- バンドルリソースへのリンクが有効であること
- その他の構造的問題
ステップ6: 実際の使用に基づく反復とフォワードテスト
スキルを作成したら、実際の使用状況を監視し、必要に応じて改善します:
- 実際の使用を観察する: スキルがどのようにトリガーされているか、期待どおりに動作しているかを確認します
- ユーザーフィードバックを収集する: スキルの使用感や改善点についてユーザーからフィードバックを求めます
- フォワードテスト: 複雑なスキルの場合は、新しいユースケースやエッジケースでスキルが正しく動作するかどうかを積極的にテストします
- 反復する: フィードバックと観察に基づいてスキルを更新します（リソースの追加、SKILL.mdの改善など）