skill-creator

スキル作成者

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

スキルについて

スキルは、専門知識、ワークフロー、ツールを提供して 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/）

Codex の処理や思考に役立てるため、必要に応じてコンテキストに読み込むことを想定したドキュメントや参考資料です。

• 含める場合：Codex が作業中に参照するドキュメントが必要な場合
• 例：財務スキーマ用の references/finance.md、会社の NDA テンプレート用の references/mnda.md、会社のポリシー用の references/policies.md、API 仕様用の references/api_docs.md
• 用途：データベーススキーマ、API ドキュメント、ドメイン知識、会社のポリシー、詳細なワークフローガイド
• 利点：SKILL.md を簡潔に保ち、Codex が必要と判断した場合にのみ読み込まれます
• ベストプラクティス：ファイルが大きい（>10k words）場合は、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 段階の読み込みシステムを使用します。

1. メタデータ（名前 + 説明） - 常にコンテキストに含まれます（約 100 語）
2. SKILL.md の本文 - スキルが起動したときに読み込まれます（<5k words）
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：具体例を使ってスキルを理解する

スキルの使用パターンをすでに明確に理解している場合に限り、このステップを省略してください。既存のスキルを扱う場合でも、このステップは有用です。

効果的なスキルを作成するには、そのスキルの具体的な使用例を明確に理解する必要があります。理解の手がかりは、ユーザーから直接提供される例や、生成したうえでユーザーのフィードバックにより検証した例から得られます。

たとえば、画像編集スキルを作成する場合、関連する質問には次のようなものがあります。

• 「画像編集スキルでは、どのような機能に対応する必要がありますか？編集、回転、そのほかにもありますか？」
• 「このスキルの使用例をいくつか挙げてもらえますか？」
• 「『この画像の赤目を修正して』や『この画像を回転して』のような依頼が考えられます。ほかに、このスキルがどのように使われると思いますか？」
• 「どのような依頼があれば、このスキルを起動すべきですか？」
• 「このスキルはどこに作成すればよいですか？特に希望がなければ、Codex が自動的に検出できるよう、$CODEX_HOME/skills（CODEX_HOME が設定されていない場合は ~/.codex/skills）に配置します。」

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

スキルが対応すべき機能について明確になったら、このステップを終了します。

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

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

1. 例のタスクをゼロから実行する方法を検討する
2. こうしたワークフローを繰り返し実行する際に役立つスクリプト、参考資料、アセットを特定する

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

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

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

1. フロントエンドの Web アプリを作成するたびに、同じ定型の HTML／React を書く必要があります
2. 定型の HTML／React プロジェクトファイルを含む assets/hello-world/ テンプレートをスキルに含めておくと役立ちます

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

1. BigQuery でクエリを実行するたびに、テーブルのスキーマや関連性を調べ直す必要があります
2. テーブルのスキーマを記載した references/schema.md ファイルをスキルに含めておくと役立ちます

スキルに含める内容を決めるため、各具体例を分析し、含めるべき再利用可能なリソース（スクリプト、参考資料、アセット）のリストを作成します。

ステップ 3：スキルの初期化

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

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

init_skill.py を実行する前に、スキルの作成場所をユーザーに確認してください。場所が指定されていない場合は、$CODEX_HOME/skills をデフォルトとして使用します。CODEX_HOME が設定されていない場合は、~/.codex/skills に切り替え、スキルが自動検出されるようにします。

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

使い方：

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 scripts,references
scripts/init_skill.py my-skill --path ~/work/skills --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 スキルの説明の例：「変更履歴、コメント、書式の保持、テキスト抽出に対応した、包括的なドキュメントの作成、編集、分析。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. 変更を実施して、再度テストする
5. 妥当かつ適切であれば、前方テストを行う

フォワードテスト

フォワードテストを行うには、コンテキストを最小限にしてスキルに負荷をかけるため、サブエージェントを起動します。 サブエージェントには、スキルのテストを依頼されていることを知らせないでください。ユーザーからタスクを依頼されたエージェントとして扱います。サブエージェントへのプロンプトは、次のような形式にします。 Use $skill-x at /path/to/skill-x to solve problem y 次のような形式にはしないでください。 Review the skill at /path/to/skill-x; pretend a user asks you to...

フォワードテストの判断基準：

• 迷った場合は、フォワードテストを実施します
• フォワードテストによって次のいずれかのリスクが生じると思われる場合は、承認を求めます
  • 長時間かかる
  • ユーザーから追加の承認が必要になる
  • 稼働中の本番システムが変更される

このような場合は、提案するプロンプトをユーザーに提示し、（1）実施するかどうかの判断と、（2）変更案があればその内容を求めます。

フォワードテストを行う際の考慮事項：

• 独立したテストでは、新しいスレッドを使用します
• ユーザーが依頼する場合と同様の形式で、スキルと依頼を渡します
• 結論ではなく、生の成果物を渡します
• 期待する回答や意図する修正内容を見せないようにします
• 各反復後に、元の成果物からコンテキストを再構築します
• サブエージェントの出力、推論、生成された成果物を確認します
• 反復間でエージェントがディスク上の成果物を見つけられないようにし、汚染を防ぐためにサブエージェントの成果物を削除します

サブエージェントに漏えいしたコンテキストを見せた場合にしかフォワードテストが成功しないなら、結果を信頼する前に、スキルまたはフォワードテストの設定を見直してください。