スキルクリエイター
Codexに対して、無関係な作業を制限することなく、有用で自明ではないガイダンスを提供するスキルを作成します。
基本原則
Codexはすでに有能であると想定します。 意思決定を変更したり、作業を改善したりする情報のみを含めてください。汎用的なアドバイス、繰り返しの指示、推測によるエッジケース、タスクを実質的に明確にしない例は削除してください。
ユーザーの意図とスコープを維持します。 スキルは要求されたタスクをサポートするものであり、ユーザーが選択した製品を置き換えたり、アサインを拡大したり、無関係な設定を変更したり、追加の外部アクションを暗黙的に許可したりするものではありません。特定の例、過去の失敗、または個人的な好みを普遍的な要件にしないでください。
タスクを完了するための承認は、そのスコープや実行権限を拡大するものではありません。再試行や外部を変更するワークフローについては、リスクに見合った停止条件を定義してください。
特異性をリスクに合わせます。 複数のアプローチが合理的である場合、モデルに適切なアプローチを選択する余地を与えてください。詳細な手順、決定論的なスクリプト、または絶対的な表現は、正確性、安全性、権限、または本当に脆弱なワークフローが必要な場合にのみ使用してください。
オープンエンドな作業には、成果と関連する意思決定基準を記述してください。推奨される形状のワークフローには、有用な例や設定可能なスクリプトを提供してください。固定されたシーケンスと狭いパラメータは、逸脱が具体的な問題を引き起こす操作のために予約してください。自明ではない運用上の不変条件を保持し、実際の要件とオプションの推奨事項やローカルな慣習を区別し、他ですでに実施されているポリシーを再記述しないでください。
発見を安価かつ正確に保ちます。 スキル名と説明は、スキルがロードされる前に利用可能です。実際の機能とそれが適用されるタイミングを説明し、誤ったルーティングを防ぐ場合にのみ除外条件を追加してください。無関係なリクエストを引き寄せる網羅的な機能リストやキャッチオールは避けてください。
スキルは自己完結型に保ち、要求されたワークフローが本当にそれを必要とし、ターゲット環境で利用可能な場合にのみ、別のスキルやツールを参照してください。特別なレビュー、ハードニング、または監査ワークフローは、要求された場合や本当に必要な場合に適用し、通常の作業が同じテーマに触れるという理由だけで適用しないでください。
詳細を段階的に開示します。 共通の目的、必須の制約、有用なルーティング情報を SKILL.md に保持してください。実質的なモード固有のガイダンス、スキーマ、例、手順は、サポートリファレンスに配置し、現在のタスクに関連するリファレンスのみを読み込んでください。シンプルで自己完結型のスキルには、ルーターや追加ファイルは必要ありません。
スキルの構造
すべてのスキルは、必須の SKILL.md ファイルと、実際のワークフローに必要なオプションリソースを含むフォルダです：
skill-name/
|-- SKILL.md 必須のスキル指示
| |-- YAML frontmatter 必須の名前と説明
| `-- Markdown body スキル使用時に読み込まれる指示
|-- agents/ オプションのUIメタデータと呼び出しポリシー
| `-- openai.yaml
|-- scripts/ オプションの実行可能ヘルパー
|-- references/ オプションのドキュメント（必要に応じて読み込まれる）
`-- assets/ オプションの生成出力で使用されるファイル
実際のタスクに合った構造を選択してください。短く自己完結型のスキルもあれば、動作モード間でルーティングしたり、複雑なメカニクスをスクリプトに委譲したりするスキルもあります。明確な用途なしにディレクトリ、プレースホルダー、例、または補助的なドキュメントを作成しないでください。
SKILL.md
YAMLフロントマターはスキルを識別し、いつ考慮されるべきかを決定します。必須の name と description を含め、既存の metadata など、サポートされているオプションフィールドを適切に保持してください。
Markdown本文はスキルが使用された場合にのみ読み込まれます。目的、必須のワークフロー、実際の制約、有用なリンクをそこに配置してください。特定のモードにのみ関連する詳細な手順や例は、サポートリファレンスに配置してください。
スキル情報は3段階で開示されます：
- 名前と説明： スキル選択時に利用可能なので、簡潔で識別しやすいものにしてください。
- SKILL.md本文： スキルが適用される場合に読み込まれるので、そのタスクに関連する指示を保持してください。
- サポートリソース： 現在のタスクが実際にそれらを必要とする場合にのみ読み込むか実行します。
エントリーポイントは、重要な制約を保持しながら、タスクが許す限り短くしてください。大きな上限は目標ではありません。条件付きの詳細は、明瞭性やコンテキスト使用を向上させる場合にリファレンスに移動してください。ファイルが扱いにくくなるのを待つ必要はありません。
スクリプト
同じロジックが繰り返し書き直される場合、または決定論的な実行が信頼性を実質的に向上させる場合に、scripts/ に実行可能コードを使用してください。
- 例： 同じコードを再作成する必要があるPDF操作には
scripts/rotate_pdf.py。 - 有用なケース： 繰り返しの変換、信頼性の高いAPI操作、データ処理、その他の具体的な自動化。
- 検証： 新規または変更されたスクリプトを実行して、その動作を確認してください。スクリプトは、通常、完全な実装をコンテキストに読み込まずに実行できますが、エージェントはパッチや適応時にそれらを検査する必要がある場合があります。
リファレンス
特定のコンテキストでのみ必要なドキュメントには references/ を使用してください。
- 例： データベーステーブルには
references/schema.md、ドメインルールにはreferences/policies.md、APIにはreferences/api_docs.md、または異なるデリバラブルごとに個別のライティングガイド。 - 有用なケース： スキーマ、APIドキュメント、会社のポリシー、フォーマット固有の手順、詳細なワークフロー、実質的な例。
- ルーティング： 各リファレンスを
SKILL.mdまたは別の関連リソースからリンクし、いつ読むべきかを説明してください。情報をエントリーポイントとリファレンス間で重複させるのではなく、1か所に保持してください。
リファレンスは、エージェントの決定を変更する、メンテナンスされたタスク固有の情報に焦点を当ててください。コピーされたマニュアル、網羅的なカタログ、権威あるソースからすでに利用可能な汎用チュートリアルは避けてください。既存のリソースを削除する前に、その呼び出し元と目的を検査してください。
大きなリファレンスについては、必要な資料を見つけやすくするために、有用な検索語や短い目次セクションを含めてください。
アセット
モデルの指示ではなく、生成された出力に含めるファイルには assets/ を使用してください。
- 例：
assets/logo.png、assets/slides.pptx、assets/font.ttf、またはassets/frontend-template/。 - 有用なケース： テンプレート、画像、フォント、アイコン、ボイラープレートプロジェクトなど、結果にコピーまたは適用されるファイル。
- コンテキスト： タスクがそれらの検査を必要としない限り、アセットを指示として読み込まないでください。
UIメタデータと呼び出しポリシー
agents/openai.yaml は、display_name、short_description、default_prompt などのUI向けメタデータと、呼び出しポリシーを提供できます。これらの設定を作成または更新するときは、references/openai_yaml.md を読み、値をスキルと一致させてください。
自動スキル選択はデフォルトで許可されています。ユーザーが明示的に明示専用スキルを要求する場合にのみ、そのデフォルトを変更してください：
policy:
allow_implicit_invocation: false
これにより、スキルがモデルコンテキストに自動的に追加されることなく、$skill-name として明示的に呼び出された場合に利用可能になります。agents/openai.yaml を更新する際は、既存の無関係なUI、ポリシー、依存関係フィールドを保持してください。
イニシャライザはこのファイルを自動的に作成します。新規またはインターフェースのみのメタデータについては、以下で生成します：
scripts/generate_openai_yaml.py <path/to/skill-folder> --interface key=value
ジェネレーターはファイル全体を置き換えます。既存のファイルに policy または dependencies が含まれている場合は、再生成する代わりに、意図したフィールドのみをその場で更新してください。
オプションのインターフェースフィールドは、ユーザーが提供または要求した場合にのみ含めてください。
含めないもの
スキルの作業を直接サポートするファイルのみを含めてください。特定のタスクやパッケージング要件が要求しない限り、README.md、インストールガイド、変更履歴、重複したクイックリファレンス、その他の補助的なドキュメントを追加しないでください。
段階的な開示の実践
複数の実質的なモードを持つスキルの場合、共通のガイダンスとモード選択基準を SKILL.md に保持してください。各サポートリファレンスは、その使用が関連する時点でリンクしてください。デフォルトですべてのリファレンスを読み込んだり、エントリーポイントでリファレンスコンテンツを重複させたり、ルーティングする価値のあるものがないのにルーティングレイヤーを追加したりしないでください。
例えば、デプロイメントスキルはプロバイダー選択を SKILL.md に保持し、各プロバイダーの詳細を別々にすることができます：
cloud-deploy/
|-- SKILL.md
`-- references/
|-- aws.md
|-- gcp.md
`-- azure.md
ユーザーがAWSを選択した場合、references/aws.md のみを読み込み、GCPやAzureのガイドは読み込まないでください。同じパターンで、ビジネスドメイン、デリバラブルタイプ、またはその他の明確に異なる動作モードを分離できます。
短いスキルは、高度な操作が必要な場合にのみ詳細にルーティングすることもできます：
## ドキュメント
通常の編集は直接処理します。
- 変更履歴については [references/redlining.md](references/redlining.md) を参照してください。
- ドキュメント内部については [references/ooxml.md](references/ooxml.md) を参照してください。
これらの例はオプションを示しており、必須の構造ではありません。無関係な資料を読み込まずにスキルを使いやすくする編成を選択してください。
スキルの作成または更新
作業をリクエストに適応させてください。複雑な新しいスキルを作成するには、実際のユースケースの理解、サポートリソースの選択、ファイルの初期化、指示の記述、結果の検証が含まれる場合があります。既存のスキルに対する狭い更新には、焦点を絞った編集と検証のみが必要な場合があります。
欠落している情報が重要であり、合理的に推測できない場合にのみ、質問を明確にしてください。ユーザーが指定した場所を尊重し、そうでない場合は、$CODEX_HOME/skills に、または CODEX_HOME が設定されていない場合は ~/.codex/skills に検出可能なスキルを作成してください。
ユーザーが明示的に明示専用スキルを要求しない限り、自動スキル選択を有効にしたままにしてください。意図された呼び出しモードが本当に不明瞭で、要求されたワークフローにとって重要である場合、ユーザーに通常の自動検出と明示専用呼び出しのどちらを希望するかを尋ねてください。それ以外の場合はデフォルトを保持してください。機密操作や必要な承認から明示専用呼び出しを推測しないでください。スキルを検出可能に保ち、実際の変更の直前に承認を要求してください。ユーザーが変更を求めない限り、既存のスキルの呼び出しポリシーを保持してください。
新しいスキルまたは大幅に改訂されたスキルについては、それが処理すべき実際のリクエストと、どの再利用可能なリソースがそれらのタスクを改善するかを検討してください：
- 繰り返しのPDF変換は、
scripts/rotate_pdf.pyヘルパーを正当化する可能性があります。 - アプリケーション構築ワークフローは、
assets/frontend-template/スターターの恩恵を受ける可能性があります。 - データ分析スキルは、テーブル関係を再発見することを避けるために、
references/schema.mdガイドを必要とする可能性があります。
これらのリソースは、その具体的なメリットが正当化される場合にのみ作成してください。ユーザーがタスクをすでに明確に説明している場合は、追加の例を要求せずに進めてください。
命名
- 小文字、数字、ハイフンを使用してください。
- 名前は64文字未満に保ち、短いアクション指向の名前を推奨します。
- 発見性を向上させる場合は、ツールまたはドメインで名前空間を設定します。
- スキルフォルダの名前はスキル名にしてください。
新しいスキルの初期化
新しいスキルについては、必要なファイルを一貫して作成するのに役立つ場合、バンドルされたイニシャライザを使用してください：
scripts/init_skill.py <skill-name> --path <output-directory> [--resources scripts,references,assets] [--examples]
例：
scripts/init_skill.py my-skill --path "${CODEX_HOME:-$HOME/.codex}/skills"
scripts/init_skill.py my-skill --path "${CODEX_HOME:-$HOME/.codex}/skills" --resources references
スキルが必要とするリソースディレクトリのみをリクエストしてください。具体的なプレースホルダーが役立つ場合にのみ --examples を使用し、完了する前に置き換えるか削除してください。既存のスキルを再度初期化しないでください。
イニシャライザは、スキルディレクトリ、簡潔な SKILL.md スターター、および agents/openai.yaml を作成します。リクエストされた場合にのみ、リソースディレクトリとサンプルファイルを作成します。必要に応じて、生成されたUI値を --interface key=value として渡してください。
指示の記述
フロントマターの description は、スキルの機能とそれが適用されるタイミングを簡潔に説明する必要があります。類似のリクエストがスキルをアクティブにすべきでない場合、意味のある境界を含めてください。
例：
description: 書式設定、変更履歴、またはコメントにドキュメント固有の処理が必要な場合に、Word文書を作成または編集します。
詳細なワークフロー、ツールの選択、例、動作モードは、説明にすべてをリストするのではなく、本文または関連するリファレンスに配置してください。サポートされているオプションのフロントマター（既存の metadata など）を適切に保持してください。
別のCodexインスタンスがタスクを適切に実行するために必要な指示のみを記述してください。望ましい結果、自明ではないコンテキスト、実際の制約、関連するリファレンスやツールを明記してください。ユーザーの明示的な選択と既存の承認境界を保持してください。タスクが必要としない場合、固定された構造、プロセス、またはステップ数を規定しないでください。
検証と反復
以下のコマンドで完了したスキルを検証します：
scripts/quick_validate.py <path/to/skill-folder>
バリデーターは、フロントマター、命名、未完了のスキャフォールドプレースホルダーをチェックします。スキルが適切な決定を下すことを証明するものではありません。また、説明が識別可能であること、指示がユーザーの意図を維持していること、リファレンスが発見可能であること、追加されたスクリプトが実際に機能することを確認してください。
テストが正当化される場合、観察可能な動作または意味のある不変条件を検証してください。生成された文言、見出し、または正規表現パターンに単に一致するテストは避けてください。
実際の使用法や実証された失敗に基づいてスキルを改善してください。すべての失敗を防ごうとする普遍的なルールを蓄積するよりも、狭い修正を推奨します。