skill-creator-openai

スキルクリエーター

このスキルでは、効果的なスキルを作成するためのガイダンスを提供します。

スキルについて

スキルは、専門知識、ワークフロー、ツールを提供することでCodexの機能を拡張する、モジュール式で自己完結したフォルダーです。特定の分野やタスク向けの「オンボーディングガイド」と考えてください。手順に関する知識を備えた専門エージェントへと、Codexを汎用エージェントから変化させます。この知識は、どのモデルも完全には備えられません。

スキルが提供するもの

1. 専門的なワークフロー — 特定の分野向けの複数ステップの手順
2. ツール連携 — 特定のファイル形式やAPIを扱うための手順
3. 分野の専門知識 — 企業固有の知識、スキーマ、ビジネスロジック
4. 同梱リソース — 複雑で反復的なタスク向けのスクリプト、リファレンス、アセット

基本原則

簡潔さが重要

コンテキストウィンドウは共有資産です。スキルは、システムプロンプト、会話履歴、他のスキルのメタデータ、実際のユーザーリクエストなど、Codexが必要とするあらゆる情報とコンテキストウィンドウを共有します。

Codexはすでに非常に高い能力を備えていると想定してください。 Codexがすでに知っていることは追加せず、それ以外の情報だけを加えます。情報を一つひとつ吟味してください。「Codexに本当にこの説明が必要だろうか？」「この段落はトークンを消費する価値があるだろうか？」と問いかけます。

冗長な説明より、簡潔な例を優先してください。

適切な自由度を設定する

タスクの壊れやすさと変動性に応じて、具体性の度合いを調整します。

自由度が高い（テキストベースの指示）：複数の方法が有効な場合、判断が状況に左右される場合、またはヒューリスティックに沿って進める場合に使用します。

自由度が中程度（疑似コードまたはパラメーター付きスクリプト）：推奨パターンがあり、ある程度の変化が許容される場合や、設定によって動作が変わる場合に使用します。

自由度が低い（具体的なスクリプト、少数のパラメーター）：操作が壊れやすくエラーが起きやすい場合、一貫性が不可欠な場合、または特定の手順に従う必要がある場合に使用します。

Codexが道筋を探っていると考えてください。崖に挟まれた狭い橋では具体的なガードレールが必要ですが、開けた野原ではさまざまなルートを選べます。

スキルの構成

各スキルには、必須のSKILL.mdファイルと、任意の同梱リソースが含まれます。

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
├── agents/ (recommended)
│   └── openai.yaml - UI metadata for skill lists and chips
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation intended to be loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)

SKILL.md（必須）

すべてのSKILL.mdは、次の要素で構成されます。

• フロントマター（YAML）：nameとdescriptionフィールドを含みます。スキルを使用するタイミングの判断にCodexが使うのはこの2つのフィールドだけなので、スキルの内容と使用場面を明確かつ包括的に記述することが非常に重要です。
• 本文（Markdown）：スキルを使用するための指示とガイダンスです。スキルが起動した後にのみ読み込まれます（起動した場合）。

エージェントのメタデータ（推奨）

• スキル一覧とチップに表示されるメタデータ
• 値を生成する前にreferences/openai_yaml.mdを読み、その説明と制約に従います
• スキルを読んで、ユーザー向けのdisplay_name、short_description、default_promptを作成します
• 値を--interface key=valueとしてscripts/generate_openai_yaml.pyまたはscripts/init_skill.pyに渡し、決定的に生成します
• 更新時は、agents/openai.yamlが引き続きSKILL.mdと一致していることを検証し、古くなっていれば再生成します
• アイコンやブランドカラーなど、その他の任意のインターフェースフィールドは、明示的に指定されている場合にのみ含めます
• フィールドの定義と例についてはreferences/openai_yaml.mdを参照してください

同梱リソース（任意）

スクリプト（scripts/）

決定論的な信頼性が求められるタスクや、同じコードを繰り返し書き直すタスク向けの実行可能なコード（Python/Bashなど）です。

• 含める場合：同じコードを何度も書き直す場合や、決定論的な信頼性が必要な場合
• 例：PDFの回転タスク向けのscripts/rotate_pdf.py
• 利点：トークンを節約でき、動作が決定的で、コンテキストに読み込まずに実行できます
• 注意：Codexがパッチの適用や環境固有の調整のために、スクリプトを読む必要がある場合もあります

References (references/)

Codex の作業や思考の参考となる、必要に応じてコンテキストに読み込むドキュメントや参考資料です。

• 含めるタイミング：作業中に Codex が参照するドキュメントの場合
• 例：財務スキーマの references/finance.md、会社の NDA テンプレートの references/mnda.md、会社のポリシーの references/policies.md、API 仕様の references/api_docs.md
• ユースケース：データベーススキーマ、API ドキュメント、ドメイン知識、会社のポリシー、詳細なワークフローガイド
• メリット：SKILL.md を簡潔に保ち、Codex が必要だと判断した場合にのみ読み込めます
• ベストプラクティス：ファイルが大きい場合（10k 語超）は、SKILL.md に grep の検索パターンを記載してください
• 重複を避ける：情報は SKILL.md または references ファイルのどちらか一方に記載し、両方には記載しないでください。スキルの中核に当たる情報でない限り、詳細情報は references ファイルに記載してください。これにより、コンテキストウィンドウを圧迫せずに情報を見つけやすくしながら、SKILL.md を簡潔に保てます。SKILL.md には必須の手順とワークフローのガイダンスのみを残し、詳細な参考資料、スキーマ、例は references ファイルに移してください。

Assets (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 段階の読み込みシステムを使用します。

1. メタデータ（名前＋説明） - 常にコンテキスト内（約100語）
2. SKILL.md 本文 - スキルが起動したとき（5k 語未満）
3. バンドルされたリソース - Codex が必要に応じて使用（スクリプトはコンテキストウィンドウに読み込まずに実行できるため、制限なし）

段階的な開示のパターン

コンテキストの肥大化を最小限に抑えるため、SKILL.md の本文は必要事項に絞り、500 行未満にしてください。この上限に近づいたら、内容を別ファイルに分割してください。内容を別ファイルに分割する場合は、SKILL.md からそれらのファイルを参照し、いつ読むべきかを明確に説明することが非常に重要です。これにより、スキルを読む人が、それらのファイルの存在と使用するタイミングを把握できます。

重要な原則： スキルが複数のバリエーション、フレームワーク、またはオプションをサポートする場合、SKILL.md には基本的なワークフローと選択のガイダンスのみを記載してください。バリエーション固有の詳細（パターン、例、設定）は、別のリファレンスファイルに移してください。

パターン 1：リファレンス付きの概要ガイド

# PDF Processing

## Quick start

Extract text with pdfplumber:
[code example]

## Advanced features

- **Form filling**: See [FORMS.md](FORMS.md) for complete guide
- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns

Codex は必要な場合にのみ FORMS.md、REFERENCE.md、または EXAMPLES.md を読み込みます。

パターン 2：ドメイン固有の構成

複数のドメインを持つスキルでは、関係のないコンテキストを読み込まないように、ドメインごとに内容を整理します。

bigquery-skill/
├── SKILL.md (overview and navigation)
└── reference/
    ├── finance.md (revenue, billing metrics)
    ├── sales.md (opportunities, pipeline)
    ├── product.md (API usage, features)
    └── marketing.md (campaigns, attribution)

ユーザーが営業指標について尋ねた場合、Codex は sales.md のみを読み込みます。

同様に、複数のフレームワークやバリエーションをサポートするスキルでは、バリエーションごとに整理します。

cloud-deploy/
├── SKILL.md (workflow + provider selection)
└── references/
    ├── aws.md (AWS deployment patterns)
    ├── gcp.md (GCP deployment patterns)
    └── azure.md (Azure deployment patterns)

ユーザーが AWS を選択した場合、Codex は aws.md のみを読み込みます。

パターン 3：条件付きの詳細

基本的な内容を示し、高度な内容にリンクします。

# DOCX Processing

## Creating documents

Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).

## Editing documents

For simple edits, modify the XML directly.

**For tracked changes**: See [REDLINING.md](REDLINING.md)
**For OOXML details**: See [OOXML.md](OOXML.md)

Codex は、ユーザーがこれらの機能を必要とする場合にのみ REDLINING.md または OOXML.md を読み込みます。

重要なガイドライン：

• 参照を深くネストしないでください - 参照は SKILL.md から 1 階層に保ちます。すべてのリファレンスファイルは、SKILL.md から直接リンクしてください。
• 長いリファレンスファイルを構成してください - 100 行を超えるファイルでは、プレビュー時に Codex が全体の範囲を確認できるよう、先頭に目次を含めてください。

スキル作成プロセス

スキルの作成には、次の手順が含まれます。

1. 具体例を使ってスキルを理解する
2. 再利用可能なスキルの内容（スクリプト、リファレンス、アセット）を計画する
3. スキルを初期化する（init_skill.py を実行）
4. スキルを編集する（リソースを実装し、SKILL.md を作成）
5. スキルを検証する（quick_validate.py を実行）
6. 実際の使用状況に基づいて反復する

適用されない明確な理由がある場合にのみ手順を省略し、それ以外はこの順序で進めてください。

スキルの命名

• 小文字、数字、ハイフンのみを使用し、ユーザーが指定したタイトルはハイフン区切りの小文字に正規化します（例：「Plan Mode」-> plan-mode）。
• 名前を生成するときは、64 文字未満（文字、数字、ハイフン）にしてください。
• 動作を表す、短く動詞で始まるフレーズを優先してください。
• 明確さやトリガーの改善につながる場合は、ツール名を名前空間として付けます（例：gh-address-comments、linear-address-issue）。
• スキルのフォルダー名は、スキル名と完全に一致させてください。

手順 1：具体例を使ってスキルを理解する

スキルの使用パターンがすでに明確に理解できている場合にのみ、この手順を省略してください。既存のスキルを扱う場合でも、この手順は有用です。

効果的なスキルを作成するには、スキルがどのように使われるか、具体例を通じて明確に理解してください。この理解は、ユーザーから直接提供された例や、生成したうえでユーザーのフィードバックによって検証した例から得られます。

たとえば、画像エディターのスキルを作成する場合、次のような質問が参考になります。

• 「画像エディターのスキルでは、どのような機能をサポートする必要がありますか？編集、回転など、ほかに何かありますか？」
• 「このスキルの使用例をいくつか教えてもらえますか？」
• 「ユーザーが『この画像の赤目を消して』や『この画像を回転して』と頼むことが考えられます。ほかにどのような使い方が考えられますか？」
• 「どのような依頼があれば、このスキルを起動すべきですか？」

ユーザーを圧倒しないよう、1 つのメッセージで質問しすぎないでください。最も重要な質問から始め、効果を高めるために必要に応じて追加で質問してください。

このスキルがサポートすべき機能が明確になったら、この手順を終了します。

ステップ 2：再利用可能なスキルの内容を計画する

具体例を効果的なスキルに変えるには、各例を次のように分析します。

1. 例の内容を一から実行する方法を検討します
2. これらのワークフローを繰り返し実行する際に役立つスクリプト、リファレンス、アセットを特定します

例：「この PDF を回転するのを手伝って」というクエリに対応する pdf-editor スキルを作成する場合、分析から次のことがわかります。

1. PDF を回転するには、毎回同じコードを書き直す必要があります
2. スキルに保存しておく scripts/rotate_pdf.py スクリプトが役立ちます

例：「ToDo アプリを作って」や「歩数を記録するダッシュボードを作って」というクエリに対応する frontend-webapp-builder スキルを設計する場合、分析から次のことがわかります。

1. フロントエンドのウェブアプリを作成するには、毎回同じ HTML／React のひな形が必要です
2. ひな形の HTML／React プロジェクトファイルを含む assets/hello-world/ テンプレートをスキルに保存しておくと役立ちます

「今日ログインしたユーザー数は？」というクエリに対応する big-query スキルを作成する場合、分析から次のことがわかります。

1. BigQuery でクエリを実行するには、毎回テーブルのスキーマと関係を再確認する必要があります
2. テーブルのスキーマを記載した references/schema.md ファイルをスキルに保存しておくと役立ちます

スキルの内容を決めるには、具体例をそれぞれ分析し、含める再利用可能なリソース（スクリプト、リファレンス、アセット）の一覧を作成します。

ステップ 3：スキルを初期化する

ここから、実際にスキルを作成します。

開発するスキルがすでに存在する場合に限り、このステップをスキップしてください。その場合は次のステップに進みます。

新しいスキルを一から作成する場合は、必ず init_skill.py スクリプトを実行してください。このスクリプトを使うと、スキルに必要なものがすべて自動的に含まれた新しいスキルのテンプレートディレクトリが生成されるため、スキルの作成プロセスをより効率的かつ確実に進められます。

使用方法：

scripts/init_skill.py <skill-name> --path <output-directory> [--resources scripts,references,assets] [--examples]

例：

scripts/init_skill.py my-skill --path skills/public
scripts/init_skill.py my-skill --path skills/public --resources scripts,references
scripts/init_skill.py my-skill --path skills/public --resources scripts --examples

このスクリプトは次の処理を行います。

• 指定したパスにスキルディレクトリを作成します
• 適切なフロントマターと TODO のプレースホルダーを含む SKILL.md テンプレートを生成します
• --interface key=value で渡された、エージェントが生成した display_name、short_description、default_prompt を使用して agents/openai.yaml を作成します
• --resources に応じて、任意でリソースディレクトリを作成します
• --examples が指定された場合、任意でサンプルファイルを追加します

初期化したら、必要に応じて SKILL.md をカスタマイズし、リソースを追加してください。--examples を使用した場合は、プレースホルダーファイルを置き換えるか、削除してください。

スキルを読み、display_name、short_description、default_prompt を生成してから、それらを --interface key=value として init_skill.py に渡すか、次のように再生成します。

scripts/generate_openai_yaml.py <path/to/skill-folder> --interface key=value

ユーザーが明示的に指定した場合に限り、その他の任意のインターフェースフィールドを含めてください。フィールドの詳しい説明と例については、references/openai_yaml.md を参照してください。

ステップ 4：スキルを編集する

（新しく生成した、または既存の）スキルを編集する際は、別の Codex インスタンスが使うために作成していることを忘れないでください。Codex にとって有益で、すぐにはわからない情報を含めてください。別の Codex インスタンスがこれらのタスクをより効率的に実行するうえで役立つ、手順に関する知識、ドメイン固有の詳細、再利用可能なアセットを検討してください。

再利用可能なスキルコンテンツから始める

実装を始めるには、上記で特定した再利用可能なリソース、すなわち scripts/、references/、assets/ のファイルから始めます。このステップではユーザーの入力が必要になる場合があることに注意してください。たとえば、brand-guidelines スキルを実装する際には、ユーザーが assets/ に保存するブランドアセットやテンプレート、あるいは references/ に保存するドキュメントを提供する必要があるかもしれません。

追加したスクリプトは、実際に実行してテストし、バグがないこと、および出力が期待どおりであることを確認する必要があります。類似したスクリプトが多数ある場合は、完了までの時間とのバランスを取りながら、それらすべてが動作することに確信を持てるよう、代表的なサンプルのみをテストすれば十分です。

--examples を使用した場合は、スキルに不要なプレースホルダーファイルを削除してください。実際に必要なリソースディレクトリのみを作成します。

SKILL.md を更新する

執筆ガイドライン: 常に命令形/不定詞形を使用してください。

frontmatter

name と description を含む YAML frontmatter を記述します:

• name: スキル名
• description: これはスキルの主要なトリガー機構であり、Codex がスキルをいつ使用すべきかを理解するのに役立ちます。
  • スキルが何を行うかと、いつ使用するかの具体的なトリガー/コンテキストの両方を含めてください。
  • 「いつ使用するか」の情報はすべてここに含めてください。本文には含めないでください。本文はトリガー後にのみ読み込まれるため、本文中の「このスキルをいつ使用するか」というセクションは Codex にとって役に立ちません。
  • docx スキルの description の例: 「変更履歴、コメント、書式の保持、テキスト抽出をサポートする包括的なドキュメントの作成、編集、分析。Codex が以下の目的でプロフェッショナルなドキュメント (.docx ファイル) を扱う必要がある場合に使用します: (1) 新しいドキュメントの作成、(2) コンテンツの変更または編集、(3) 変更履歴の操作、(4) コメントの追加、その他のドキュメントタスク」

YAML frontmatter には他のフィールドを含めないでください。

本文

スキルとそのバンドルされたリソースの使用方法に関する指示を記述します。

ステップ 5: スキルを検証する

スキルの開発が完了したら、スキルフォルダーを検証して基本的な問題を早期に発見します:

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

検証スクリプトは、YAML frontmatter の形式、必須フィールド、および命名規則を確認します。検証が失敗した場合は、報告された問題を修正し、コマンドを再度実行してください。

ステップ 6: 反復する

スキルをテストした後、ユーザーは改善を求めることがあります。多くの場合、これはスキルを使用した直後に、スキルがどのように機能したかについての新鮮なコンテキストを持って行われます。

反復ワークフロー:

1. 実際のタスクでスキルを使用する
2. 困難や非効率に気づく
3. SKILL.md またはバンドルされたリソースをどのように更新すべきかを特定する
4. 変更を実装して再度テストする