skill-creator

スキル作成者

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

スキルについて

スキルは、専門知識、ワークフロー、ツールを提供して 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 (Python/Bash/etc.)
    ├── references/       - Documentation intended to be loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)

SKILL.md（必須）

メタデータの品質： YAML フロントマターの name と description によって、エージェントがスキルを使用するタイミングが決まります。スキルの内容と使用するタイミングを具体的に記述してください。「このスキルは、〜のときに使用します」のように、三人称で記述してください。

同梱リソース（任意）

スクリプト（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 を簡潔に保ち、必要と判断されたときだけ読み込めます
• ベストプラクティス：ファイルが大きい場合（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
• 用途：テンプレート、画像、アイコン、ひな形コード、フォント、コピーまたは編集するサンプル文書
• 利点：出力リソースをドキュメントから分離し、エージェントがファイルをコンテキストに読み込まずに使用できるようにします

プログレッシブ・ディスクロージャーの設計原則

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

1. メタデータ（name + description） — 常にコンテキスト内（約 100 語）
2. SKILL.md 本文 — スキルが適用されたとき（5k 語未満）
3. 同梱リソース — エージェントが必要と判断したとき（無制限*）

*スクリプトはコンテキストウィンドウに読み込まずに実行できるため、無制限です。

スキル作成プロセス

スキルを作成するには、明確な理由があって該当しない場合を除き、「スキル作成プロセス」を順番に進めてください。

ステップ 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>

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

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

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

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

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

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

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

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

SKILL.md を更新する

文体： スキル全体を、二人称ではなく命令形・不定詞形（動詞から始まる指示）で書いてください。客観的で指示的な表現を使用します（「X を達成するには、Y を行う」のように書き、「X を行うべきです」や「X を行う必要がある場合」のような表現は避けます）。これにより、AI が利用する際の一貫性と明確さを保てます。

SKILL.md を完成させるには、次の質問に答えてください。

1. スキルの目的は何ですか。数文で説明してください。
2. どのような場合にスキルを使用しますか。
3. 実際に、エージェントはどのようにスキルを使用すればよいですか。エージェントが使い方を把握できるよう、上で作成した再利用可能なスキルの内容をすべて参照してください。

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

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

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

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

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

パッケージ化スクリプトは次の処理を行います。

1. 検証：スキルを自動でチェックし、次の項目を確認します。

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

2. パッケージ化：検証に合格すると、スキル名に基づいた名前（例：my-skill.zip）の zip ファイルを作成します。配布用に、適切なディレクトリ構造を維持したまま、すべてのファイルを含めます。

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

ステップ 6：反復する

スキルをテストした後、ユーザーから改善を求められることがあります。多くの場合、スキルを使用した直後に、実行結果についての新鮮な文脈がある状態で改善を求められます。

反復のワークフロー：

1. 実際のタスクでスキルを使用する
2. 問題点や非効率な点に気づく
3. SKILL.md または同梱リソースのどこを更新すべきか特定する
4. 変更を実装して、再度テストする