Skill Creator

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

スキルについて

スキルは、特殊な知識、ワークフロー、ツールを提供することで Codex の機能を拡張する、モジュール化された自己完結型パッケージです。特定のドメインやタスク向けの「オンボーディングガイド」と考えてください。これにより Codex は汎用エージェントから、どのモデルも完全には所有できない手順的知識を備えた専門エージェントへと変わります。

スキルが提供するもの

1. 専門的なワークフロー - 特定のドメイン向けの複数ステップの手順
2. ツール統合 - 特定のファイル形式または API を使用するための指示
3. ドメイン専門知識 - 企業固有の知識、スキーマ、ビジネスロジック
4. バンドルされたリソース - 複雑で反復的なタスク向けのスクリプト、リファレンス、アセット

コア原則

簡潔であることが鍵

コンテキストウィンドウは公共の資産です。スキルは、システムプロンプト、会話履歴、他のスキルのメタデータ、実際のユーザーリクエストなど、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 が必要と判断したときにのみ読み込まれます
• ベストプラクティス：ファイルが大きい場合（>10k ワード）、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 ワード)
3. バンドルリソース - Codex が必要に応じて (スクリプトはコンテキストウィンドウに読み込まずに実行できるため無制限)

段階的情報開示パターン

SKILL.md 本文を必須のみに保ち、コンテキスト肥大化を最小化するために 500 行以下に保ちます。この制限に近づく場合、コンテンツを別ファイルに分割します。コンテンツを他のファイルに分割する場合、スキル読者がそれらが存在すること、およびいつそれらを使用するかを知るようにするために、SKILL.md からそれらを参照し、いつそれらを読むかを明確に説明することが非常に重要です。

重要な原則：スキルが複数のバリエーション、フレームワーク、またはオプションをサポートする場合、SKILL.md にはコアワークフローと選択ガイダンスのみを保持します。バリエーション固有の詳細（パターン、例、構成）を個別のリファレンスファイルに移します。

パターン 1：高レベルガイドとリファレンス

# PDF Processing

## クイックスタート

pdfplumber を使用してテキストを抽出します：
[code example]

## 高度な機能

- **フォーム入力**：完全なガイドについては [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 Processing

## ドキュメントの作成

新しいドキュメントには 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 がプレビュー時にフルスコープを確認できるように、上部に目次を含めます。

スキル作成プロセス

スキル作成には以下のステップが含まれます：

1. 具体的な例でスキルを理解する
2. 再利用可能なスキルコンテンツを計画する (スクリプト、リファレンス、アセット)
3. スキルを初期化する (init_skill.py を実行)
4. スキルを編集する (リソースを実装し SKILL.md を作成)
5. スキルをパッケージ化する (package_skill.py を実行)
6. 実際の使用に基づいて反復する

これらのステップを順番に従い、それらが適用されない明確な理由がある場合のみスキップしてください。

スキルネーミング

• 小文字、数字、ハイフンのみを使用します；ユーザーが提供するタイトルをハイフンケースに正規化します (例：「Plan Mode」 -> plan-mode)。
• 名前を生成する場合、64 文字以下 (文字、数字、ハイフン) の名前を生成します。
• 動作を説明する短い動詞主導のフレーズを優先します。
• 明確性またはトリガーが改善される場合、ツール別にネームスペースします (例：gh-address-comments、linear-address-issue)。
• スキルフォルダーにスキル名と全く同じ名前を付けます。

ステップ 1：具体的な例でスキルを理解する

スキルの使用パターンがすでに明確に理解されている場合、このステップをスキップします。既存のスキルを使用する場合でも価値があります。

効果的なスキルを作成するには、スキルがどのように使用されるかについての具体的な例を明確に理解する必要があります。この理解は、直接のユーザー例または ユーザーフィードバックで検証された生成された例から来る可能性があります。

たとえば、画像エディタスキルを構築する場合、関連する質問は以下を含みます：

• 「image-editor スキルはどのような機能をサポートすべきですか？編集、回転、その他ありますか？」
• 「このスキルがどのように使用されるかのいくつかの例をいただけますか？」
• 「ユーザーが「この画像から赤目を削除する」や「この画像を回転させる」といったことを求めることを想像できます。このスキルが使用されるべき他の方法を想像しますか？」
• 「ユーザーがこのスキルをトリガーすべき何を言いますか？」

ユーザーを圧倒しないために、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> [--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

スクリプトは以下を実行します：

• 指定されたパスでスキルディレクトリを作成する
• 適切な frontmatter と TODO プレースホルダーを使用して SKILL.md テンプレートを生成する
• --resources に基づいてオプションでリソースディレクトリを作成する
• --examples が設定されている場合、オプションでサンプルファイルを追加する

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

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

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

実証済みのデザインパターンを学ぶ

スキルのニーズに基づいて、これらの有用なガイドを参照してください：

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

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

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

実装を開始するには、上で特定した再利用可能なリソースから始めます：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：スキルをパッケージ化する

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

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

オプションの出力ディレクトリ指定：

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

パッケージングスクリプトは以下を実行します：

1. 検証スキルを自動的に実行し、以下を確認します：

   • YAML frontmatter 形式と必須フィールド
   • スキルネーミング規則とディレクトリ構造
   • 説明の完全性と品質
   • ファイル組織とリソースリファレンス

2. パッケージ化検証が成功した場合、スキル (例：my-skill.skill) にちなんで名前が付けられた .skill ファイルを作成し、配布用に適切なディレクトリ構造を保持しながらすべてのファイルを含めます。.skill ファイルは .skill 拡張子を持つ zip ファイルです。

   セキュリティ制限：シンボリックリンクは拒否され、シンボリックリンクが存在する場合、パッケージング は失敗します。

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

ステップ 6：反復する

スキルをテストした後、ユーザーが改善をリクエストする場合があります。多くの場合、これはスキルを使用した直後に発生し、スキルがどのように実行されたかについての新しいコンテキストが得られます。

反復ワークフロー：

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