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（必須）

メタデータの品質： 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：スキルを編集する

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

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

実装を始めるには、先に特定した再利用可能なリソースである 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. パッケージ化：検証に合格した場合、スキル名を付けた zip ファイル（例：my-skill.zip）を作成します。配布に適したディレクトリ構造を維持したまま、すべてのファイルが含まれます。

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

ステップ 6：反復する

スキルをテストした後、ユーザーから改善を求められる場合があります。スキルを使用した直後など、スキルの動作について新鮮な情報が得られるタイミングで依頼されることがよくあります。

反復のワークフロー：

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