skill-creator

スキル作成ツール

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

スキルについて

スキルは、専門知識、ワークフロー、ツールを提供して Gemini CLI の機能を拡張する、モジュール式の自己完結型パッケージです。特定の分野やタスクに特化した「オンボーディングガイド」と考えてください。手順に関する知識を備えた専門エージェントへと Gemini CLI を変えることができます。その知識は、どのモデルも完全には備えられないものです。

スキルが提供するもの

1. 専門的なワークフロー — 特定の分野における複数ステップの手順
2. ツール連携 — 特定のファイル形式や API を扱うための手順
3. ドメインの専門知識 — 企業固有の知識、スキーマ、ビジネスロジック
4. 同梱リソース — 複雑で反復的なタスク向けのスクリプト、リファレンス、アセット

基本原則

簡潔さが重要です

コンテキストウィンドウは共有の資源です。スキルは、システムプロンプト、会話履歴、ほかのスキルのメタデータ、実際のユーザーリクエストなど、Gemini CLI に必要なあらゆる情報とコンテキストウィンドウを共有します。

Gemini CLI はすでに非常に賢いと考えるのが基本です。 Gemini CLI がまだ持っていないコンテキストだけを追加してください。各情報について、「Gemini CLI に本当にこの説明が必要か」「この段落は、それに必要なトークン数に見合うか」と考えてください。

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

適切な自由度を設定する

タスクの壊れやすさや変動性に応じて、具体性のレベルを調整してください。

自由度が高い（テキストベースの指示）：複数の方法が有効な場合、判断が状況に左右される場合、またはヒューリスティックに沿って進める場合に使います。

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

自由度が低い（特定のスクリプト、少数のパラメーター）：操作が壊れやすくエラーが起きやすい場合、一貫性が重要な場合、または特定の手順に従う必要がある場合に使います。

Gemini CLI が道を進む様子を考えてみてください。崖のある狭い橋には具体的なガードレールが必要ですが（自由度を低く）、開けた野原なら多くのルートを選べます（自由度を高く）。

スキルの構成

すべてのスキルは、必須の SKILL.md ファイルと、任意の同梱リソースで構成されます。

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Node.js/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 フィールドを含みます。スキルをいつ使用するかの判断に Gemini CLI が使うのはこの 2 つのフィールドのみです。そのため、スキルの内容と使用すべき状況を明確かつ包括的に説明することが非常に重要です。
• 本文（Markdown）：スキルを使うための指示とガイダンスです。スキルが起動した場合にのみ読み込まれます。

同梱リソース（任意）

スクリプト（scripts/）

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

• 含めるタイミング：同じコードを何度も書き直す場合や、決定論的な信頼性が必要な場合
• 例：PDF 回転タスク用の scripts/rotate_pdf.cjs
• 利点：トークン効率が高く、決定論的で、コンテキストに読み込まずに実行できます
• エージェント向けの使いやすさ：スクリプトは LLM が扱いやすい標準出力を生成する必要があります。標準のトレースバックは抑制してください。明確で簡潔な成功・失敗メッセージを出力し、コンテキストウィンドウのあふれを防ぐため、出力をページ分割または切り詰めてください（例：「成功：処理済みファイルの先頭 50 行…」）。
• 注記：パッチ適用や環境に応じた調整のため、Gemini CLI がスクリプトを読み込む必要がある場合もあります

References (references/)

Gemini CLI の処理と思考に役立つ、必要に応じてコンテキストに読み込むドキュメントおよび参照資料です。

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

Assets (assets/)

コンテキストに読み込むのではなく、Gemini CLI が生成する出力内で使用するファイルです。

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

スキルに含めないもの

スキルには、その機能を直接支える必須ファイルのみを含めてください。README.md、INSTALLATION_GUIDE.md、QUICK_REFERENCE.md、CHANGELOG.md などの余分なドキュメントや補助ファイルは作成しないでください。

スキルには、AI エージェントが目の前の作業を行うために必要な情報だけを含めてください。作成プロセスに関する補足情報、セットアップやテストの手順、ユーザー向けドキュメントなどの補助的なコンテキストは含めないでください。追加のドキュメントファイルを作成すると、混乱を招き、煩雑になるだけです。

段階的開示の設計原則

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

1. メタデータ（名前 + 説明） - 常にコンテキストに含まれます（約 100 語）
2. SKILL.md 本文 - スキルが呼び出されたときに含まれます（<5k words）
3. バンドルされたリソース - Gemini CLI が必要に応じて使用します（スクリプトはコンテキストウィンドウに読み込まずに実行できるため、上限はありません）

プログレッシブ開示のパターン

コンテキストの肥大化を最小限に抑えるため、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

Gemini CLI は、必要な場合にのみ 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)

ユーザーが売上指標について尋ねた場合、Gemini CLI は 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 を選択した場合、Gemini CLI は aws.md のみを読み込みます。

パターン 3：条件付きの詳細

基本的な内容を示し、詳細な内容にリンクします。

# CSV Processing

## Basic Analysis

Use pandas for loading and basic queries. See [PANDAS.md](PANDAS.md).

## Advanced Operations

For massive files that exceed memory, see [STREAMING.md](STREAMING.md). For timestamp normalization, see [TIMESTAMPS.md](TIMESTAMPS.md).

Gemini CLI reads REDLINING.md or OOXML.md only when the user needs those features.

重要なガイドライン：

• 参照の過度な多階層化を避ける - SKILL.md からの参照は 1 階層に保ちます。すべてのリファレンスファイルは、SKILL.md から直接リンクしてください。
• 長いリファレンスファイルを構成する - 100 行を超えるファイルには、Gemini CLI がプレビュー時に全体の範囲を把握できるよう、先頭に目次を含めてください。

スキルの作成プロセス

スキルの作成には、次の手順が含まれます。

1. 具体例を用いてスキルを理解する
2. 再利用可能なスキルの内容（スクリプト、リファレンス、アセット）を計画する
3. スキルを初期化する（node init_skill.cjs を実行）
4. スキルを編集する（リソースを実装し、SKILL.md を作成する）
5. スキルをパッケージ化する（node package_skill.cjs を実行）
6. スキルをインストールして再読み込みする
7. 実際の使用状況に基づいて反復する

適用できない明確な理由がある場合にのみ手順を省略し、それ以外は順番に進めてください。

スキルの命名

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

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

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

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

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

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

質問のループを避ける： 一度に尋ねる確認事項は、1 つか 2 つまでにしてください。まず行動することを優先し、最初の理解に基づいて具体的な機能や例のリストを提案し、ユーザーに修正してもらいます。

スキルが対応すべき機能について明確な理解が得られたら、このステップを終了します。

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

具体例を効果的なスキルに変換するには、各例を次の観点から分析します。

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

例：「この PDF を回転するのを手伝って」といったクエリに対応する pdf-editor スキルを作成する場合、分析によって次のことが分かります。

1. PDF の回転には、毎回同じコードを書き直す必要があります
2. scripts/rotate_pdf.cjs スクリプトをスキルに保存すると便利です

例：「ToDo アプリを作って」や「歩数を記録するダッシュボードを作って」といったクエリに対応する frontend-webapp-builder スキルを設計する場合、分析によって次のことが分かります。

1. フロントエンドのウェブアプリを作成するには、毎回同じ定型の HTML／React を用意する必要があります
2. 定型の HTML／React プロジェクトファイルを含む assets/hello-world/ テンプレートをスキルに保存すると便利です

例：「今日ログインしたユーザー数は？」といったクエリに対応する big-query スキルを作成する場合、分析によって次のことが分かります。

1. BigQuery のクエリでは、毎回テーブルのスキーマとリレーションシップを再確認する必要があります
2. テーブルのスキーマを記載した references/schema.md ファイルをスキルに保存すると便利です

スキルに含める内容を決めるには、具体例をそれぞれ分析して、含める再利用可能なリソース（スクリプト、リファレンス、アセット）のリストを作成します。

ステップ 3：スキルを初期化する

ここで、実際にスキルを作成します。

開発中のスキルがすでに存在し、反復作業やパッケージ化が必要な場合に限り、このステップをスキップしてください。その場合は、次のステップに進みます。

新しいスキルをゼロから作成するときは、必ず init_skill.cjs スクリプトを実行してください。このスクリプトを実行すると、新しいスキルのテンプレートディレクトリが生成され、スキルに必要なすべてのものが自動的に含まれるため、スキルの作成をより効率的かつ確実に進められます。

注： available_resources セクションに記載されている、スクリプトの絶対パスを使用してください。

使い方：

node <path-to-skill-creator>/scripts/init_skill.cjs <skill-name> --path <output-directory>

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

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

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

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

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

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

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

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

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

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

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

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

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

SKILL.md を更新する

執筆ガイドライン： 常に命令形または不定詞形を使います。

フロントマター

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

• name：スキル名
• description：これはスキルの主なトリガーとなる仕組みで、Gemini CLI がスキルをいつ使用すべきかを判断するのに役立ちます。
  • スキルでできることと、使用する具体的なトリガーや状況の両方を含めます。
  • 1 行の文字列でなければなりません（例：description: Data ingestion...）。引用符は省略できます。
  • 「いつ使用するか」に関する情報はすべてここに含めます。本文には含めないでください。トリガー後に初めて本文が読み込まれるため、本文に「このスキルを使用するタイミング」セクションを設けても Gemini CLI の役には立ちません。
  • 例：description: Data ingestion, cleaning, and transformation for tabular data. Use when Gemini CLI needs to work with CSV/TSV files to analyze large datasets, normalize schemas, or merge sources.

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

本文

スキルと付属リソースの使用方法を指示します。

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

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

注： available_resources セクションに記載された、スクリプトの絶対パスを使用してください。

node <path-to-skill-creator>/scripts/package_skill.cjs <path/to/skill-folder>

出力ディレクトリは任意で指定できます。

node <path-to-skill-creator>/scripts/package_skill.cjs <path/to/skill-folder> ./dist

パッケージ化スクリプトでは、次の処理が行われます。

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

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

2. パッケージ化：検証に合格すると、スキル名を付けた .skill ファイル（例：my-skill.skill）を作成します。このファイルには、配布に適したディレクトリ構造を保ったまま、すべてのファイルが含まれます。.skill ファイルは、拡張子が .skill の zip ファイルです。

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

ステップ 6：スキルをインストールして再読み込みする

スキルが .skill ファイルにパッケージ化されたら、ユーザーにインストールを提案します。現在のフォルダーにローカルインストールするか（ワークスペーススコープ）、ユーザーレベルでインストールするか（ユーザースコープ）を尋ねてください。

ユーザーがインストールに同意した場合は、run_shell_command ツールを使ってすぐに実行します。

• ローカル（ワークスペーススコープ）：

  gemini skills install <path/to/skill-name.skill> --scope workspace
  

• ユーザーレベル（ユーザースコープ）：

  gemini skills install <path/to/skill-name.skill> --scope user
  

重要： インストールが完了したら、新しいスキルを有効にするため、対話型の Gemini CLI セッションでユーザー自身が /skills reload コマンドを手動で実行する必要があることを必ず伝えてください。その後、/skills list を実行してインストールを確認できます。

注：エージェント自身が /skills reload コマンドを実行することはできません。このコマンドは、Gemini CLI の対話型インスタンスでユーザーが実行する必要があります。ユーザーに代わって実行しようとしないでください。

ステップ 7：反復

スキルをテストした後、ユーザーから改善を求められることがあります。多くの場合、スキルを使った直後に、その動作をまだよく覚えている状態で求められます。

反復のワークフロー：

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