skill-creator

スキルクリエイター

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

スキルについて

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

スキルが提供するもの

1. 専門的なワークフロー - 特定のドメイン向けの多段階の手順
2. ツール連携 - 特定のファイル形式や API を扱うための指示
3. ドメインの専門知識 - 会社固有の知識、スキーマ、ビジネスロジック
4. バンドルされたリソース - 複雑で反復的なタスク向けのスクリプト、リファレンス、アセット

基本原則

簡潔さが鍵

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

既定の前提: エージェントはすでに有能である。 エージェントがまだ持っていないコンテキストだけを追加してください。情報の一つひとつに対して、「エージェントは本当にこの説明を必要としているか？」「この段落はそのトークンコストに見合うか？」と問いかけてください。

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

適切な自由度を設定する

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

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

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

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

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

スキルの構造

すべてのスキルは、必須の SKILL.md ファイルと任意のバンドルされたリソースで構成されます:

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (TypeScript/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 フィールドを含みます。これらは、スキルがいつ使用されるかを判断するためにエージェントが読む唯一のフィールドであるため、スキルが何であるか、いつ使用すべきかを明確かつ包括的に説明することが非常に重要です。
• 本文（Markdown）: スキルを使用するための指示とガイダンス。スキルがトリガーされた後にのみ（トリガーされた場合）読み込まれます。

バンドルされたリソース（任意）

スクリプト（scripts/）

決定的な信頼性を必要とするタスクや、繰り返し書き直されるタスク向けの実行可能コード（TypeScript/Python/Bash など）。

• 含める場合: 同じコードが繰り返し書き直されている場合、または決定的な信頼性が必要な場合
• 例: PDF 回転タスク用の scripts/rotate-pdf.ts
• 利点: トークン効率が良く、決定的で、コンテキストに読み込まずに実行できる場合がある
• 注意: スクリプトは、パッチ適用や環境固有の調整のために、エージェントが引き続き読む必要がある場合があります

参照資料 (references/)

エージェントのプロセスと思考に情報を与えるために、必要に応じてコンテキストへ読み込まれることを意図したドキュメントおよび参照資料です。

• 含めるべき場合: エージェントが作業中に参照すべきドキュメント
• 例: 財務スキーマ用の references/finance.md、会社の NDA テンプレート用の references/mnda.md、会社のポリシー用の references/policies.md、API 仕様用の references/api_docs.md
• ユースケース: データベーススキーマ、API ドキュメント、ドメイン知識、会社のポリシー、詳細なワークフローガイド
• メリット: SKILL.md を簡潔に保ち、エージェントが必要と判断した場合にのみ読み込まれます
• ベストプラクティス: ファイルが大きい場合（10k ワード超）、SKILL.md に grep 検索パターンを含めます
• 重複を避ける: 情報は SKILL.md または参照資料ファイルのどちらかに置くべきで、両方に置くべきではありません。スキルにとって真に中核である場合を除き、詳細な情報には参照資料ファイルを優先してください。これにより SKILL.md を簡潔に保ちつつ、コンテキストウィンドウを占有することなく情報を発見できるようにします。SKILL.md には必須の手順説明とワークフローガイダンスのみを残し、詳細な参照資料、スキーマ、例は参照資料ファイルに移動してください。

アセット (assets/)

コンテキストに読み込まれることを意図しておらず、むしろエージェントが生成する出力内で使用されるファイルです。

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

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

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

• README.md
• INSTALLATION_GUIDE.md
• QUICK_REFERENCE.md
• CHANGELOG.md
• など

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

段階的開示の設計原則

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

1. メタデータ（名前 + 説明） - 常にコンテキスト内（約 100 ワード）
2. SKILL.md 本体 - スキルがトリガーされたとき（5k ワード未満）
3. バンドルされたリソース - エージェントが必要に応じて（スクリプトはコンテキストウィンドウに読み込むことなく実行できるため無制限）

段階的開示パターン

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

エージェントは、必要なときにのみ 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)

ユーザーが売上指標について質問すると、エージェントは 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 を選択すると、エージェントは 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)

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

重要なガイドライン:

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

スキル作成プロセス

スキル作成は次の手順で構成されます:

1. 具体的な例を用いてスキルを理解する
2. 再利用可能なスキルの内容（スクリプト、参照、アセット）を計画する
3. スキルを初期化する（init-skill.ts を実行）
4. スキルを編集する（リソースを実装し、SKILL.md を作成）
5. スキルをパッケージ化する（package-skill.ts を実行）
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.ts スクリプトを実行してください。このスクリプトは、スキルに必要なものがすべて自動的に含まれた新しいテンプレートスキルディレクトリを簡単に生成するため、スキル作成プロセスが大幅に効率的かつ確実になります。

使用方法:

npx tsx scripts/init-skill.ts <skill-name> --path <output-directory>

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

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

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

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

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

実証済みの設計パターンを学ぶ

スキルのニーズに応じて、以下の役立つガイドを参照してください。

• 多段階のプロセス: 順次ワークフローと条件分岐については、references/workflows.md を参照してください
• 特定の出力形式または品質基準: テンプレートとサンプルパターンについては、references/output-patterns.md を参照してください

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

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

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

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

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

SKILL.md を更新する

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

フロントマター

name と description を含む YAML フロントマターを記述します。

• name: スキル名
• description: これはスキルの主要なトリガーメカニズムであり、エージェントがいつスキルを使用すべきかを理解するのに役立ちます。
  • スキルが何を行うかと、いつ使用するかの具体的なトリガー/コンテキストの両方を含めてください。
  • 「いつ使用するか」の情報はすべてここに含めてください。本文には含めないでください。本文はトリガー後にのみ読み込まれるため、本文中の「このスキルをいつ使用するか」というセクションはエージェントにとって役立ちません。
  • docx スキルの説明例: 「変更履歴、コメント、書式の保持、テキスト抽出をサポートする包括的なドキュメントの作成、編集、分析。エージェントがプロフェッショナルなドキュメント (.docx ファイル) を扱う必要がある場合に使用します: (1) 新しいドキュメントの作成、(2) コンテンツの変更または編集、(3) 変更履歴の操作、(4) コメントの追加、その他のドキュメントタスク」

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

本文

スキルとそのバンドルされたリソースを使用するための手順を記述します。

ステップ 5: スキルのパッケージ化

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

npx tsx scripts/package-skill.ts <path/to/skill-folder>

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

npx tsx scripts/package-skill.ts <path/to/skill-folder> ./dist

パッケージ化スクリプトは以下を実行します:

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

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

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

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

ステップ 6: 反復

スキルをテストした後、ユーザーが改善を要求することがあります。これは多くの場合、スキルを使用した直後に、スキルがどのように機能したかについての新鮮なコンテキストを持った状態で発生します。

反復ワークフロー:

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