skill-creator

スキルクリエーター

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

大まかな手順は次のとおりです。

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

このスキルを使う際のあなたの役割は、ユーザーがこのプロセスのどの段階にいるかを見極め、各段階を進められるよう支援することです。たとえば、ユーザーが「X 用のスキルを作りたい」と言った場合、意図を明確にする手助けをし、草案の作成、テストケースの作成、評価方法の検討、すべてのプロンプトの実行、そして反復作業を支援できます。

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

もちろん、ユーザーが「たくさん評価を実行する必要はないので、気軽に相談に乗ってほしい」と言うような場合は、柔軟に対応してください。

スキルが完成したら（ただし、進める順番は柔軟です）、スキルの説明文を改善するツールも実行できます。トリガーされやすさを最適化するための、別個のスクリプトが用意されています。

いいですか？いいですね。

ユーザーとのコミュニケーション

スキルクリエーターは、コーディング用語に詳しい人から不慣れな人まで、さまざまなユーザーが使う可能性があります。最近始まったばかりの動きなのでご存じないかもしれませんが、Claude の能力に刺激を受けた配管工がターミナルを開いたり、親や祖父母が「npm のインストール方法」を Google で検索したりするようになっています。一方で、ユーザーの多くはコンピューターにかなり詳しいでしょう。

そのため、どのような表現が適切か判断する際は、文脈の手掛かりに注意してください。標準的な場合の目安として、次の点を参考にしてください。

• 「評価」や「ベンチマーク」は判断が分かれる用語ですが、使っても問題ありません
• 「JSON」や「アサーション」は、ユーザーがそれらを知っていると確信できる手掛かりがある場合に限り、説明なしで使うようにしてください

迷った場合は、用語を簡潔に説明してもかまいません。ユーザーが理解できるか不明な場合は、短い定義を添えてください。

---

スキルの作成

意図を把握する

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

1. このスキルで AI エージェントに何をできるようにしますか？
2. どのようなときにこのスキルを起動しますか？（ユーザーが使うフレーズや状況）
3. 期待する出力形式は何ですか？
4. スキルが正しく動作することを検証するテストケースを用意しますか？客観的に検証できる出力（ファイル変換、データ抽出、コード生成、固定されたワークフロー手順など）を生成するスキルには、テストケースが役立ちます。主観的な出力（文体、アートなど）の場合は、不要なこともよくあります。スキルの種類に応じて適切な既定案を提案しつつ、最終的な判断はユーザーに任せてください。
5. このスキルはどのツール向けですか？（Claude Code、Cursor、または両方）

対象プラットフォーム

SKILL.md の形式は Claude Code と Cursor で同一です。同じ YAML フロントマター、同じディレクトリ構造を使用します。主な違いは次のとおりです。

• Claude Code は .claude/skills/ からスキルを検出します
• Cursor は .cursor/skills/、.agents/skills/、~/.cursor/skills/、.claude/skills/（旧形式）からスキルを検出します
• クロスプラットフォーム：両方のツールで検出されるように、スキルを .agents/skills/ に配置します
• Cursor 専用のフィールド：フロントマターに disable-model-invocation: true を設定すると、/skill-name 経由でのみスキルを呼び出せるようになります（自動トリガーされません）

両方のプラットフォーム向けにスキルを作成する場合は、スキル本文でツール固有の機能（Claude の Skill ツールと Cursor の /skill-name による呼び出しなど）に言及しないでください。

ヒアリングと調査

エッジケース、入力／出力形式、サンプルファイル、成功基準、依存関係について、積極的に質問してください。この部分を固めるまでは、テスト用プロンプトの作成を始めないでください。

利用可能な MCP を確認してください。調査（ドキュメントの検索、類似スキルの確認、ベストプラクティスの調査）に役立つ場合は、利用可能であればサブエージェントを使って並行して調査し、そうでなければインラインで調査してください。ユーザーの負担を軽減できるよう、関連する情報をあらかじめ用意してください。

SKILL.md の作成

ユーザーへのヒアリングに基づいて、次の項目を記入してください。

• name：スキルの識別子
• description：いつ起動するか、何をするか。これは主なトリガーの仕組みです。スキルが行うことと、使用すべき具体的な状況の両方を含めてください。「いつ使うか」に関する情報はすべてここに記載し、本文には記載しないでください。注：現在、AI エージェント（Claude と Cursor の両方）はスキルを「起動しすぎない」傾向があり、役立つ場面でも使わないことがあります。これを防ぐため、スキルの説明は少し「積極的」にしてください。たとえば、「Anthropic の社内データを表示するシンプルで高速なダッシュボードの構築方法」とする代わりに、「Anthropic の社内データを表示するシンプルで高速なダッシュボードの構築方法です。ユーザーがダッシュボード、データ可視化、社内指標に言及した場合や、明示的に『ダッシュボード』を求めていなくても、会社のデータを何らかの形で表示したい場合は、必ずこのスキルを使ってください」とすることができます。
• compatibility：必要なツール、依存関係（任意。必要となることはまれです）
• スキルの残りの項目 :)

スキル作成ガイド

スキルの構成

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）：常にコンテキスト内にあります（約 100 語）
2. SKILL.md の本文：スキルが起動するたびにコンテキスト内に読み込まれます（理想的には 500 行未満）
3. 同梱リソース：必要に応じて読み込まれます（制限なし。スクリプトは読み込まずに実行できます）

これらの語数はおおよその目安です。必要であれば、自由に長くしてください。

主なパターン：

• SKILL.md は 500 行未満にしてください。この上限に近づいている場合は、階層をもう 1 段追加し、スキルを使用するモデルが次に参照すべき場所を明確に案内してください。
• SKILL.md から参照ファイルへの参照を明確に記載し、いつ読むべきかを案内してください
• 大きな参照ファイル（300 行超）には目次を含めてください

ドメインの整理：スキルが複数のドメイン／フレームワークに対応する場合は、バリエーションごとに整理してください。

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

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

意外性のない原則

言うまでもありませんが、スキルにマルウェア、エクスプロイトコード、システムのセキュリティを侵害する可能性のあるコンテンツを含めてはいけません。スキルの内容が説明と異なり、ユーザーを驚かせるものであってはなりません。誤解を招くスキルや、不正アクセス、データの持ち出し、その他の悪意ある活動を助長するスキルの作成依頼には応じないでください。ただし、「XYZ になりきる」といったものは問題ありません。

作成パターン

指示では命令形を優先してください。

出力形式の定義 - 次のように記述できます。

## Report structure
ALWAYS use this exact template:
# [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

執筆スタイル

強引で堅苦しい「必須」事項を並べるのではなく、なぜそれが重要なのかをモデルに説明するようにします。心の理論を活用し、特定の例に極端に限定せず、汎用的なスキルになるようにしてください。まずドラフトを書き、それを新鮮な視点で見直して改善します。

テストケース

スキルのドラフトを書いたら、現実的なテストプロンプトを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つを開始します。

Claude Code の場合（サブエージェントあり）：すべての実行がほぼ同時に終わるよう、同じターンにすべての実行を開始します。スキル使用時の実行を先に始めて、ベースラインを後から始めることは避けてください。

Cursor の場合（サブエージェントなし）：テストケースを順番に実行します。スキルを読み、各テストプロンプトに対してその指示に従ってください。これは厳密性に欠けますが、人によるレビューで補います。

スキル使用時の実行：

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
}

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

Step 4: 採点 — カスタムスクリプトではなく、agents/grader.md を使用します

プログラムによるチェック（ファイルの存在、行数、文字列の一致）は補助として有用ですが、構造上の準拠しか確認できません。採点エージェントは、スクリプトでは確認できない内容の品質、主張の検証、誤った安心感を生む弱いアサーションを確認します。スキルがすべてのファイルを正しい場所に生成しても、内容がひどい場合があります。それを見つけるのが採点エージェントです。すべての実行について grading.json が存在するまで、ビューアーやベンチマークを生成しないでください。

すべての実行が完了したら、次の手順に進みます。

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>
   

   これにより、各構成の pass_rate、time、tokens を含む benchmark.json と benchmark.md が生成され、平均 ± 標準偏差と差分も記録されます。benchmark.json を手動で生成する場合は、ビューアーが想定する正確なスキーマについて references/schemas.md を参照してください。 各 with_skill バージョンを、対応するベースラインバージョンより先に配置してください。

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

4. 定性的な出力と定量データの両方を使ってビューアーを起動する：

   nohup python <skill-creator-path>/eval-viewer/generate_review.py \
     <workspace>/iteration-N \
     --skill-name "my-skill" \
     --benchmark <workspace>/iteration-N/benchmark.json \
     > /dev/null 2>&1 &
   VIEWER_PID=$!
   

   反復 2 以降では、--previous-workspace <workspace>/iteration-<N-1> も渡してください。

   ヘッドレス環境： webbrowser.open() を利用できない場合、または環境にディスプレイがない場合は、サーバーを起動する代わりに --static <output_path> を使用して、スタンドアロンの HTML ファイルを書き出してください。ユーザーが「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"
}

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

作業が終わったら、ビューアーサーバーを停止します。

kill $VIEWER_PID 2>/dev/null

---

スキルの改善

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

改善の考え方

1. フィードバックから一般化します。 ここで起きていることの全体像は、何百万回も（文字どおりかもしれませんし、もっと多いかもしれません）さまざまなプロンプトで使えるスキルを作ろうとしている、ということです。ここでは、作業を速く進めるため、あなたとユーザーは少数の例を何度も繰り返し試しています。ユーザーはそれらの例を熟知しているので、新しい出力をすばやく評価できます。しかし、あなたとユーザーが共同開発しているスキルがその例にしか使えないのであれば、役に立ちません。細かく過剰適合する変更や、過度に制約の厳しい「必ずこうする」という指示を加えるのではなく、解決しにくい問題がある場合は、別の比喩を使ったり、異なる作業パターンを提案したりしてみてください。試すコストは比較的低く、優れた方法が見つかるかもしれません。

2. プロンプトを簡潔に保ちます。 役に立っていない指示を削除してください。最終出力だけでなく、トランスクリプトも必ず読んでください。スキルによってモデルが非生産的な作業に多くの時間を費やしているようであれば、その原因になっている指示を削除して、どうなるか試してみてください。

3. 理由を説明します。 モデルに求めることすべてについて、その理由を説明するよう努めてください。現在のLLMは賢く、他者の考えを推し量る能力にも優れています。適切な仕組みを与えれば、単に指示を機械的にこなすだけでなく、実際に成果を生み出せます。ユーザーのフィードバックが簡潔だったり、いら立ちを含んでいたりしても、課題の本質や、ユーザーがそのように書いた理由、実際に書かれた内容を理解し、その理解を指示に反映してください。大文字で「必ず」や「絶対に」と書いたり、極端に厳格な構成を使ったりしていることに気づいたら、それは注意信号です。可能であれば、理由を説明する形に言い換え、求めていることがなぜ重要なのかモデルが理解できるようにしてください。その方が、人間味があり、強力で、効果的なアプローチになります。

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：トリガー評価用クエリの生成

トリガーすべきクエリと、トリガーすべきでないクエリを混ぜて、評価用クエリを20件作成します。JSON として保存します。

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

クエリは現実的で、Claude Code または Cursor のユーザーが実際に入力しそうなものにしてください。抽象的な依頼ではなく、具体的で詳細が十分に含まれた依頼にします。たとえば、ファイルパス、ユーザーの仕事や状況に関する個人的な背景、列名と値、会社名、URL などを含めます。少し背景情報を加えます。小文字で書かれたもの、省略形やタイプミスを含むもの、くだけた表現なども混ぜてください。長さにも変化をつけ、明白なケースよりも境界的なケースに重点を置きます（ユーザーが確認する機会を得られます）。

悪い例："Format this data"、"Extract text from PDF"、"Create a chart"

良い例："ok so my boss just sent me this xlsx file (its in my downloads, called something like 'Q4 sales final FINAL v2.xlsx') and she wants me to add a column that shows the profit margin as a percentage. The revenue is in column C and costs are in column D i think"

トリガーすべきクエリ（8～10件）では、網羅性を考慮してください。同じ意図を異なる表現で伝えるクエリを用意します。かしこまった表現とくだけた表現の両方を含めてください。ユーザーがスキル名やファイル形式を明示していなくても、明らかにこのスキルが必要なケースも含めます。珍しいユースケースや、別のスキルと競合するものの、こちらのスキルを優先すべきケースも盛り込んでください。

トリガーすべきでないクエリ（8～10件）では、最も価値が高いのは、惜しいケースです。スキルと同じキーワードや概念を含んでいても、実際には別の対応が必要なクエリです。隣接する分野、単純なキーワード一致ではトリガーされそうな曖昧な表現、スキルが扱う内容に触れていても別のツールのほうが適切な状況などを考えてください。

避けるべき重要な点は、トリガーすべきでないクエリを、明らかに無関係なものにすることです。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：最適化ループを実行する

API キーの前提条件： 実行前に認証情報が読み込まれていることを確認します。上記の API 認証情報 セクションの手順に従い、環境変数を確認するか、.env を source するか、ファイルがない場合はユーザーに作成を依頼します。

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

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

source .env && python -m scripts.run_loop \
  --eval-set <path-to-trigger-eval.json> \
  --skill-path <path-to-skill> \
  --model ${SKILL_MODEL} \
  --platform <claude|cursor> \
  --max-iterations 5 \
  --verbose

.env の $SKILL_MODEL を使用します。設定されていない場合は、システムプロンプトにあるモデル ID（現在のセッションを実行しているモデル）にフォールバックし、トリガーテストがユーザーの実際の体験に合うようにします。Cursor スキルの場合は --platform cursor を設定します（claude -p CLI の代わりに LLM シミュレーションを使用します）。

実行中は、定期的に出力を確認し、現在の反復回数とスコアの状況をユーザーに伝えます。

この処理では、最適化ループ全体が自動的に実行されます。評価セットをトレーニング用 60％、保留テスト用 40％に分割し、現在の説明を評価します（信頼できるトリガー率を得るため、各クエリを 3 回実行します）。次に、失敗したケースに基づいて改善案を提案するよう、拡張思考を使って Claude に依頼します。新しい説明をトレーニング用とテスト用の両方で再評価し、最大 5 回まで反復します。完了すると、各反復の結果を示す HTML レポートをブラウザーで開き、過学習を避けるため、トレーニングスコアではなくテストスコアで選ばれた best_description を含む JSON を返します。

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

トリガーの仕組みを理解すると、より適切な評価クエリを設計できます。スキルは、名前と説明を含むエージェントの available_skills リストに表示され、エージェントはその説明に基づいてスキルを参照するかどうかを判断します。重要なのは、AI エージェントは自力で簡単に処理できないタスクに対してのみスキルを参照するという点です。「この PDF を読んで」のような単純な一段階のクエリは、説明に完全に一致していても、エージェントが基本的なツールで直接処理できるため、スキルがトリガーされないことがあります。一方、複雑なタスクや複数の手順を要するタスク、専門的なタスクでは、説明が一致すればスキルが確実にトリガーされます。

つまり、評価クエリは、Claude が実際にスキルを参照すると役立つ程度に内容のあるものにする必要があります。「ファイル X を読む」のような単純なクエリは、説明の質にかかわらずスキルをトリガーしないため、テストケースとして適していません。

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

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

---

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

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

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

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

---

Cursor 固有の手順

Cursor 内で実行する場合：

• 基本的なワークフローは同じです。草案を作成し、テストし、レビューし、改善する作業を繰り返します。
• Cursor にはサブエージェントがありません。テストケースは順番に実行します。スキルの SKILL.md を読み、その指示に従ってテストプロンプトを一つずつ自分で実行してください。
• すべての Python スクリプト（run_eval、run_loop、improve_description、package_skill）で --platform cursor を使用してください。
• 説明の最適化では、CLI テストではなく LLM シミュレーションを使用します。このシミュレーションでは、「このクエリに対して、このスキルを呼び出しますか？」とモデルに尋ねます。説明を比較する際の方向性を把握するには正確ですが、Cursor の実際の実行時の動作を完全に予測できるものではありません。
• Cursor は disable-model-invocation: true フロントマターのフィールドに対応しています。/skill-name 経由でのみ呼び出し可能にし、エージェントによる自動起動を無効にするスキルには、このフィールドを設定してください。
• ブラインド比較にはサブエージェントが必要です。Cursor では省略してください。
• パッケージ化の手順は同じです。生成されたスキルフォルダーを .cursor/skills/（クロスプラットフォームの場合は .agents/skills/）に配置してください。
• 評価ビューアーを生成する際、Cursor 環境で webbrowser.open() を利用できない場合は、--static <output_path> を使用してください。

---

参照ファイル

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

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

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

• references/schemas.md — evals.json、grading.json などの JSON 構造

---

念のため、強調を兼ねて基本的なループをもう一度説明します：

• スキルの目的を把握する
• スキルの草案を作成するか、編集する
• スキルを利用できる状態でエージェントをテストプロンプトに対して実行する
• ユーザーと一緒に出力を評価する：
  • benchmark.json を作成し、eval-viewer/generate_review.py を実行して、ユーザーがレビューしやすいようにする
  • 定量評価を実行する
• あなたとユーザーが納得するまで繰り返す
• 最終的なスキルをパッケージ化し、ユーザーに返す

忘れないよう、TodoList があれば手順を追加してください。

頑張ってください！