skill-creator

anthropics/skills の skills/skill-creator のフォークで、Windows 向けの修正（パイプリーダー、UTF-8 ファイル I/O、--project-root、実際のスキルのトリガー検出）と評価の妥当性に関する修正（同名のスキルがインストール済みの場合に起きる結果の汚染、ハーネスのエラーがスコア 0％として扱われる問題）が含まれています。アップストリームのコミット、パッチ、監査結果は、CtrlCarlitos/skills の vendor/skill-creator/ にあります。差し替えてそのまま使えます。名前と説明は同じです。 アップストリームの issue anthropics/skills#1827。

スキルクリエイター

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

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

• スキルで何を実現し、どのように実現するかをおおよそ決めます
• スキルの草案を書きます
• テスト用のプロンプトをいくつか作成し、claude-with-access-to-the-skill で実行します
• 結果を定性的・定量的に評価できるよう、ユーザーを支援します
  • 実行がバックグラウンドで進んでいる間に、定量評価がまだない場合は作成します（すでにある場合は、そのまま使うか、変更が必要だと思えば修正できます）。次に、その内容をユーザーに説明します（すでに評価があった場合は、既存の評価について説明します）
  • eval-viewer/generate_review.py スクリプトを使って結果を表示し、ユーザーが確認できるようにします。また、定量指標も確認できるようにします
• ユーザーによる結果の評価から得たフィードバックをもとにスキルを書き直します（定量ベンチマークから明らかな問題が見つかった場合も修正します）
• 納得できるまで繰り返します
• テストセットを拡張し、より大規模に再度試します

このスキルを使うときの役割は、ユーザーがこのプロセスのどの段階にいるのかを見極め、次の段階に進めるよう支援することです。たとえば、「X のスキルを作りたい」と言われた場合、意図を具体化し、草案やテストケースを作成し、評価方法を決め、すべてのプロンプトを実行して、反復的な改善を手伝えます。

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

もちろん、柔軟に対応してください。ユーザーが「たくさん評価を実行する必要はないから、一緒にアイデアを練りたいだけ」と言うなら、そのように進めてもかまいません。

スキルが完成したら（繰り返しになりますが、順序は柔軟です）、スキルのトリガーを最適化するための、専用スクリプトが用意されたスキル説明改善ツールを実行することもできます。

いいですか？　では、始めましょう。

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

スキルクリエイターは、コーディング用語への習熟度が幅広いユーザーに使われる可能性があります。ご存じないかもしれませんが（始まったのはごく最近なので、知らなくても無理はありません）、Claude の能力に刺激を受けて、配管工がターミナルを開いたり、親や祖父母が「npm のインストール方法」を Google で検索したりする傾向が今や見られます。一方で、ユーザーの大半はコンピューターにかなり詳しいでしょう。

そのため、状況を示す手がかりに注意して、伝え方を調整してください。基本的には、次のように考えてください。

• 「評価」と「ベンチマーク」は判断が分かれるところですが、使っても問題ありません
• 「JSON」や「アサーション」は、ユーザーが理解していると判断できる明確な手がかりがない限り、説明なしで使わないようにしてください

迷った場合は、用語を簡単に説明してかまいません。ユーザーに伝わるかどうか不確かなときは、短い定義を添えてください。

---

スキルの作成

意図の把握

まず、ユーザーの意図を理解します。現在の会話に、ユーザーがスキルとして記録したいワークフローがすでに含まれている場合があります（例：「これをスキルにして」と言われた場合）。その場合は、まず会話履歴から、使用したツール、手順の順序、ユーザーが行った修正、確認された入力／出力形式などの回答を抽出します。ユーザーに不足している情報を補ってもらい、次のステップに進む前に確認してください。

1. このスキルで Claude に何ができるようにしますか？
2. どのようなときにこのスキルを起動しますか？（ユーザーが使う表現や状況）
3. 想定される出力形式は何ですか？
4. スキルが機能することを確認するテストケースを用意しますか？客観的に検証可能な出力（ファイル変換、データ抽出、コード生成、固定されたワークフロー手順など）を扱うスキルには、テストケースが有効です。主観的な出力（文体、アートなど）を扱うスキルでは、多くの場合必要ありません。スキルの種類に応じて適切なデフォルトを提案しますが、決定はユーザーに委ねてください。

ヒアリングと調査

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

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

SKILL.md の作成

ユーザーへのヒアリングを踏まえて、次の要素を記入します。

• name：スキルの識別子
• description：起動するタイミングとスキルの機能。これは主な起動メカニズムです。スキルの機能と、使用すべき具体的な状況の両方を含めます。「使用するタイミング」に関する情報はすべてここに記載し、本文には書きません。注：現在の Claude は、役立つ場面でもスキルを使わない「起動不足」になりがちです。これを防ぐため、スキルの説明はやや積極的な表現にしてください。たとえば、「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つ起動します。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>
   

   これにより、各構成の 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> も渡します。

   Cowork／ヘッドレス環境： 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. フィードバックから一般化します。 ここで起きていることの大枠は、さまざまなプロンプトで何百万回も（文字どおり、あるいはそれ以上になるかもしれません）使えるスキルを作ろうとしている、ということです。ここでは、より早く進めるために、あなたとユーザーが何度も少数の例を反復しています。ユーザーはこれらの例を隅々まで把握しているので、新しい出力を素早く評価できます。しかし、あなたとユーザーが共同開発しているスキルがその例にしか使えないのであれば、役に立ちません。細かく過剰適合させる変更や、過度に制約的な 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 のフロントマターにある説明フィールドは、Claude がスキルを呼び出すかどうかを決める主な仕組みです。スキルを作成または改善した後、トリガーの精度を高めるために説明の最適化を提案してください。

ステップ 1：トリガー評価用クエリを生成する

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

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

クエリは現実的で、Claude Code または Claude.ai のユーザーが実際に入力しそうな内容にしてください。抽象的な依頼ではなく、具体的で詳細な依頼にします。たとえば、ファイルパス、ユーザーの仕事や状況に関する個人的な背景情報、列名と値、会社名、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. ユーザーはクエリの編集、トリガーすべきかどうかの切り替え、項目の追加・削除を行ってから、「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

現在のセッションを動かしている、システムプロンプト内のモデル ID を使用してください。これにより、トリガーテストでユーザーが実際に体験する内容を再現できます。

実行中は定期的に出力の末尾を確認し、現在のイテレーションとスコアの状況をユーザーに伝えます。

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

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

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

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

ステップ 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 でも基本的なワークフローは同じです（下書き → テスト → レビュー → 改善 → 繰り返し）。ただし、Claude.ai にはサブエージェントがないため、一部の進め方が変わります。以下を調整してください。

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

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

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

反復の流れ：これまでと同じく、スキルを改善し、テストケースを再実行して、フィードバックを求めます。途中のブラウザーレビューがないだけです。環境にファイルシステムがある場合は、結果をイテレーションごとのディレクトリに整理してもかまいません。

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

エージェント間の評価の同等性（CtrlCarlitos/skills#10）：run_eval.py／run_loop.py は --harness codex と --harness opencode もサポートしています（デフォルトは引き続き claude）。それぞれ、該当するハーネス独自の非対話型 CLI（codex exec／opencode run）を実行し、そのハーネス独自のイベント形式でスキルの起動を検出します。どちらも Claude の Skill ツールのような形式ではありません。--harness antigravity はありません。Antigravity は、Codex／OpenCode のようにプロジェクト内の一時的なスキルを確実に検出しません（実環境で確認済み）。また、実用的なアダプターを作るには、評価クエリのたびにユーザーの実際のグローバルスキルディレクトリへ書き込む必要がありますが、このフォークではそのような処理をユーザーに知らせずに行いません。Antigravity 用のスキルを評価する場合は、未テストのハーネスとして扱い、スコアがそのまま適用されると主張せず、その旨を伝えてください。opencode 独自の CLI には、一部の環境で深刻な信頼性の問題があることが確認されています（テスト対象のスキルとは無関係に、出力をまったく返さずに停止することがあります）。そこで報告されるエラー率が claude／codex より高い場合は、説明ではなく、この問題が原因である可能性があります。vendor/skill-creator/DISPOSITION.md を参照してください。

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

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

既存のスキルの更新：ユーザーは新しいスキルの作成ではなく、既存のスキルの更新を依頼している場合があります。その場合：

• 元の名前を維持してください。 スキルのディレクトリ名と name frontmatter フィールドを確認し、そのまま使用してください。たとえば、インストール済みのスキルが research-helper の場合は、research-helper-v2 ではなく research-helper.skill を出力します。
• 編集前に書き込み可能な場所へコピーしてください。 インストール済みのスキルのパスは読み取り専用の場合があります。/tmp/skill-name/ にコピーしてそこで編集し、そのコピーからパッケージ化してください。
• 手動でパッケージ化する場合は、まず /tmp/ に一時保存し、その後、出力ディレクトリにコピーしてください。直接書き込もうとすると、権限エラーになることがあります。

---

Cowork 固有の手順

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

• サブエージェントを利用できるため、テストケースを並行して実行し、ベースラインを実行して採点するなど、メインのワークフローはすべて機能します。（ただし、タイムアウトなどの深刻な問題が発生した場合は、テスト用プロンプトを並行ではなく順番に実行してもかまいません。）
• ブラウザーも画面表示機能もないため、評価ビューアーを生成するときは、サーバーを起動する代わりに --static <output_path> を使って、単体で動作する HTML ファイルを書き出してください。その後、ユーザーがクリックしてブラウザーで HTML を開けるリンクを提示してください。
• どういうわけか、Cowork の環境では、テストの実行後に Claude が評価ビューアーを生成しない傾向があるようです。念のため繰り返します。Cowork でも Claude Code でも、テストの実行後は、スキルを自分で見直して修正を試みる前に、必ず評価ビューアーを生成し、人が例を確認できるようにしてください。独自の凝った HTML コードを書くのではなく、generate_review.py を使ってください。あらかじめご了承ください。ここからは大文字で強調します。自分で入力を評価する前に、必ず評価ビューアーを生成してください。できるだけ早く人に確認してもらいましょう！
• フィードバックの仕組みは異なります。サーバーが起動していないため、ビューアーの「すべてのレビューを送信」ボタンを押すと、feedback.json がファイルとしてダウンロードされます。そこから読み取れます（事前にアクセス権をリクエストする必要がある場合があります）。
• パッケージ化は機能します。package_skill.py に必要なのは Python とファイルシステムだけです。
• run_loop.py／run_eval.py を使った説明の最適化は、ブラウザーではなくサブプロセス経由で claude -p を使うため、Cowork でも問題なく動作するはずです。ただし、スキルの作成を完全に終え、ユーザーが良い状態だと合意するまでは行わないでください。
• 既存のスキルの更新：新しいスキルの作成ではなく、既存のスキルの更新をユーザーが求めている場合があります。その場合は、上記の claude.ai セクションにある更新ガイダンスに従ってください。

---

参考ファイル

agents/ ディレクトリには、専門分野に特化したサブエージェント向けの指示があります。該当するサブエージェントを起動するときに参照してください。

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

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

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

---

重要なループを、念のためもう一度強調しておきます。

• スキルの目的を把握する
• スキルを作成または編集する
• スキルにアクセスできる Claude を使って、テスト用プロンプトを実行する
• ユーザーと一緒に出力を評価する：
  • benchmark.json を作成し、eval-viewer/generate_review.py を実行して、ユーザーが確認できるようにする
  • 定量評価を実行する
• あなたとユーザーが納得するまで繰り返す
• 最終的なスキルをパッケージ化し、ユーザーに返す

忘れないように、可能であれば TodoList に手順を追加してください。Cowork を使用している場合は、必ず TodoList に「テストケースを人が確認できるよう、evals JSON を作成し、eval-viewer/generate_review.py を実行する」と記載してください。

頑張ってください！