skill-creator

スキル作成

無関係な作業を制約することなく、Codex に有用で見落とされがちなガイダンスを提供するスキルを作成します。

基本原則

Codex はすでに十分な能力を備えていると想定します。 判断を変えたり、作業の質を高めたりする情報だけを含めます。一般的な助言、繰り返しの指示、推測に基づく例外ケース、タスクを実質的に明確にしない例は削除します。

ユーザーの意図と範囲を維持します。 スキルは依頼されたタスクを支援するものであり、ユーザーが選んだ製品に取って代わったり、作業範囲を広げたり、無関係な設定を変更したり、追加の外部操作が許可されていると思わせたりしてはいけません。特定の例、過去の失敗、個人的な好みを普遍的な要件に変えてはいけません。

タスクの完了に対する承認によって、その範囲や実行権限が拡大するわけではありません。再試行や外部状態を変更するワークフローでは、リスクに見合った停止条件を定義します。

リスクに応じて具体性を調整します。 複数の方法が妥当な場合は、モデルが適切な方法を選べる余地を残します。正確性、安全性、権限、または実際に壊れやすいワークフローで必要な場合に限り、詳細な手順、決定的なスクリプト、または絶対的な表現を使います。

自由度の高い作業では、成果と関連する判断基準を説明します。望ましい進め方があるワークフローでは、有用な例や設定可能なスクリプトを提示します。手順から外れると具体的な問題が生じる操作に限り、固定の手順や厳密なパラメーターを指定します。見落とされがちな運用上の不変条件を保ち、実際の要件と任意の推奨事項またはローカルの慣例を区別し、別の場所ですでに適用されているポリシーを繰り返さないようにします。

情報の探索を簡潔かつ的確にします。 スキル名と説明は、スキルが読み込まれる前に参照されます。実際の機能と適用される場面を説明し、誤った振り分けを防ぐ場合に限って対象外の条件を加えます。機能の網羅的な一覧や、無関係な依頼まで引きつける包括的な記述は避けます。

スキルは自己完結させます。別のスキルやツールを参照するのは、依頼されたワークフローで本当に必要で、対象環境で利用できる場合に限ります。専門的なレビュー、強化、監査のワークフローは、通常の作業が同じ分野に関わるというだけでは適用せず、依頼された場合、または本当に必要な場合に適用します。

詳細は段階的に提示します。 共通の目的、必須の制約、有用な振り分け情報は SKILL.md に記載します。詳細なモード別ガイダンス、スキーマ、例、手順は補助リファレンスに記載し、現在のタスクに関係するものだけを読み込みます。シンプルで自己完結したスキルに、ルーターや追加ファイルは必要ありません。

スキルの構成

すべてのスキルは、必須の SKILL.md ファイルと、そのワークフローで実際に必要となる任意のリソースを含むフォルダーです。

skill-name/
|-- SKILL.md                 Required skill instructions
|   |-- YAML frontmatter     Required name and description
|   `-- Markdown body        Instructions loaded when the skill is used
|-- agents/                  Optional UI metadata and invocation policy
|   `-- openai.yaml
|-- scripts/                 Optional executable helpers
|-- references/              Optional documentation loaded as needed
`-- assets/                  Optional files used in generated output

実際のタスクに合った構成を選びます。短く自己完結したスキルもあれば、複数の作業モードへの振り分けや、複雑な処理をスクリプトに委ねるスキルもあります。明確な用途がない限り、ディレクトリ、プレースホルダー、例、補足ドキュメントは作成しないでください。

SKILL.md

YAML フロントマターではスキルを特定し、スキルを検討するタイミングを決定します。必須の name と description を含め、既存の metadata など、サポートされている任意のフィールドは適切に保持してください。

Markdown の本文は、スキルが使用されるときにのみ読み込まれます。目的、不可欠なワークフロー、実際の制約、有用なリンクを記載してください。特定のモードでのみ必要な詳細な手順や例は、関連する場合に補足リファレンスに記載してください。

スキル情報は次の 3 段階で開示されます。

1. 名前と説明： スキルの選択中に利用できるため、簡潔で識別しやすい内容にします。
2. SKILL.md 本文： スキルが適用されると読み込まれるため、そのタスクに関係する指示に絞ります。
3. 補足リソース： 現在のタスクで実際に必要な場合にのみ、読み込みまたは実行します。

重要な制約を保ちつつ、エントリーポイントはタスクに必要な範囲でできるだけ短くしてください。大きな上限は目標ではありません。明瞭さやコンテキストの使いやすさが向上するなら、ファイルが扱いにくくなるのを待たずに、条件付きの詳細をリファレンスに移してください。

Scripts

同じロジックを何度も書き直すことになる場合や、決定的な実行によって信頼性が大幅に向上する場合は、実行可能なコードに scripts/ を使用してください。

• 例： 同じコードを毎回作り直す必要がある PDF 操作には、scripts/rotate_pdf.py を使用します。
• 適した用途： 変換の繰り返し、信頼性の高い API 操作、データ処理、その他の具体的な自動化。
• 検証： 新規作成または変更したスクリプトを実行し、動作を検証してください。通常、スクリプトは実装全体をコンテキストに読み込まずに実行できますが、パッチ適用や変更への対応時にはエージェントが内容を確認する必要がある場合があります。

References

特定の状況でのみ必要なドキュメントには references/ を使用してください。

• 例： データベースのテーブルには references/schema.md、ドメインルールには references/policies.md、API には references/api_docs.md、異なる成果物向けの執筆ガイドには個別のファイルを使用します。
• 適した用途： スキーマ、API ドキュメント、社内ポリシー、形式固有の手順、詳細なワークフロー、充実した例。
• 参照方法： 各リファレンスへのリンクを SKILL.md または別の関連リソースに記載し、いつ読むべきかを説明してください。エントリーポイントとリファレンスで情報を重複させず、1 か所にまとめてください。

リファレンスには、エージェントの判断に影響する、保守対象のタスク固有情報だけを記載してください。既存のマニュアルの複製、網羅的なカタログ、信頼できる情報源から入手できる一般的なチュートリアルは避けてください。既存のリソースを削除する前に、その参照元と目的を確認してください。

大規模なリファレンスでは、必要な情報を見つけやすくなる場合に、有用な検索語や簡潔な目次を記載してください。

Assets

生成物に含めるファイルには 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 のガイドは読み込まないでください。同じ方法で、ビジネス領域、成果物の種類、その他の実質的に異なる運用モードを分けることもできます。

短いスキルでは、高度な操作で必要になったときだけ詳細に振り分ける方法もあります。

## Documents

Handle ordinary edits directly.

- For tracked changes, read [references/redlining.md](references/redlining.md).
- For document internals, read [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: Create or edit Word documents when formatting, tracked changes, or comments require document-specific handling.

詳細なワークフロー、ツールの選択、例、動作モードは、すべて説明欄に列挙するのではなく、本文または関連するリファレンスに記載してください。適切な場合は、既存の metadata など、サポートされている任意のフロントマターを維持してください。

別の Codex インスタンスがタスクを適切に実行するために必要な手順だけを書いてください。望ましい結果、明白でない背景情報、実際の制約、関連するリファレンスやツールを明記してください。ユーザーが明示した選択と既存の承認境界を維持してください。タスクで必要とされていないのに、固定の構成、手順、またはステップ数を定めないでください。

検証と反復

完成したスキルを次のコマンドで検証します。

scripts/quick_validate.py <path/to/skill-folder>

バリデーターで確認できるのは、フロントマター、命名規則、未完了のひな形プレースホルダーです。スキルが適切な判断を行うことまでは保証しません。また、説明が他と区別できる内容になっているか、指示がユーザーの意図を保っているか、参照先を見つけやすいか、追加したスクリプトが実際に動作するかも確認してください。

テストが必要な場合は、観察可能な動作または有意義な不変条件を検証します。生成された文言、見出し、正規表現パターンに一致するかどうかだけを確認するテストは避けてください。

実際の使用や実証された不具合に基づいてスキルを改善します。観察した例すべてに当てはまる汎用ルールを積み重ねるのではなく、範囲を絞った修正を優先してください。

独立した事前テスト

スキルが十分に複雑またはリスクが高く、現実的な動作検証によって確信を高められる場合は、委任が可能で許可されていることを確認したうえで、独立したサブエージェントによる検証を行います。通常の作成や小規模な編集で、サブエージェントが自動的に必要になるわけではありません。

評価エージェントには、現実的なユーザーリクエスト、スキル、タスクの実行に必要な最小限の生データを渡します。評価に本当に必要な場合を除き、想定される回答、疑わしい不具合、修正案、過去の結論は伝えないでください。

例：

Use $skill-name at /path/to/skill-name to complete this realistic request.

評価の範囲は、許可されたリソースと副作用に限定してください。生成物には隔離された一時作業領域を使い、作業ツリーに混入したり、後続の評価に影響したりしないようにします。評価に追加の権限が必要な場合、本番環境に影響する場合、または相当な時間や費用がかかる場合は、事前に承認を求めてください。実際の結果と生成物を確認し、観察された動作で裏付けられる変更だけを行います。