スキルクリエーター
このスキルは、効果的なスキルを作成するためのガイダンスを提供します。
スキルについて
スキルは、Codexの機能を専門知識、ワークフロー、ツールで拡張するモジュール式の自己完結型パッケージです。スキルは特定のドメインやタスクのための「オンボーディングガイド」として機能し、Codexを汎用エージェントから、モデル単体では完全には持ち得ない手続き的知識を備えた専門エージェントへと変革します。
スキルが提供するもの
- 専門ワークフロー - 特定ドメイン向けの複数ステップ手順
- ツール統合 - 特定のファイル形式やAPIを扱うための指示
- ドメイン専門知識 - 企業固有の知識、スキーマ、ビジネスロジック
- バンドルリソース - 複雑で反復的なタスクのためのスクリプト、リファレンス、アセット
基本原則
簡潔さが重要
コンテキストウィンドウは公共財です。スキルは、システムプロンプト、会話履歴、他のスキルのメタデータ、実際のユーザーリクエストなど、Codexが必要とするすべてのものとコンテキストウィンドウを共有します。
デフォルトの前提：Codexはすでに非常に賢い。 まだCodexが持っていないコンテキストのみを追加してください。情報ごとに「本当にCodexはこの説明を必要としているのか？」「この段落はそのトークンコストに見合うか？」と問いかけてください。
冗長な説明よりも簡潔な具体例を優先してください。
適切な自由度を設定する
タスクの脆弱性と変動性に合わせて具体性のレベルを調整します：
高自由度（テキストベースの指示）：複数のアプローチが有効な場合、決定がコンテキストに依存する場合、またはヒューリスティックがアプローチを導く場合に使用します。
中程度の自由度（疑似コードまたはパラメータ付きスクリプト）：推奨パターンが存在する場合、多少のバリエーションが許容される場合、または設定が動作に影響する場合に使用します。
低自由度（特定のスクリプト、少数のパラメータ）：操作が脆弱でエラーが発生しやすい場合、一貫性が重要な場合、または特定のシーケンスに従う必要がある場合に使用します。
Codexが道を探索していると考えてください：崖のある狭い橋には特定のガードレール（低自由度）が必要ですが、開けた野原は多くのルート（高自由度）を許可します。
スキルの構造
すべてのスキルは、必須のSKILL.mdファイルとオプションのバンドルリソースで構成されます：
skill-name/
├── SKILL.md (必須)
│ ├── YAML frontmatter メタデータ (必須)
│ │ ├── name: (必須)
│ │ └── description: (必須)
│ └── Markdown 指示 (必須)
└── バンドルリソース (オプション)
├── scripts/ - 実行可能コード (Python/Bash など)
├── references/ - 必要に応じてコンテキストに読み込むことを目的としたドキュメント
└── assets/ - 出力で使用されるファイル (テンプレート、アイコン、フォントなど)
SKILL.md (必須)
すべてのSKILL.mdは以下で構成されます：
- Frontmatter (YAML):
nameフィールドとdescriptionフィールドを含みます。これらはCodexがスキルをいつ使用するかを判断するために読み取る唯一のフィールドであるため、スキルが何であるか、いつ使用されるべきかを明確かつ包括的に説明することが非常に重要です。 - 本文 (Markdown): スキルを使用するための指示とガイダンス。スキルがトリガーされた後にのみロードされます（ロードされる場合）。
バンドルリソース (オプション)
スクリプト (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を記述）
- スキルをパッケージ化する（package_skill.py を実行）
- 実際の使用状況に基づいて反復する
これらの手順を順番に実行し、適用できない明確な理由がある場合のみスキップしてください。
スキルの命名
- 小文字、数字、ハイフンのみを使用し、ユーザーが指定したタイトルをハイフンケースに正規化します（例：「Plan Mode」->
plan-mode）。 - 名前を生成する場合は、64文字未満（文字、数字、ハイフン）の名前を生成します。
- 動作を説明する短い動詞で始まるフレーズを優先します。
- 明確さやトリガーの改善に役立つ場合は、ツールで名前空間を指定します（例：
gh-address-comments、linear-address-issue）。 - スキルフォルダーの名前はスキル名と正確に一致させてください。
ステップ1: 具体的な例でスキルを理解する
このステップは、スキルの使用パターンがすでに明確に理解されている場合にのみスキップしてください。既存のスキルで作業する場合でも価値があります。
効果的なスキルを作成するには、スキルがどのように使用されるかの具体的な例を明確に理解します。この理解は、ユーザーからの直接の例、またはユーザーフィードバックで検証された生成された例のいずれかから得られます。
例えば、画像エディタースキルを構築する場合、関連する質問は次のとおりです：
- 「画像エディタースキルはどのような機能をサポートすべきですか？編集、回転、他には？」
- 「このスキルがどのように使用されるか、いくつか例を挙げていただけますか？」
- 「ユーザーが『この画像の赤目を除去して』や『この画像を回転して』などと依頼する場面が想像できます。他にこのスキルが使用される方法はありますか？」
- 「このスキルをトリガーするためにユーザーは何と言うと思いますか？」
ユーザーを圧倒しないために、1つのメッセージで多くの質問をすることは避けてください。最も重要な質問から始め、必要に応じてフォローアップすることで効果が向上します。
スキルがサポートすべき機能の明確な感覚が得られたら、このステップを終了します。
ステップ2: 再利用可能なスキルコンテンツの計画
具体的な例を効果的なスキルに変えるには、各例を次のように分析します：
- その例をゼロから実行する方法を検討する
- これらのワークフローを繰り返し実行する際に役立つスクリプト、リファレンス、アセットを特定する
例：「このPDFを回転して」のようなクエリを処理する pdf-editor スキルを構築する場合、分析は次のようになります：
- PDFの回転には毎回同じコードを書き直す必要がある
- スキルに保存する
scripts/rotate_pdf.pyスクリプトが役立つ
例：「Todoアプリを作って」や「歩数を追跡するダッシュボードを作って」のようなクエリ用の frontend-webapp-builder スキルを設計する場合、分析は次のようになります：
- フロントエンドWebアプリを作成するには、毎回同じHTML/Reactボイラープレートが必要
- スキルに保存する、ボイラープレートのHTML/Reactプロジェクトファイルを含む
assets/hello-world/テンプレートが役立つ
例：「今日ログインしたユーザーは何人ですか？」のようなクエリを処理する big-query スキルを構築する場合、分析は次のようになります：
- BigQueryへのクエリには、毎回テーブルスキーマとリレーションシップを再発見する必要がある
- スキルに保存するテーブルスキーマを文書化した
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テンプレートを生成します
- オプションで
--resourcesに基づいてリソースディレクトリを作成します - オプションで
--examplesが設定されている場合にサンプルファイルを追加します
初期化後、SKILL.mdをカスタマイズし、必要に応じてリソースを追加します。--examples を使用した場合は、プレースホルダーファイルを置き換えるか削除してください。
ステップ4: スキルの編集
（新しく生成された、または既存の）スキルを編集するときは、スキルが別のインスタンスのCodex向けに作成されていることを覚えておいてください。
...
[切り詰められました]