skill-creator

スキルクリエーター

新しいスキルを作成し、反復的に改善するためのスキルです。

大まかな流れは次のとおりです。

• スキルに何をさせるか、またどのように実行させるかをおおよそ決めます
• スキルの草案を作成します
• テスト用のプロンプトをいくつか作り、スキルにアクセスできる状態で Claude を実行します
• 定性的および定量的な両面から、ユーザーが結果を評価できるよう支援します
  • 実行がバックグラウンドで進む間に、定量評価がなければいくつか作成します（すでにある場合は、そのまま使うか、変更が必要だと思えば修正します）。その後、ユーザーに説明します（既存の評価がある場合は、それについて説明します）
  • eval-viewer/generate_review.py スクリプトを使って結果を表示し、ユーザーが確認できるようにします。また、定量的な指標も確認できるようにします
• 結果に対するユーザーの評価から得られたフィードバックに基づいてスキルを書き直します（定量的なベンチマークで明らかになった重大な問題があれば、それも反映します）
• 納得できるまで繰り返します
• テストセットを拡充し、さらに大規模に再度試します

このスキルを使う際のあなたの役割は、ユーザーがこのプロセスのどの段階にいるかを把握し、適切な段階から支援して次に進めることです。たとえば、ユーザーが「X 用のスキルを作りたい」と言っている場合、意図を具体化し、草案やテストケースを作成し、評価方法を決め、すべてのプロンプトを実行して、改善を繰り返すところまで支援できます。

一方で、すでにスキルの草案がある場合は、評価と反復改善の段階からすぐに始められます。

もちろん、常に柔軟に対応してください。ユーザーが「たくさん評価を実行する必要はないので、気軽に一緒に考えてほしい」と言うなら、それに応じてください。

スキルが完成したら（ただし、順序は柔軟です）、スキルの説明を改善するツールも実行できます。スキルを起動する条件を最適化するための、専用の別スクリプトがあります。

用語はユーザーに合わせてください。必要に応じて、評価基準を説明してください。

スキルの作成

意図の把握

まず、ユーザーの意図を理解します。現在の会話に、ユーザーがスキルとしてまとめたいワークフローがすでに含まれている場合（たとえば、「これをスキルにして」と言っている場合）は、まず会話履歴から、使用したツール、手順、ユーザーによる修正、確認できた入出力形式を抽出します。不足している情報はユーザーに補ってもらい、次の段階に進む前に内容を確認してもらいます。

1. このスキルで Claude に何をできるようにしますか？
2. どのようなときにこのスキルを起動しますか？（ユーザーが使うフレーズや状況）
3. 期待する出力形式は何ですか？
4. スキルが正しく動作するか確認するため、テストケースを用意しますか？客観的に検証できる出力（ファイル変換、データ抽出、コード生成、定型の手順など）を行うスキルでは、テストケースが役立ちます。主観的な出力（文体、アートなど）を行うスキルでは、必要ないことが多いです。スキルの種類に応じて適切な初期案を提案しつつ、最終的にはユーザーに判断してもらいます。

ヒアリングと調査

エッジケース、入出力形式、サンプルファイル、成功基準、依存関係について、積極的に質問します。こうした点が固まるまで、テスト用プロンプトの作成は待ちます。

利用可能な MCP を確認します。調査（ドキュメントの検索、類似スキルの発見、ベストプラクティスの確認）に役立つ場合は、利用可能であればサブエージェントを使って並行して調べます。そうでなければ、その場で調査します。ユーザーの負担を減らせるよう、参考情報を事前に用意しておきます。

SKILL.md を作成する

ユーザーへのヒアリングに基づき、以下の項目を記入します。

• name：スキル識別子（1～64 文字、小文字の a～z、数字の 0～9、ハイフンのみ使用可。ディレクトリ名と一致する必要があります）
• description：スキルの機能と使用するタイミング（1～1024 文字、三人称）。具体的な使用場面を示し、関連するスキルとの違いを明確にします。すべての説明文がより頻繁にトリガーされるべきだと決めつけず、確認されたトリガーの見逃しや誤検出に応じて説明の範囲を調整します。
• argument-hint（任意。Claude Code の拡張機能で、agentskills.io の仕様には含まれません。他のクライアントでの対応状況は異なり、厳格なバリデーターではエラーになります）：ユーザーを案内するため、スキル一覧に表示されます（例："[file or directory]"）
• compatibility（任意）：プラットフォームや環境の要件（1～500 文字）
• スキルの残りの部分 :)

スキル作成ガイド

作成のベストプラクティス

参考：https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices — チェックリストの全文は references/best-practices.md にあります。スキルの内容を作成またはレビューする前にお読みください。下書きの際に特に重要な原則は、次の 4 つです。

• Claude はすでに非常に高い能力を備えています。 エージェントに不足している情報を追加します。ローカルな判断とその理由、実測した知見、スキルが実行される環境で有効な、明白ではない契約や参照先を示します（URL はすべてのクライアントでアクセスできるとは限りません）。実際のミスを防げる場合は、短いリソースマップや正確なスキーマを含めます。コードベースを重複させたり、一般的な調査方法を教えたりするのは避けます。
• 簡潔さが重要です。 タスクに役立つ知識と完了条件を保ちながら、繰り返しや基礎事項を削ります。明白でない API の契約や必須の出力を明確にする場合は、正確な名称や短いスニペットを優先します。一般的な API にいちいち例を付ける必要はありません。
• 柔軟性は壊れやすさに合わせます。 多くの方法が使える場合は文章で指針を示し、一貫性が重要な場合は正確なスクリプトを用います。多くのスキルはその中間に位置します。
• 説明文は三人称で書きます。 「Excel ファイルを処理します」とし、「Excel ファイルの処理をお手伝いします」とはしません。説明文はシステムプロンプトに挿入されるため、人称が混在するとスキルの検索性が損なわれます。

スキルの構成

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description required)
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/    - Executable code for deterministic/repetitive tasks
    ├── references/ - Docs loaded into context as needed
    └── assets/     - Files used in output (templates, icons, fonts)

段階的な開示

スキルは、次の 3 段階で読み込まれます。

1. メタデータ（name + description）— クライアントが検出・選択します。一覧への表示方法はクライアントによって異なります。
2. SKILL.md 本文 — スキルがトリガーされるとコンテキストに含まれます（500 行未満が理想です）。
3. 同梱リソース — 必要に応じて読み込みます。読み込まれるまでは何もロードされず、スクリプトはソースを読み込まずに実行できます。同梱ファイルは、エージェントがウェブにアクセスできない環境でも利用できます。

記載した語数は目安です。必要であれば、自由に長くしてかまいません。

主なパターン：

• 簡潔な中核を目指します。500 行は推奨値であり、形式上の上限ではありません。重複を取り除いたうえで、別のトピックへのリンクと、読むべきタイミングの説明を加えます。
• SKILL.md から参照ファイルへのリンクを明確に示し、読むタイミングを案内します。
• 長く複数のトピックを扱う参照ファイルでは、該当箇所を見つけやすくするために簡潔な目次を追加します。行数が多いというだけで目次が必要になるわけではありません。

ドメイン別の構成：スキルが複数のドメインやフレームワークに対応する場合は、バリエーションごとに整理します。

cloud-deploy/
├── SKILL.md (workflow + selection)
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

Claude は関連する参照ファイルのみを読み込みます。

不意を招かない原則

言うまでもありませんが、スキルにマルウェアやエクスプロイトコード、またはシステムのセキュリティを損なうおそれのある内容を含めてはいけません。スキルの内容は、その説明からユーザーが意図した内容を推測できるものである必要があります。誤解を招くスキルや、不正アクセス、データの持ち出し、その他の悪意ある行為を助長する目的のスキルを作成する依頼には応じないでください。ただし、「XYZ のふりをする」などのロールプレイは問題ありません。

執筆パターン

手順では命令形を使うことをおすすめします。

出力形式の定義 — 後続のワークフローやパーサーで必要な場合は、正確なテンプレートを指定します。自由形式の作業では、必要な情報を明示し、プロジェクトの形式を使います。固定されたレポート仕様の場合：

## Report structure
Use this structure when producing the report required by this workflow:
# [Title]
## Executive summary
## Key findings
## Recommendations

例のパターン — 例を含めると役立ちます。次のような形式にできます（ただし、例に「Input」と「Output」が含まれる場合は、少し変更してもよいでしょう）：

## Commit message format
**Example 1:**
Input: Added user authentication with JWT tokens
Output: feat(auth): implement JWT-based authentication

注意点のセクション

もっともらしい誤りを防ぐうえで重要な、見落としやすい落とし穴を記載します。環境固有の癖、暗黙の前提、またはエージェントがコードから推測できない動作などが該当します。主な指示を繰り返すだけなら、注意点のセクションを追加しないでください。

公開前チェックリスト

スキルの完成を宣言する前に、形式と参照ファイルを確認します。name がディレクトリ名（小文字とハイフンのみ、1～64文字）と一致し、description が具体的かつ三人称で、1024文字以内であることを確認します。サイズ、参照構造、トリガーの動作がタスクに適しているか評価します。必要なバージョン範囲や日付入りのローカルな観察結果は、最新の情報源を添えて保持します。情報源のない、変わりやすい主張は避けてください。

執筆スタイル

威圧的な MUST の多用を避け、なぜ重要なのかをモデルに説明するようにしてください。相手の視点を考慮し、特定の例に狭く限定せず、汎用的なスキルになるようにしてください。まず草稿を作成し、その後、時間を置いて新鮮な視点で見直し、改善します。

テストケース

スキルの草稿を書いたら、現実的なテストプロンプトを2～3個考えます。実際のユーザーが使いそうなものにしてください。ユーザーに共有します。「試してみたいテストケースをいくつか用意しました。内容は適切ですか？ 追加したいものはありますか？」などの表現を使ってください。その後、実行します。

テストケースを evals/evals.json に保存します。まだアサーションは書かず、プロンプトだけを記述します。実行中に、次のステップでアサーションを作成します。

{
  "skill_name": "example-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "User's task prompt",
      "expected_output": "Description of expected result",
      "files": []
    }
  ]
}

完全なスキーマについては references/schemas.md を参照してください（後で追加する assertions フィールドも含まれています）。

テストケースの実行と評価

このセクションは一連の作業です。途中で止めないでください。/skill-test やその他のテスト用スキルは使用しないでください。

結果は、スキルのディレクトリと同じ階層にある <skill-name>-workspace/ に保存します。ワークスペース内では、イテレーションごとに整理し（iteration-1/、iteration-2/ など）、その中に各テストケースのディレクトリ（eval-0/、eval-1/ など）を作成します。これらのディレクトリを最初にすべて作るのではなく、作業の進行に合わせて作成してください。

ステップ 1：すべての実行（スキルあり・ベースライン）を同じターンで開始する

各テストケースについて、同じターン内にサブエージェントを2つ起動します。1つはスキルあり、もう1つはスキルなしです。これは重要です。まずスキルありの実行を起動し、後からベースラインを実行することは避けてください。すべてを同時に開始し、ほぼ同時に完了するようにします。

スキルありの実行：

Execute this task:
- Skill path: <path-to-skill>
- Task: <eval prompt>
- Input files: <eval files if any, or "none">
- Save outputs to: <workspace>/iteration-<N>/eval-<ID>/with_skill/outputs/
- Outputs to save: <what the user cares about — e.g., "the .docx file", "the final CSV">

ベースラインの実行（同じプロンプトを使いますが、ベースラインは状況に応じて異なります）：

• 新しいスキルを作成する場合：スキルなしで実行します。同じプロンプトを使い、スキルのパスは指定せず、without_skill/outputs/ に保存します。
• 既存のスキルを改善する場合：古いバージョンを使います。編集前にスキルをスナップショットとして保存します（cp -r <skill-path> <workspace>/skill-snapshot/）。その後、ベースラインのサブエージェントにスナップショットを指定します。old_skill/outputs/ に保存します。

各テストケースについて eval_metadata.json を作成します（アサーションはひとまず空で構いません）。何をテストするのかを示す説明的な名前を各評価に付け、単なる「eval-0」のような名前は避けてください。その名前をディレクトリ名にも使います。このイテレーションで新規または変更された評価プロンプトを使う場合は、新しい評価ディレクトリごとにこれらのファイルを作成します。以前のイテレーションから引き継がれると考えないでください。

{
  "eval_id": 0,
  "eval_name": "descriptive-name-here",
  "prompt": "The user's task prompt",
  "assertions": []
}

ステップ 2：実行中にアサーションを作成する

実行が完了するのをただ待つのではなく、この時間を有効に活用できます。各テストケースの定量的なアサーションを作成し、その内容をユーザーに説明してください。evals/evals.json にアサーションがすでにある場合は、その内容を確認し、何をチェックするのか説明してください。

優れたアサーションは客観的に検証でき、説明的な名前が付いています。ベンチマークビューアーで結果を見た人が、各アサーションのチェック内容をすぐに理解できるよう、明確に記述してください。文章のスタイルやデザインの品質などの主観的なスキルは、定性的に評価するのが適しています。人間の判断が必要なものに無理にアサーションを設定しないでください。

アサーションを作成したら、eval_metadata.json ファイルと evals/evals.json を更新してください。また、ビューアーで定性的な出力と定量的なベンチマークの両方を確認できることをユーザーに説明してください。

ステップ 3：実行完了時にタイミングデータを記録する

各サブエージェントのタスクが完了すると、total_tokens と duration_ms を含む通知が届きます。このデータをすぐに、実行ディレクトリの timing.json に保存してください。

{
  "total_tokens": 84852,
  "duration_ms": 23332,
  "total_duration_seconds": 23.3
}

このデータを記録できる機会はこのときだけです。タスク通知を通じて届き、ほかの場所には保存されません。まとめて処理しようとせず、通知が届くたびに処理してください。

ステップ 4：採点、集計し、ビューアーを起動する

すべての実行が終わったら、次の手順に従ってください。

1. 各実行を採点する — 採点用サブエージェントを起動する（またはインラインで採点する）ために、agents/grader.md を読み、各アサーションを出力に照らして評価してください。結果は各実行ディレクトリの grading.json に保存します。grading.json の expectations 配列では、text、passed、evidence のフィールドを使用してください（name／met／details やその他の形式は使用しないでください）。ビューアーはこれらの正確なフィールド名に依存しています。プログラムでチェックできるアサーションは、目視で判断するのではなく、スクリプトを作成して実行してください。スクリプトのほうが速く、信頼性が高く、反復時にも再利用できます。

2. ベンチマークに集計する — skill-creator ディレクトリにある集計スクリプトを実行してください。

   python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name>
   

   このスクリプトは、各構成の合格率、所要時間、トークン数について、平均 ± 標準偏差と差分を含む benchmark.json と benchmark.md を生成します。benchmark.json を手動で作成する場合は、ビューアーが想定する正確なスキーマについて references/schemas.md を参照してください。 各 with_skill バージョンは、対応するベースラインより前に配置してください。

3. 分析担当者による確認を行う — ベンチマークデータを読み、集計統計だけでは見えない傾向を明らかにしてください。確認すべき点については、agents/analyzer.md の「Analyzing Benchmark Results」セクションを参照してください。たとえば、スキルの有無にかかわらず常に合格するアサーション（識別力がない）、ばらつきの大きい評価（不安定な可能性がある）、所要時間とトークン数のトレードオフなどです。

4. ビューアーを起動する — 定性的な出力と定量的なデータの両方を表示してください。

   python <skill-creator-path>/eval-viewer/generate_review.py \
     <workspace>/iteration-N \
     --skill-name "my-skill" \
     --benchmark <workspace>/iteration-N/benchmark.json &
   

   Windows では、末尾の & を省略して別のターミナルで実行するか、サーバーを起動せずにスタンドアロンの HTML ファイルを書き出すため、--static <output_path> を使用してください。 反復 2 以降では、--previous-workspace <workspace>/iteration-<N-1> も渡してください。

   Cowork／ヘッドレス環境： webbrowser.open() が利用できない場合や、環境にディスプレイがない場合は、サーバーを起動せずにスタンドアロンの HTML ファイルを書き出すため、--static <output_path> を使用してください。ユーザーが「Submit All Reviews」をクリックすると、フィードバックが feedback.json ファイルとしてダウンロードされます。ダウンロード後、次の反復で読み込めるよう、feedback.json をワークスペースディレクトリにコピーしてください。

注：ビューアーの作成には generate_review.py を使用してください。独自の HTML を作成する必要はありません。

5. ユーザーに伝える — たとえば、次のように伝えてください。「結果をブラウザーで開きました。タブは 2 つあります。『Outputs』では各テストケースを確認してフィードバックを残せます。『Benchmark』では定量的な比較を確認できます。確認が終わったら、こちらに戻ってお知らせください。」

ビューアーでユーザーに表示される内容

「Outputs」タブには、一度に1つのテストケースが表示されます。

• Prompt：与えられたタスク
• Output：スキルが生成したファイル。可能な場合はインラインで表示されます
• Previous Output（イテレーション2以降）：前回のイテレーションの出力を表示する折りたたみセクション
• Formal Grades（採点を実行した場合）：アサーションの合否を表示する折りたたみセクション
• Feedback：入力と同時に自動保存されるテキストボックス
• Previous Feedback（イテレーション2以降）：前回のコメントがテキストボックスの下に表示されます

「Benchmark」タブには、各設定の合格率、所要時間、トークン使用量をまとめた統計が表示され、評価ごとの内訳と分析担当者の所見も確認できます。

前後のボタンまたは矢印キーで移動します。完了したら「Submit All Reviews」をクリックすると、すべてのフィードバックが feedback.json に保存されます。

ステップ5：フィードバックを読む

ユーザーから完了したと伝えられたら、feedback.json を読みます。

{
  "reviews": [
    {"run_id": "eval-0-with_skill", "feedback": "the chart is missing axis labels", "timestamp": "..."},
    {"run_id": "eval-1-with_skill", "feedback": "", "timestamp": "..."},
    {"run_id": "eval-2-with_skill", "feedback": "perfect, love this", "timestamp": "..."}
  ],
  "status": "complete"
}

フィードバックが空の場合、ユーザーは問題ないと判断しています。ユーザーが具体的な不満を述べたテストケースを中心に改善してください。

ビューアーサーバーを使い終わったら終了してください。Unix/macOS では kill <PID>、Windows では taskkill /PID <PID> /F を使うか、サーバーを実行しているターミナルで Ctrl+C を押してください。

---

スキルを改善する

ここが改善サイクルの中心です。テストケースを実行し、ユーザーが結果を確認したら、フィードバックに基づいてスキルを改善します。

改善の考え方

1. フィードバックから一般化する。 ここで目指しているのは、多種多様なプロンプトに対して、何百万回も（文字どおりかもしれませんし、それ以上かもしれません）使えるスキルを作ることです。ここでは、作業を速く進めるために、あなたとユーザーが少数の例を何度も繰り返し改善しています。ユーザーはこれらの例を隅々まで把握しており、新しい出力をすばやく評価できます。しかし、共同で開発しているスキルがその例でしか機能しないなら、役に立ちません。細部にこだわった過学習的な変更や、過度に制約の厳しい MUST の追加をする代わりに、根強い問題がある場合は、別の比喩を使ったり、異なる作業パターンを提案したりしてみてください。試すコストは比較的低く、素晴らしい方法が見つかるかもしれません。

2. プロンプトを簡潔に保つ。 役に立っていない内容は削除してください。最終出力だけでなく、やり取りの記録も必ず読みましょう。スキルのせいで、モデルが生産性のない作業に多くの時間を費やしているようなら、その原因になっている部分を削除して、どうなるか試してみてください。

3. 理由を説明する。 モデルに求めることの理由を説明できるよう努めてください。現在の LLM は賢く、他者の意図をよく理解します。適切な枠組みがあれば、型どおりの指示に従うだけでなく、実際に物事を成し遂げられます。ユーザーのフィードバックがそっけなかったり、苛立ちを含んでいたりしても、タスクの内容や、ユーザーがそう書いた理由、実際に何を書いたのかを理解し、その理解を指示に反映するよう努めてください。指示に ALWAYS や NEVER をすべて大文字で書いたり、非常に厳格な構造を使ったりしていることに気づいたら、それは注意信号です。可能であれば、理由を説明する形に言い換え、求めていることが重要な理由をモデルが理解できるようにしてください。そのほうが人間に寄り添い、強力で、効果的なアプローチです。

4. テストケース間で繰り返される作業を探す。 テスト実行のやり取りの記録を読み、サブエージェントがそれぞれ独立して同じようなヘルパースクリプトを書いていないか、同じ複数段階の手順を踏んでいないか確認してください。3つのテストケースすべてでサブエージェントが create_docx.py や build_chart.py を作成したなら、それはスキルにそのスクリプトを含めるべきだという強い兆候です。一度だけ作成して scripts/ に配置し、スキルにそれを使うよう指示してください。こうすれば、今後の実行ごとに同じものを作り直す必要がなくなります。

反復ループ

スキルを改善したら、次の手順を実行します。

1. 改善内容をスキルに反映します
2. ベースライン実行も含め、すべてのテストケースを新しい iteration-<N+1>/ ディレクトリに再実行します。新しいスキルを作成する場合、ベースラインは常に without_skill（スキルなし）とし、反復を重ねても変わりません。既存のスキルを改善する場合は、ユーザーが最初に提示した元のバージョンと前回の反復のどちらをベースラインにするか、状況に応じて判断してください。
3. --previous-workspace に前回の反復を指定して、レビュアーを起動します
4. ユーザーがレビューを終えたと伝えてくれるまで待ちます
5. 新しいフィードバックを読み、再度改善して繰り返します

次のいずれかに該当するまで続けてください。

• ユーザーが満足したと言う
• フィードバックがすべて空である（すべて問題ない）
• 意味のある改善ができなくなる

---

上級編：ブラインド比較

スキルの2つのバージョンをより厳密に比較したい場合（たとえば、ユーザーから「新しいバージョンのほうが本当に良いの？」と尋ねられた場合）は、ブラインド比較システムを利用できます。詳細は agents/comparator.md と agents/analyzer.md を読んでください。基本的には、どちらがどのバージョンかを知らせずに、2つの出力を独立したエージェントに提示して品質を判定してもらい、その後、勝者となった理由を分析します。

これは任意であり、サブエージェントが必要です。また、ほとんどのユーザーには不要です。通常は人間によるレビューで十分です。

---

説明の最適化

SKILL.md のフロントマターにある description フィールドは、Claude がスキルを呼び出すかどうかを決める主な仕組みです。スキルを作成または改善した後、呼び出し精度を高めるために description を最適化することを提案してください。

手順 1：トリガー評価クエリの生成

should-trigger と should-not-trigger を混ぜた評価クエリを20個作成し、JSONとして保存します。

[
  {"query": "the user prompt", "should_trigger": true},
  {"query": "another prompt", "should_trigger": false}
]

クエリは現実的で、Claude Code や Claude.ai のユーザーが実際に入力しそうな内容にしてください。抽象的な依頼ではなく、具体的で詳細が十分にある依頼にします。たとえば、ファイルパス、ユーザーの仕事や状況に関する個人的な背景情報、列名や値、会社名、URLなどを含めます。背景情報を少し加えます。小文字のみの文、略語や誤字、くだけた表現を含めるものもあります。長さに幅を持たせ、明確に判別できるものばかりではなく、境界事例を重視してください（ユーザーが内容を確認して承認できるようにします）。

悪い例："このデータを整形して"、"PDFからテキストを抽出して"、"グラフを作成して"

良い例："上司から xlsx ファイルが送られてきたんだけど（ダウンロードフォルダにあって、たしか 'Q4 sales final FINAL v2.xlsx' みたいな名前）、利益率をパーセンテージで表示する列を追加してほしいって。売上はC列で、コストはD列だと思う"

should-trigger クエリ（8～10個）では、カバレッジを意識してください。同じ意図を異なる言い回しで表現し、形式的なものもくだけたものも含めます。ユーザーがスキル名やファイル形式を明示していなくても、明らかにそのスキルが必要なケースを含めます。あまり一般的でないユースケースや、別のスキルと競合しながらも、このスキルを選ぶべきケースも含めてください。

should-not-trigger クエリ（8～10個）では、ニアミスが特に重要です。スキルとキーワードや概念が共通していても、実際には別の対応が必要なクエリを考えてください。隣接領域、単純なキーワード一致なら起動しそうでも実際にはそうすべきでない曖昧な表現、このスキルが扱う内容に触れているものの別のツールのほうが適切な状況などを考えます。

避けるべきなのは、should-not-trigger クエリが明らかに無関係なものになることです。PDF スキルの否定テストに「フィボナッチ関数を書いて」は簡単すぎて、何も検証できません。否定ケースは、本当に見分けるのが難しいものにしてください。

ステップ 2：ユーザーとレビューする

HTML テンプレートを使って、評価セットをユーザーに提示します。

1. assets/eval_review.html からテンプレートを読み込みます
2. プレースホルダーを置き換えます。
   • __EVAL_DATA_PLACEHOLDER__ → 評価項目の JSON 配列（JS 変数への代入なので、前後に引用符は付けません）
   • __SKILL_NAME_PLACEHOLDER__ → スキル名
   • __SKILL_DESCRIPTION_PLACEHOLDER__ → スキルの現在の説明
3. 一時ファイル（例：/tmp/eval_review_<skill-name>.html）に書き込み、開きます：open /tmp/eval_review_<skill-name>.html
4. ユーザーはクエリの編集、should-trigger の切り替え、項目の追加・削除を行い、「Export Eval Set」をクリックできます
5. ファイルは ~/Downloads/eval_set.json にダウンロードされます。複数ある場合（例：eval_set (1).json）は、Downloads フォルダーで最新のものを確認します

このステップは重要です。評価クエリが不適切だと、説明も不適切になります。

ステップ 3：最適化ループを実行する

ユーザーに「少し時間がかかります。バックグラウンドで最適化ループを実行し、定期的に状況を確認します」と伝えます。

評価セットをワークスペースに保存してから、バックグラウンドで実行します。

python -m scripts.run_loop \
  --eval-set <path-to-trigger-eval.json> \
  --skill-path <path-to-skill> \
  --model <model-id-powering-this-session> \
  --max-iterations 5 \
  --verbose

認証済みの Claude CLI がサポートするモデル ID を使用します。現在のホストモデルは別のプロバイダーのものかもしれません。ID をそのまま claude -p に渡さないでください。

実行中は、出力を定期的に確認し、現在の反復回数やスコアをユーザーに報告します。

この処理により、最適化ループ全体が自動的に実行されます。評価セットをトレーニング用 60％、保留テスト用 40％に分け、現在の説明を評価します（信頼できるトリガー率を得るため、各クエリを 3 回実行します）。その後、失敗した項目に基づいて改善案を Claude に提案させます。新しい説明はトレーニング用とテスト用の両方で再評価され、最大 5 回反復されます。完了すると、反復ごとの結果を示す HTML レポートがブラウザーで開き、best_description を含む JSON が返されます。best_description はトレーニングスコアではなく保留スコアに基づいて選ばれます。最良の候補を選ぶため、この分割データは検証データとして機能します。偏りのない推定値を得るには、最終テスト用に新しい評価セットを使用してください。

スキルのトリガーの仕組み

トリガー評価では、スキルが最初のツール呼び出しかどうかをスコア化します。他のツールの後にスキルが使われた場合は、トリガーされなかったものとして扱われます（ローカル評価者による確認、2026-10-11）。

説明はホストがスキルを選ぶ際に役立ちますが、実際に有効化されるかどうかは、クライアント、モデル、利用可能なツールによって異なります。単純なものと複雑で現実的なリクエストに加え、近似したリクエストもテストしてください。単純なリクエストではスキルがトリガーされないと決めつけないでください。 説明の選択に使うクエリとは別に、最終的なホールドアウトセットを用意してください。同じテストセットを繰り返し選択に使うと、そのセットに過剰適合する可能性があります。

ステップ 4：結果を適用する

JSON 出力から best_description を取得し、スキルの SKILL.md フロントマターを更新します。更新前後の内容をユーザーに示し、スコアを報告します。

---

パッケージ化して提示する（present_files ツールが利用可能な場合のみ）

present_files ツールにアクセスできるか確認します。アクセスできない場合は、このステップを省略してください。アクセスできる場合は、スキルをパッケージ化して .skill ファイルをユーザーに提示します。

python -m scripts.package_skill <path/to/skill-folder>

パッケージ化したら、インストールできるように、生成された .skill ファイルのパスをユーザーに伝えます。

---

Claude.ai 固有の手順

Claude.ai では、基本的なワークフロー（下書き → テスト → レビュー → 改善 → 繰り返し）は同じですが、サブエージェントがないため、一部の仕組みが異なります。以下の点を調整してください。

テストケースの実行：サブエージェントがないため、並列実行はできません。各テストケースについて、スキルの SKILL.md を読み、その指示に従ってテスト用プロンプトを自分で実行してください。1件ずつ進めてください。これは独立したサブエージェントを使うより厳密さに欠けます（スキルを作成したあなた自身が実行するため、すべての背景情報を把握しています）が、有用な妥当性確認になります。また、人間によるレビューのステップがその不足を補います。ベースラインの実行は省略し、スキルを使って依頼されたタスクを完了してください。

結果のレビュー：ブラウザーを開けない場合（例：Claude.ai の VM に画面表示機能がない場合や、リモートサーバーを使用している場合）は、ブラウザーレビュアーを完全に省略してください。代わりに、会話内で結果を直接提示します。各テストケースについて、プロンプトと出力を表示してください。出力がユーザーに確認してもらう必要のあるファイル（.docx や .xlsx など）の場合は、ファイルシステムに保存し、ダウンロードして確認できるよう保存先を伝えてください。会話内でフィードバックを求めます：「これはどうでしょうか？変更したい点はありますか？」

ベンチマーク：ベースラインとの比較に依存しており、サブエージェントがいない場合は意味をなさないため、定量的なベンチマークは省略してください。ユーザーからの定性的なフィードバックに重点を置きます。

反復のループ：これまでと同様に、スキルを改善し、テストケースを再実行して、フィードバックを求めます。途中にブラウザーレビュアーを挟まないだけです。ファイルシステムが使える場合は、反復ごとにディレクトリを作成して結果を整理できます。

説明の最適化：このセクションでは claude CLI ツール（特に claude -p）が必要ですが、これは Claude Code でのみ利用できます。Claude.ai を使用している場合は省略してください。

ブラインド比較：サブエージェントが必要です。省略してください。

パッケージ化：package_skill.py スクリプトは、Python とファイルシステムが使える環境ならどこでも動作します。Claude.ai ではこれを実行でき、ユーザーは生成された .skill ファイルをダウンロードできます。

既存のスキルの更新：新しいスキルを作成するのではなく、既存のスキルを更新するよう求められる場合があります。その場合は、次の点に従ってください。

• 元の名前を維持してください。 スキルのディレクトリ名と name フロントマターのフィールドを確認し、変更せずに使用してください。たとえば、インストール済みのスキルが research-helper の場合、research-helper-v2 ではなく research-helper.skill を出力します。
• 編集する前に、書き込み可能な場所にコピーしてください。 インストール済みのスキルのパスは読み取り専用の場合があります。スクラッチディレクトリにコピーして編集し、そのコピーからパッケージを作成してください。

Cowork 固有の手順

Cowork を使用している場合に知っておくべき主な点は次のとおりです。

• サブエージェントを利用できるため、メインのワークフロー（テストケースを並行して起動し、ベースラインを実行し、採点するなど）はすべて機能します。（ただし、タイムアウトによる深刻な問題が発生した場合は、テスト用プロンプトを並行ではなく順番に実行してもかまいません。）
• ブラウザーやディスプレイがないため、評価ビューアーを生成するときは、サーバーを起動する代わりに --static <output_path> を使ってスタンドアロンの HTML ファイルを書き出してください。その後、ユーザーがクリックしてブラウザーで HTML を開けるリンクを提示してください。
• Cowork のセットアップでは、評価ビューアーの手順が省略されることがあります。明確にしておきます。Cowork でも Claude Code でも、テストの実行後は、スキルを自分で修正する前に、必ず人間が確認できるよう評価ビューアーを生成してください。独自の HTML ではなく generate_review.py を使用してください。人間からのフィードバックは最も価値のあるシグナルです。変更を始める前に、評価ビューアーを確認してもらいましょう。
• フィードバックの仕組みは異なります。実行中のサーバーがないため、ビューアーの「Submit All Reviews」ボタンを押すと、feedback.json がファイルとしてダウンロードされます。その後、ファイルから読み取ることができます（先にアクセス許可を求める必要がある場合があります）。
• パッケージ化は機能します。package_skill.py には Python とファイルシステムがあれば十分です。
• 既存のスキルを更新する場合：上記の claude.ai セクションにある更新ガイダンスに従ってください。
• 説明の最適化（run_loop.py / run_eval.py）は、ブラウザーではなくサブプロセス経由で claude -p を使用するため、Cowork でも問題なく機能するはずです。ただし、スキルの作成を完全に終え、ユーザーが十分な仕上がりだと納得するまで、実行は後回しにしてください。

---

依存関係

このスキルのスクリプトには、次のものが必要です。

• Python 3.10+ と pyyaml（pip install pyyaml）
• claude CLI — run_eval.py、run_loop.py、improve_description.py が使用します。これらはすべてシェルから claude -p を実行します。

ANTHROPIC_API_KEY は不要です。すべてのスクリプトは、セッション自身の Claude Code 認証を再利用します。

参考ファイル

agents/ ディレクトリには、専門のサブエージェント向けの手順が含まれています。該当するサブエージェントを起動する必要がある場合は、これらを読んでください。

• agents/grader.md — 出力に対するアサーションの評価方法
• agents/comparator.md — 2 つの出力をブラインドで A/B 比較する方法
• agents/analyzer.md — あるバージョンが別のバージョンを上回った理由を分析する方法

references/ ディレクトリには、追加のドキュメントがあります。

• references/schemas.md — evals.json、grading.json などの JSON 構造
• references/best-practices.md — スキル作成に関する包括的なリファレンス（フロントマターのルール、説明文の作成、段階的な情報開示、スクリプト設計、アンチパターン）。スキルのコンテンツ品質を作成またはレビューする際に読んでください。
• references/cross-agent-guide.md — プラットフォーム固有の検出パスと、エージェント間の互換性。Claude Code、Codex、Gemini CLI をまたいでスキルを動作させる必要がある場合に読んでください。

---

コアループの確認： 意図を把握 → スキルの草案を作成 → テスト用プロンプトを実行 → ユーザーと評価（generate_review.py + ベンチマーク）→ 改善 → 満足するまで繰り返す → パッケージ化。

TodoList がある場合は、「人間がテストケースを確認できるよう eval-viewer/generate_review.py を実行する」を追加して、必ず実行されるようにしてください。頑張ってください！