skill-creator

スキル作成者

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

スキルについて

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

スキルが提供するもの

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 (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/）

決定論的な信頼性が必要なタスクや、繰り返し書き直されるタスクに使用する実行可能コード（Python/Bash など）です。

• 含めるタイミング：同じコードを何度も書き直している場合、または決定論的な信頼性が必要な場合
• 例：PDF の回転タスク向けの scripts/rotate_pdf.py
• 利点：トークン効率が高く、決定論的で、コンテキストに読み込まずに実行できる場合があります
• 注記：パッチ適用や環境固有の調整のために、エージェントがスクリプトを読む必要がある場合もあります

リファレンス (references/)

エージェントの処理と思考を支えるため、必要に応じてコンテキストに読み込まれることを想定したドキュメントおよび参考資料です。

• 含めるタイミング: エージェントが作業中に参照すべきドキュメントの場合
• 例: 財務スキーマ用の references/finance.md、会社の NDA テンプレート用の references/mnda.md、社内ポリシー用の references/policies.md、API 仕様用の references/api_docs.md
• ユースケース: データベーススキーマ、API ドキュメント、ドメイン知識、社内ポリシー、詳細なワークフローガイド
• 利点: SKILL.md を軽量に保ち、エージェントが必要と判断したときだけ読み込まれます
• ベストプラクティス: ファイルが大きい場合（10,000 語超）は、grep の検索パターンを SKILL.md に含めてください
• 重複の回避: 情報は 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. メタデータ（name + description） - 常にコンテキスト内にあります（約 100 語）
2. SKILL.md 本文 - スキルが起動したときに読み込まれます（5,000 語未満）
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.py を実行する）
4. スキルを編集する（リソースを実装し、SKILL.md を作成する）
5. スキルをパッケージ化する（package_skill.py を実行する）
6. 実際の使用状況に基づいて反復する

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

スキルの命名

• 小文字、数字、ハイフンのみを使用し、ユーザーが指定したタイトルはハイフン区切りの形式に正規化します（例：「Plan Mode」→ plan-mode）。
• 名前を生成する場合は、64 文字未満（英字、数字、ハイフン）にしてください。
• 動作を表す、短い動詞始まりのフレーズを優先してください。
• 明確さやトリガーの精度が向上する場合は、ツール名で名前空間を分けます（例：gh-address-comments、linear-address-issue）。
• スキルのフォルダー名は、スキル名と完全に一致させてください。

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

スキルの使用パターンがすでに明確に理解されている場合にのみ、このステップを省略してください。既存のスキルに取り組む場合でも、このステップは有益です。

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

たとえば、画像エディターのスキルを作成する場合は、次のような質問が役立ちます。

• 「画像エディターのスキルには、どのような機能が必要ですか？編集、回転など、ほかにもありますか？」
• 「このスキルがどのように使われるか、例を挙げてもらえますか？」
• 「『この画像の赤目を消して』や『画像を回転して』といった依頼が考えられます。ほかにどのような使い方があると思いますか？」
• 「どのような依頼があれば、このスキルを起動すべきですか？」

ユーザーに負担をかけないよう、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：スキルを編集する

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

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

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

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

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

再利用可能なスキルの内容から始める

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

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

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

SKILL.md を更新する

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

フロントマター

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

• name：スキル名
• description：これはスキルを起動する主な仕組みであり、スキルをいつ使うべきかをエージェントが理解するのに役立ちます。
  • スキルの機能と、使用すべき具体的なきっかけや状況の両方を含めてください。
  • 「使用するタイミング」に関する情報はすべてここに含めてください。本文には含めないでください。本文は起動後に読み込まれるため、本文に「このスキルを使用するタイミング」のセクションを設けても、エージェントの役には立ちません。
  • docx スキルの説明例：「変更履歴、コメント、書式の保持、テキスト抽出に対応した、包括的な文書の作成、編集、分析。エージェントが以下のような作業でプロフェッショナルな文書（.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. 変更を実施し、再度テストする