Skill creator

スキルクリエイター

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

スキルについて

スキルは、専門知識、ワークフロー、ツールを提供することで AI エージェントの機能を拡張する、モジュール式で自己完結型のパッケージです。特定のドメインやタスクのための「オンボーディングガイド」と考えてください。スキルは、AI エージェントを汎用エージェントから、どのモデルも完全には持ち得ない手続き的知識を備えた専門エージェントへと変換します。

スキルが提供するもの

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

基本原則

簡潔さが鍵

コンテキストウィンドウは共有資源です。スキルは、AI エージェントが必要とする他のすべてのもの（システムプロンプト、会話履歴、他のスキルのメタデータ、実際のユーザーリクエスト）とコンテキストウィンドウを共有します。

デフォルトの前提：AI エージェントはすでに非常に賢い。 AI エージェントがまだ持っていないコンテキストのみを追加してください。各情報に対して「AI エージェントは本当にこの説明が必要か？」「この段落はトークンコストに見合う価値があるか？」と問いかけてください。

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

適切な自由度を設定する

タスクの脆弱性と変動性に応じて、具体性のレベルを合わせてください：

高い自由度（テキストベースの指示）：複数のアプローチが有効な場合、決定がコンテキストに依存する場合、またはヒューリスティクスがアプローチを導く場合に使用します。

中程度の自由度（擬似コードまたはパラメータ付きスクリプト）：推奨パターンが存在する場合、ある程度の変動が許容される場合、または設定が動作に影響する場合に使用します。

低い自由度（特定のスクリプト、少ないパラメータ）：操作が脆弱でエラーが発生しやすい場合、一貫性が重要な場合、または特定の順序に従う必要がある場合に使用します。

AI エージェントが道を探索していると考えてください：崖のある狭い橋には特定のガードレール（低い自由度）が必要ですが、開けた野原では多くのルートが可能です（高い自由度）。

スキルの構成

すべてのスキルは、必須の SKILL.md ファイルとオプションのバンドルリソースで構成されます：

skill-name/
├── SKILL.md (必須)
│   ├── YAMLフロントマターメタデータ (必須)
│   │   ├── name: (必須)
│   │   └── description: (必須)
│   └── Markdownの指示 (必須)
└── バンドルリソース (オプション)
    ├── scripts/          - 実行可能コード (Python/Bash等)
    ├── references/       - 必要に応じてコンテキストに読み込むドキュメント
    └── assets/           - 出力に使用するファイル (テンプレート、アイコン、フォント等)

SKILL.md (必須)

すべての SKILL.md は以下で構成されます：

• フロントマター (YAML)：nameとdescriptionフィールドを含みます。これらは AI エージェントがスキルをいつ使用するかを判断するために読み取る唯一のフィールドです。したがって、スキルが何であるか、いつ使用すべきかを明確かつ包括的に記述することが非常に重要です。
• 本文 (Markdown)：スキルの使用に関する指示とガイダンス。スキルがトリガーされた後にのみ読み込まれます（トリガーされた場合のみ）。

バンドルリソース (オプション)

スクリプト (scripts/)

決定論的な信頼性が必要なタスクや繰り返し書き直されるタスクのための実行可能コード（Python/Bash 等）。

• 含めるべき場合：同じコードが繰り返し書き直される場合、または決定論的な信頼性が必要な場合
• 例：PDF 回転タスク用のscripts/rotate_pdf.py
• 利点：トークン効率が良い、決定論的、コンテキストに読み込まずに実行可能
• 注意：スクリプトは、パッチや環境固有の調整のために AI エージェントが読み取る必要がある場合があります

リファレンス (references/)

AI エージェントのプロセスと思考を導くために、必要に応じてコンテキストに読み込むことを目的としたドキュメントとリファレンス資料。

• 含めるべき場合：AI エージェントが作業中に参照すべきドキュメントがある場合
• 例：財務スキーマ用のreferences/finance.md、会社の NDA テンプレート用のreferences/mnda.md、会社のポリシー用のreferences/policies.md、API 仕様用のreferences/api_docs.md
• ユースケース：データベーススキーマ、API ドキュメント、ドメイン知識、会社のポリシー、詳細なワークフローガイド
• 利点：SKILL.md をスリムに保ち、AI エージェントが必要と判断した場合にのみ読み込まれます
• ベストプラクティス：ファイルが大きい場合（10k 語以上）、SKILL.md に grep 検索パターンを含めてください
• 重複を避ける：情報は SKILL.md またはリファレンスファイルのいずれかに存在すべきで、両方には存在しないでください。本当にスキルの核心でない限り、詳細情報はリファレンスファイルを優先してください。これにより SKILL.md をスリムに保ちながら、コンテキストウィンドウを占有せずに情報を発見可能にできます。SKILL.md には本質的な手続き的指示とワークフローガイダンスのみを保持し、詳細なリファレンス資料、スキーマ、例はリファレンスファイルに移動してください。

アセット (assets/)

コンテキストに読み込むことを目的としていないが、AI エージェントが生成する出力内で使用されるファイル。

• 含めるべき場合：スキルが最終出力で使用されるファイルを必要とする場合
• 例：ブランドアセット用のassets/logo.png、PowerPoint テンプレート用のassets/slides.pptx、HTML/React ボイラープレート用のassets/frontend-template/、タイポグラフィ用のassets/font.ttf
• ユースケース：テンプレート、画像、アイコン、ボイラープレートコード、フォント、コピーまたは変更されるサンプルドキュメント
• 利点：出力リソースをドキュメントから分離し、AI エージェントがコンテキストに読み込まずにファイルを使用できるようにします

スキルに含めるべきでないもの

スキルには、その機能を直接サポートする必須ファイルのみを含めるべきです。以下のような余分なドキュメントや補助ファイルを作成しないでください：

• README.md
• INSTALLATION_GUIDE.md
• QUICK_REFERENCE.md
• CHANGELOG.md
• 等

スキルには、AI エージェントが目の前の仕事を行うために必要な情報のみを含めるべきです。作成過程に関する補助的なコンテキスト、セットアップやテスト手順、ユーザー向けドキュメントなどは含めるべきではありません。追加のドキュメントファイルを作成すると、混乱と乱雑さを招くだけです。

段階的開示の設計原則

スキルは、コンテキストを効率的に管理するために 3 段階の読み込みシステムを使用します：

1. メタデータ（name + description） - 常にコンテキスト内（約 100 語）
2. SKILL.md 本文 - スキルがトリガーされた時（5k 語未満）
3. バンドルリソース - AI エージェントが必要に応じて（スクリプトはコンテキストウィンドウに読み込まずに実行できるため無制限）

段階的開示パターン

SKILL.md 本文はコンテキストの肥大化を最小限に抑えるため、必須事項のみに絞り、500 行未満に保ってください。この制限に近づいた場合は、コンテンツを別ファイルに分割してください。コンテンツを他のファイルに分割する場合、読者がその存在といつ使用すべきかを理解できるよう、SKILL.md からそれらを参照し、いつ読むべきかを明確に記述することが非常に重要です。

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

パターン 1：リファレンス付きハイレベルガイド

# PDF 処理

## クイックスタート

pdfplumber でテキストを抽出：
[コード例]

## 高度な機能

- **フォーム入力**: 完全なガイドは[FORMS.md](FORMS.md)を参照
- **API リファレンス**: すべてのメソッドは[REFERENCE.md](REFERENCE.md)を参照
- **例**: 一般的なパターンは[EXAMPLES.md](EXAMPLES.md)を参照

AI エージェントは必要な時にのみ FORMS.md、REFERENCE.md、または EXAMPLES.md を読み込みます。

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

複数のドメインを持つスキルの場合、無関係なコンテキストの読み込みを避けるためにドメインごとにコンテンツを整理してください：

bigquery-skill/
├── SKILL.md (概要とナビゲーション)
└── reference/
    ├── finance.md (収益、請求メトリクス)
    ├── sales.md (商談、パイプライン)
    ├── product.md (API使用状況、機能)
    └── marketing.md (キャンペーン、アトリビューション)

ユーザーが営業メトリクスについて質問すると、AI エージェントは sales.md のみを読み取ります。

同様に、複数のフレームワークやバリエーションをサポートするスキルの場合、バリエーションごとに整理してください：

cloud-deploy/
├── SKILL.md (ワークフロー + プロバイダー選択)
└── references/
    ├── aws.md (AWSデプロイパターン)
    ├── gcp.md (GCPデプロイパターン)
    └── azure.md (Azureデプロイパターン)

ユーザーが AWS を選択すると、AI エージェントは aws.md のみを読み取ります。

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

基本コンテンツを表示し、高度なコンテンツへリンク：

# DOCX 処理

## ドキュメントの作成

新しいドキュメントには docx-js を使用。[DOCX-JS.md](DOCX-JS.md)を参照。

## ドキュメントの編集

シンプルな編集には、XML を直接変更。

**変更履歴の場合**: [REDLINING.md](REDLINING.md)を参照
**OOXML の詳細の場合**: [OOXML.md](OOXML.md)を参照

AI エージェントは、ユーザーがそれらの機能を必要とする場合にのみ REDLINING.md または OOXML.md を読み取ります。

重要なガイドライン：

• 深くネストされた参照を避ける - 参照は SKILL.md から 1 階層の深さに保ってください。すべてのリファレンスファイルは SKILL.md から直接リンクすべきです。
• 長いリファレンスファイルの構造化 - 100 行を超えるファイルの場合、AI エージェントがプレビュー時に全体の範囲を確認できるよう、先頭に目次を含めてください。

スキル作成プロセス

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

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 スキルを構築する場合、関連する質問には以下が含まれます：

• 「image-editor スキルはどのような機能をサポートすべきですか？編集、回転、他には？」
• 「このスキルがどのように使用されるか、いくつかの例を教えていただけますか？」
• 「ユーザーが『この画像の赤目を除去して』や『この画像を回転して』のようなことを頼むことを想像できます。このスキルが使用される他の方法を想像できますか？」
• 「ユーザーは何と言えばこのスキルがトリガーされるべきですか？」

ユーザーを圧倒しないように、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 テンプレートを生成
• --resourcesに基づいてオプションでリソースディレクトリを作成
• --examplesが設定されている場合、オプションで例示ファイルを追加

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

ステップ 4：スキルの編集

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

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

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

• マルチステッププロセス：シーケンシャルワークフローと条件付きロジックについては references/workflows.md を参照
• 特定の出力形式または品質基準：テンプレートと例示パターンについては references/output-patterns.md を参照

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

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

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

追加されたスクリプトは、バグがなく出力が期待どおりであることを確認するために、実際に実行してテストする必要があります。類似のスクリプトが多数ある場合、完了までの時間とのバランスを取りながら、すべてが機能することへの自信を確保するために、代表的なサンプルのみをテストする必要があります。

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

SKILL.md の更新

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

フロントマター

nameとdescriptionを含む YAML フロントマターを作成してください：

• name：スキル名
• description：これはスキルの主要なトリガーメカニズムであり、AI エージェントがいつスキルを使用するかを理解するのに役立ちます。
  • スキルが何をするかと、いつ使用するかの具体的なトリガー/コンテキストの両方を含めてください。
  • すべての「このスキルを使用するタイミング」情報はここに含めてください - 本文には含めないでください。本文はトリガー後にのみ読み込まれるため、本文の「このスキルを使用するタイミング」セクションは AI エージェントにとって役に立ちません。
  • docxスキルの説明例：「変更履歴、コメント、書式の保持、テキスト抽出をサポートした包括的なドキュメント作成、編集、分析。AI エージェントが以下のプロフェッショナルドキュメント（.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. 検証に合格した場合、スキルをパッケージ化し、スキル名にちなんだ.skill ファイル（例：my-skill.skill）を作成します。このファイルにはすべてのファイルが含まれ、配布用の適切なディレクトリ構造が維持されます。.skill ファイルは.skill 拡張子を持つ zip ファイルです。

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

ステップ 6：反復

スキルをテストした後、ユーザーは改善を要求するかもしれません。これは、スキルがどのように機能したかの新鮮なコンテキストがある、スキルを使用した直後に起こることが多いです。

反復ワークフロー：

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