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 フィールドが含まれます。スキルをいつ使用するかの判断にエージェントが参照するのはこの2つのフィールドだけです。そのため、スキルの内容と使用すべき状況を明確かつ包括的に説明することが非常に重要です。
• 本文（Markdown）：スキルを使用するための指示やガイダンスです。スキルが呼び出された後にのみ（呼び出された場合）、読み込まれます。

同梱リソース（任意）

スクリプト（scripts/）

決定論的な信頼性が求められるタスクのための実行可能なコードファイルです。スキルでのスクリプトの作成と使用に関する詳しいガイダンスは、references/scripts.md を参照してください。

References (references/)

エージェントのプロセスと思考に役立つよう、必要に応じてコンテキストに読み込むドキュメントや参考資料です。

• 含めるタイミング：作業中にエージェントが参照する必要のあるドキュメントの場合
• 例：財務スキーマ用の references/finance.md、会社のNDAテンプレート用の references/mnda.md、会社のポリシー用の references/policies.md、API仕様用の references/api_docs.md
• ユースケース：データベーススキーマ、APIドキュメント、ドメイン知識、会社のポリシー、詳細なワークフローガイド
• メリット：SKILL.mdを簡潔に保ち、エージェントが必要だと判断した場合にのみ読み込まれます
• ベストプラクティス：ファイルが大きい場合（>10k words）は、SKILL.mdにgrep検索パターンを含めます
• 重複を避ける：情報はSKILL.mdかreferencesファイルのどちらか一方に記載し、両方には記載しないでください。スキルの中核となる情報でない限り、詳細情報はreferencesファイルに記載することをおすすめします。これにより、コンテキストウィンドウを圧迫することなく情報を見つけやすくしながら、SKILL.mdを簡潔に保てます。SKILL.mdには、不可欠な手順の指示とワークフローのガイダンスだけを残し、詳細な参考資料、スキーマ、例はreferencesファイルに移してください。

Assets (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本文 - スキルが呼び出されたときに読み込まれます（<5k words）
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. 実際の使用状況に基づいて反復する

明確な理由から該当しない場合にのみスキップし、それ以外はこの順序で手順を進めてください。

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

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

効果的なスキルを作成するには、スキルがどのように使われるかを具体例で明確に理解する必要があります。この理解は、ユーザーから直接提供される例、または生成したうえでユーザーのフィードバックにより検証された例から得られます。

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

• 「画像編集スキルでは、どのような機能に対応する必要がありますか？編集、回転、ほかにはありますか？」
• 「このスキルがどのように使われるか、例をいくつか教えていただけますか？」
• 「ユーザーが『この画像の赤目を修正して』や『この画像を回転して』といった依頼をすることが考えられます。ほかにも、どのような使われ方がありそうですか？」
• 「どのような依頼があった場合に、このスキルを使うべきですか？」

ユーザーに負担をかけないよう、1 回のメッセージで質問しすぎないでください。最も重要な質問から始め、効果を高めるために必要に応じて追加で質問してください。

スキルが対応すべき機能を明確に把握できたら、このステップを終了します。

ステップ 2：再利用可能なスキルの内容を計画する

具体的な例を効果的なスキルにするには、各例を次のように分析します。

1. その例をゼロから実行する方法を検討します
2. これらのワークフローを繰り返し実行するときに役立つスクリプト、リファレンス、アセットを特定します

例：pdf-editor スキルを作成して「このPDFを回転させてください」のような問い合わせに対応する場合、分析から次のことがわかります。

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 スクリプトを実行してください。このスクリプトを使うと、スキルに必要なものがすべて自動的に含まれた新しいスキルのテンプレートディレクトリが生成されるため、スキル作成のプロセスをより効率的かつ確実に進められます。

使い方：

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

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

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

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

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

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

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

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

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

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

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

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

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

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

SKILL.md を更新する

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

Frontmatter

name と description を含む YAML frontmatter を記述します。

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

YAML frontmatter にほかのフィールドを含めないでください。

本文

スキルと同梱リソースの使用手順を記述します。

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

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

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

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

uv run 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. 変更を実施し、再度テストする