create-skill

elastic/elastic-docs-skills カタログ用のスキルジェネレーターです。ユーザーが新しい Claude Code スキルを作成できるよう対話形式で案内し、必要に応じて上流へのコントリビューションを提案します。

プロセス

ステップ 1：目的を理解する

何よりも先に、ユーザーがスキルに何をさせたいのかを必ず理解してください。これは最も重要なステップです。明確な回答を得るまでは先に進まないでください。

ユーザーに次のように尋ねます。「このスキルには何をさせたいですか？自動化したいタスクやワークフローを説明してください。」

ユーザーが $ARGUMENTS でスキル名を指定した場合は、その名前を確認したうえで、スキルの目的を尋ねてください。名前だけでは、有用なスキルを生成するための情報として不十分です。

指定された名前が docs- で始まらない場合は、自動的に先頭に付け加え、カタログの命名規則に合わせて正規化したことをユーザーに伝えてください。

ユーザーの回答を待ちます。回答が曖昧な場合（例：「ドキュメントを手伝って」）は、次の点を具体的に理解できるまで追加で質問してください。

• スキルが解決する問題
• 必要な入力（ファイル、URL、引数）
• スキルが生成する出力、または発生させる副作用

ステップ 2：詳細を収集する

目的が明確になったら、AskUserQuestion を使って残りの詳細を収集します（関連する質問はまとめて尋ねてもかまいません）。

1. スキル名：短いケバブケースの名前。必ず docs- で始めます（例：docs-review-docs、docs-check-applies-to）。目的に基づいて候補を提案してください。
2. カテゴリ：このスキルはどのカテゴリに属しますか？（例：authoring、review、workflow、testing）
3. トリガー：ユーザーによる呼び出しのみ（disable-model-invocation: true）にしますか、それとも Claude による自動起動にも対応させますか？
4. 必要なツール：このスキルでどのツールを利用できるようにしますか？（例：Read, Grep, Bash(gh *)）
5. 引数を受け取りますか？：スキルで $ARGUMENTS を使ってユーザー入力を受け取る必要はありますか？必要な場合、ヒントは何ですか？
6. 実行コンテキスト：メインコンテキストで実行しますか、それともフォークしたサブエージェントで実行しますか（context: fork）？

ステップ 3：スキルを生成する

回答に基づき、次の内容を含む、適切に構成された SKILL.md ファイルを生成します。

• 関連するすべてのフィールドと version: 1.0.0 を含む適切な YAML フロントマター
• Markdown 本文に記載する、明確で実行可能な指示
• スキルが入力を受け取る場合は、$ARGUMENTS または位置引数（$0、$1）を使用

必須のフロントマターフィールド：

---
name: <skill-name>
version: 1.0.0
description: <what the skill does and when to use it>
---

すべての SKILL.md には、フロントマターの閉じ区切り --- の直後に Apache 2.0 ライセンスヘッダーを必ず含めてください。

スキルをカタログ内の skills/<category>/<skill-name>/SKILL.md に書き込みます。

ファイルを書き込む前に、skill-name を検証してください。

• ケバブケースであること。
• docs- で始まること。
• skills/**/SKILL.md に既存の同じ name を持つスキルがないこと。

ステップ 4：ユーザーと内容を確認する

ファイルを書き込んだ後：

1. ファイルを読み返し、全文をユーザーに提示します。
2. ユーザーに内容を確認するよう尋ねます。「この内容でよさそうですか？変更したい点はありますか？」
3. ユーザーが問題ないと確認するまでは、先に進まないでください。
4. ユーザーが変更を依頼した場合は、ファイルを編集し、更新版を再度提示します。

ステップ 5：対話形式で評価テストを生成する

ユーザーがスキルを承認した後、スキルディレクトリ内に evals/evals.json として評価テストケースを生成します。references/eval-schemas.md に記載されているスキーマに従ってください。

5a: 初期評価を作成する

以下を網羅する評価を3〜4件作成します。

1. コアユースケース — スキルが想定する標準的な利用パターン
2. エッジケース — 特異な入力、境界条件、複雑なシナリオ
3. ネガティブ評価 — スキルがトリガーされたり、フラグを立てたり、出力を生成したりしてはならない入力です。誤検出や過剰なトリガーを防ぐために不可欠です。例：
   • リンター／チェッカーの場合：問題なく通るべき有効な入力
   • ジェネレーターの場合：スキルの対象範囲外のリクエスト
   • アナライザーの場合：報告事項のない入力

優れた評価の条件：

• 現実的で具体的なプロンプトを使う（「X を実行する」だけでなく、ファイルパス、背景、詳細を含めます）
• 判別力のある期待値を設定する（スキルが機能しなければ失敗し、どんな出力でも通るような内容にしません）
• ネガティブ評価では「フラグを立てない／生成しない／提案しない」という期待値を使う
• ベースモデルがすでに対応できることではなく、スキル独自の価値を検証する

5b: ユーザーと評価を確認する

評価を提示し、次のように尋ねます。「誤検出を防ぐネガティブ評価も含めて、提案するテストケースはこちらです。適切なシナリオを網羅できていますか？ 追加や変更をしたいものはありますか？」

5c: 繰り返し調整する

ユーザーがシナリオ、失敗パターン、エッジケースを追加で提案した場合は、それらを加えます。ユーザーが実際に経験したケースを特に重視してください。現実の失敗事例は、優れた評価になります。

Step 6: 説明を最適化する（任意）

評価を書き終えたら、トリガー精度を高めるためにスキルの description フィールドを最適化することを提案します。説明は、Claude がスキルを呼び出すかどうかを決める主要な仕組みです。

優れた説明の条件：

• スキルの機能と、使用すべき具体的な状況を明記する
• トリガー不足を防ぐため、やや「強め」にする（Claude は役立つ場合でもスキルを使わない傾向があります）
• ユーザーが自然に使うトリガーワードを含める

Step 7: テストとコントリビューションを提案する

ユーザーが承認したら、次のテストを提案します。

• ./install.sh を実行してローカルにインストールする
• Claude Code で /<skill-name> と入力する

続いて、上流へのコントリビューションを提案します。

スキルを作成したら、次の内容をユーザーに提案します。

このスキルを共有しませんか？ elastic/elastic-docs-skills カタログにコントリビュートすれば、ほかのチームも利用できるようになります。

次の作業をお手伝いできます。

1. ブランチを作成し、新しいスキルをコミットする
2. プッシュして、elastic/elastic-docs-skills に対する PR を作成する

こちらを実行しましょうか？

ユーザーが同意した場合は、add-skill-<skill-name> という名前のブランチを作成し、新しいスキルのディレクトリをコミットして、プッシュし、次の内容で PR を作成します。

• タイトル：Add <skill-name> skill
• 本文：スキルの機能、使い方、呼び出し例の概要

ガイドライン

• スキルの指示は簡潔で的を絞り、過度に複雑にしないでください
• 副作用（PR、コミット、デプロイなど）があるスキルでは、disable-model-invocation: true を優先してください
• 大量の出力を伴う調査重視のスキルでは、context: fork を使用してください
• スキルが引数を受け取る場合は、必ず argument-hint を含めてください
• 新しいスキルのバージョンは 1.0.0 とし、更新では SemVer（MAJOR.MINOR.PATCH）に従ってください