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)
└── 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）：スキルの使用方法に関する指示とガイダンスです。スキルが呼び出された後にのみ読み込まれます（呼び出されない場合は読み込まれません）。

同梱リソース（任意）

スクリプト（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 が必要と判断した場合にのみ読み込めます
• ベストプラクティス：ファイルが大きい場合（1 万語超）は、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 の本文 - スキルが適用される場合に読み込まれます（5,000 語未満）
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：ドメイン別の構成

複数のドメインに対応する Skills では、関係のないコンテキストを読み込まないよう、内容をドメイン別に整理します。

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. スキルをパッケージ化する（package_skill.py を実行する）
6. 実際の使用状況に基づいて反復する

明確な理由があり、該当しない場合にのみ手順を省略し、これらの手順を順番に実行してください。

ステップ 1：具体例を通じてスキルを理解する

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

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

たとえば、画像編集スキルを作成する場合、次のような質問が考えられます。

• 「画像編集スキルでは、どのような機能に対応すべきでしょうか？編集、回転、それ以外にもありますか？」
• 「このスキルの使用例をいくつか挙げてもらえますか？」
• 「『この画像の赤目を除去して』や『この画像を回転して』といった依頼が考えられます。他にも、このスキルがどのように使われると思いますか？」
• 「どのような依頼があれば、このスキルを使うべきでしょうか？」

ユーザーに負担をかけすぎないよう、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 スクリプトを実行してください。このスクリプトは、スキルに必要なものがすべて含まれる新しいスキルのテンプレートディレクトリを簡単に生成するため、スキル作成のプロセスをより効率的で確実なものにします。

使用方法：

scripts/init_skill.py <skill-name> --path <output-directory>

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

• 指定したパスにスキルディレクトリを作成します
• 適切なフロントマターと TODO プレースホルダーを含む SKILL.md テンプレートを生成します
• リソース用のディレクトリ scripts/、references/、assets/ の例を作成します
• 各ディレクトリに、カスタマイズまたは削除できるサンプルファイルを追加します

初期化後、必要に応じて生成された SKILL.md とサンプルファイルをカスタマイズまたは削除してください。

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

新しく生成したスキルでも既存のスキルでも、編集する際は、このスキルを別の Codex インスタンスが使用することを念頭に置いてください。Codex にとって有益で、すぐには気づきにくい情報を含めます。ほかの Codex インスタンスがタスクをより効果的に実行するうえで役立つ、手順に関する知識、分野固有の詳細、再利用可能なアセットを検討してください。

実績のある設計パターンを学ぶ

スキルのニーズに応じて、次の便利なガイドを参照してください。

• 複数ステップのプロセス：順次ワークフローと条件分岐については、references/workflows.md を参照してください
• 特定の出力形式や品質基準：テンプレートと例のパターンについては、references/output-patterns.md を参照してください

これらのファイルには、効果的なスキル設計のための確立されたベストプラクティスが記載されています。

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

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

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

スキルに不要なサンプルファイルやディレクトリは削除してください。初期化スクリプトは構成を示すため、scripts/、references/、assets/ にサンプルファイルを作成しますが、ほとんどのスキルではすべてが必要になるわけではありません。

SKILL.md を更新する

記述ガイドライン： 常に命令形または不定詞形を使用してください。

フロントマター

name と description を含む YAML フロントマターを記述してください。

• name：スキル名
• description：スキルの主要なトリガーとなる項目で、Codex がスキルを使用するタイミングを理解するのに役立ちます。
  • スキルが行うことと、使用する具体的なトリガーや状況の両方を含めてください。
  • 「使用するタイミング」に関する情報はすべてここに含めてください。本文には含めないでください。本文はトリガーされた後に読み込まれるため、本文に「このスキルを使用するタイミング」セクションを設けても Codex の役には立ちません。
  • docx スキルの説明例：「変更履歴、コメント、書式の保持、テキスト抽出に対応した、包括的なドキュメントの作成、編集、分析。Codex が業務用ドキュメント（.docx ファイル）を扱う必要がある場合に使用します。例：（1）新しいドキュメントの作成、（2）コンテンツの変更または編集、（3）変更履歴の操作、（4）コメントの追加、その他のドキュメント関連タスク」

YAML フロントマターには、ほかのフィールドを含めないでください。

本文

スキルと同梱リソースの使用方法を記述してください。

ステップ 5：スキルをパッケージ化する

スキルの開発が完了したら、ユーザーと共有するため、配布可能な .skill ファイルにパッケージ化する必要があります。パッケージ化プロセスでは、すべての要件を満たしていることを確認するため、まずスキルが自動的に検証されます。

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

出力ディレクトリの指定（任意）：

scripts/package_skill.py <path/to/skill-folder> ./dist

パッケージ化スクリプトは、次の処理を行います。

1. 検証：次の項目を自動的に確認します。

   • YAML フロントマターの形式と必須フィールド
   • スキルの命名規則とディレクトリ構成
   • 説明の完全性と品質
   • ファイルの整理とリソースへの参照

2. パッケージ化：検証に合格した場合、スキル名にちなんだ名前（例：my-skill.skill）の .skill ファイルを作成し、すべてのファイルを含め、配布に適したディレクトリ構成を維持します。.skill ファイルは、拡張子が .skill の ZIP ファイルです。

検証に失敗した場合、スクリプトはエラーを報告し、パッケージを作成せずに終了します。検証エラーを修正して、パッケージ化コマンドを再度実行してください。

ステップ 6：反復する

スキルをテストした後、ユーザーから改善を求められることがあります。多くの場合、スキルを使用した直後に、動作をよく把握した状態で依頼されます。

反復ワークフロー：

1. 実際のタスクでスキルを使用する
2. 問題点や非効率な部分を見つける
3. SKILL.md または同梱リソースの更新が必要な箇所を特定する
4. 変更を実装して、再度テストする