skill-creator

スキル作成ツール

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

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

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

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

一方、ユーザーがすでにスキルの草案を持っている場合は、評価と反復改善の段階から始められます。

もちろん、柔軟に対応することが大切です。たとえば、ユーザーが「たくさん評価を実行する必要はないので、気軽に相談に乗ってほしい」と言うなら、そのように対応できます。

スキルが完成した後は（繰り返しになりますが、順番は柔軟です）、別の専用スクリプトで実行できるスキル説明の改善ツールを使って、スキルが呼び出される条件を最適化することもできます。

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

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

スキル作成ツールは、コーディング用語への理解度がさまざまな人に使われる可能性があります。ご存じないかもしれませんが（ご存じなくても無理はありません。始まったのはごく最近です）、最近では Claude の力に刺激され、配管工がターミナルを開き、親や祖父母が「npm のインストール方法」を検索するようになっています。一方で、ユーザーの大半は、コンピューターに関する知識をある程度持っているでしょう。

そのため、文脈から適切な言い回しを判断するよう心がけてください。標準的な場合の目安としては、次のとおりです。

• 「評価」と「ベンチマーク」は境界的な用語ですが、使用しても問題ありません
• 「JSON」や「アサーション」については、ユーザーがそれらを知っていることを示す明確な手がかりがない限り、説明なしで使うのは避けてください

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

---

スキルの作成

意図を把握する

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

1. このスキルによって、Claude に何をできるようにしますか？
2. どのようなときにこのスキルを呼び出しますか？（ユーザーが使う表現や状況）
3. 期待する出力形式は何ですか？
4. スキルが正しく機能することを確認するため、テストケースを用意しますか？客観的に検証できる出力（ファイル変換、データ抽出、コード生成、固定された手順など）を扱うスキルでは、テストケースを用意するのが効果的です。主観的な出力（文体、アートなど）を扱うスキルでは、多くの場合、テストケースは不要です。スキルの種類に応じて適切な初期案を提案しつつ、最終的にはユーザーに選んでもらいます。

インタビューと調査

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

利用可能な MCP を確認してください。調査（ドキュメントの検索、類似スキルの発見、ベストプラクティスの確認）に役立つ場合は、サブエージェントが利用可能なら並行して調査し、利用できない場合はその場で調査してください。ユーザーの負担を減らせるよう、背景情報を準備してください。

新規スキルや大幅に変更するスキルを下書きする前に、references/quality-playbook.md を読んでください。これを使って、主要なスキルの種類を1つ選び、そのスキルに落とし穴、スクリプト、セットアップ状態、フック、検証が必要かどうかを判断してください。また、サポートファイルに記載すべき詳細で SKILL.md を肥大化させないようにしてください。

エージェントのワークフロー、デリバリー、自動化、PR、高影響度のスキルについては、skill-lifeguard の Reliable Skill Contract も適用してください。具体的には、否定的な例、検証チェックポイント、機械で確認可能な完了条件、ログからパッチへのループを伴うリプレイまたはスモークテスト用フック、ドリフトの兆候の検出を含めてください。

SKILL.md の作成

ユーザーへのインタビューをもとに、以下の項目を記入してください。

• name：スキルの識別子
• description：いつ起動するか、何をするか。これは主要な起動メカニズムです。スキルが行うことと、使用すべき具体的な状況の両方を含めてください。「いつ使うか」に関する情報はすべてここに記載し、本文には含めないでください。注：現在 Claude はスキルを「undertrigger」し、役立つ場面でも使わない傾向があります。これを防ぐため、スキルの説明は少し「強め」にしてください。たとえば、「Anthropic の社内データを表示する、シンプルで高速なダッシュボードの作成方法」ではなく、「Anthropic の社内データを表示する、シンプルで高速なダッシュボードの作成方法です。ユーザーがダッシュボード、データ可視化、社内指標に言及した場合や、明示的に『ダッシュボード』と依頼していなくても、会社のデータを何らかの形で表示したいと考えている場合は、必ずこのスキルを使用してください」と記載するのがよいでしょう。
• compatibility：任意の環境要件テキスト（1～500文字）。Agent Skills specification で定義されています。Spellbook のランタイムフィルターは、文字列値の metadata.spellbook-runtimes 拡張に、スペース区切りの claude_code、codex、portable の ID を使って記載してください。

  compatibility: Requires Codex with native subagent support.
  metadata:
    spellbook-runtimes: "codex"
  

ランタイムメタデータを省略した場合、レジストリでは unspecified となり、インストールは制限されません。ただし、移植可能であることを証明するものではありません。従来の compatibility.runtimes マッピングも引き続き読み取れますが、新しいスキルでは標準の文字列とメタデータの形式を使用してください。

• スキルの残りの部分 :)
• 高価値なワークフロースキル向けの Reliable Skill Contract：禁止される動作、チェックポイント、完了条件、スモークテスト用フック、ドリフトの兆候。

スキル作成ガイド

スキルの構成

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つ起動してください。一方にはスキルを使用させ、もう一方には使用させません。これは重要です。スキルありの実行を先に始めて、後からベースラインに戻ることはしないでください。すべてを同時に起動して、ほぼ同じタイミングで完了するようにしてください。

スキルありの実行：

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 には、単に「eval-0」とするのではなく、テスト内容に基づいた説明的な名前を付けてください。ディレクトリ名にもこの名前を使用してください。このイテレーションで新規または変更済みの eval プロンプトを使う場合は、各新しい eval ディレクトリにこれらのファイルを作成してください。前のイテレーションから引き継がれると思い込まないでください。

{
  "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、時間、トークン数を示す benchmark.json と benchmark.md が生成され、平均 ± 標準偏差と差分が含まれます。benchmark.json を手動で作成する場合は、ビューアーが想定する正確なスキーマについて references/schemas.md を参照してください。 各 with_skill バージョンを、対応する baseline バージョンより前に配置してください。

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

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 ファイルを書き出してください。ユーザーが「すべてのレビューを送信」をクリックすると、フィードバックが feedback.json ファイルとしてダウンロードされます。ダウンロード後、次のイテレーションで読み込めるように、feedback.json を workspace ディレクトリにコピーしてください。

注：ビューアーの作成には 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 などです。ちょっとした背景説明も加えます。小文字で書かれていたり、省略形や誤字、くだけた表現が含まれていたりするものもあるでしょう。さまざまな長さを混ぜ、明確に判断できるものより、境界ケースに重点を置いてください（ユーザーが承認する機会があります）。

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

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

トリガーされるべきクエリ（8～10 件）では、網羅性を意識してください。同じ意図をさまざまに表現します。かしこまった表現とくだけた表現を混ぜてください。ユーザーがスキル名やファイル形式を明示していなくても、明らかにそのスキルが必要なケースを含めます。一般的でないユースケースや、別のスキルと競合してもこのスキルを選ぶべきケースも加えてください。

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

避けるべき重要な点は、トリガーされるべきでないクエリを明らかに無関係な内容にしないことです。PDF スキルの否定テストに "フィボナッチ関数を書いて" を使うのは簡単すぎて、何も検証できません。否定ケースは、本当に判断の難しいものにしてください。

ステップ 2：ユーザーにレビューしてもらう

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

1. assets/eval_review.html からテンプレートを読み込みます。
2. プレースホルダーを置き換えます。
   • __EVAL_DATA_PLACEHOLDER__ → 評価項目の JSON 配列（JavaScript の変数代入として使うため、前後に引用符は付けません）
   • __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 を返します。

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

トリガーの仕組みを理解すると、より良い評価クエリを設計できます。スキルは、名前と説明を含む 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 を使用している場合は省略してください。

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

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

---

Cowork 固有の手順

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

• サブエージェントを利用できるため、基本的なワークフロー（テストケースを並列で起動し、ベースラインを実行して採点するなど）はすべて機能します。（ただし、タイムアウトによる深刻な問題が発生した場合は、テスト用プロンプトを並列ではなく順番に実行してもかまいません。）
• ブラウザーやディスプレイは利用できないため、評価ビューアーを生成するときは --static <output_path> を使って、サーバーを起動する代わりにスタンドアロンの HTML ファイルを書き出してください。その後、ユーザーがクリックしてブラウザーで HTML を開けるリンクを提示します。
• 理由は不明ですが、Cowork のセットアップでは、テスト実行後に Claude が評価ビューアーを生成しない傾向があるようです。念のため繰り返します。Cowork と Claude Code のどちらを使っていても、テストの実行後は必ず generate_review.py を使って評価ビューアーを生成してください（独自の HTML コードを書かないでください）。スキルを自分で見直して修正する前に、人間が事例を確認できるようにします。先にお詫びしておきますが、ここは大文字で強調します。入力を自分で評価する前に、評価ビューアーを生成してください。できるだけ早く人間に確認してもらいましょう。
• フィードバックの方法は異なります。サーバーが稼働していないため、ビューアーの「すべてのレビューを送信」ボタンを押すと、feedback.json がファイルとしてダウンロードされます。そのファイルを読み込んでください（先にアクセス許可を求める必要がある場合があります）。
• パッケージ化は機能します。package_skill.py に必要なのは Python とファイルシステムだけです。
• 説明文の最適化（run_loop.py ／ run_eval.py）は、ブラウザーではなくサブプロセス経由で claude -p を使うため、Cowork でも問題なく動作するはずです。ただし、スキルの作成を完全に終え、ユーザーが十分な状態だと合意するまでは実行しないでください。

---

参考ファイル

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

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

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

• references/schemas.md — evals.json、grading.json などの JSON 構造
• references/quality-playbook.md — スキルタイプの選択、トリガーの説明ルール、注意点、段階的な情報開示、検証チェック

---

念のため、要点となる基本的な流れをもう一度説明します。

• スキルの内容を把握する
• スキルを作成または編集する
• テスト用プロンプトで claude-with-access-to-the-skill を実行する
• ユーザーと一緒に出力を評価する：
  • benchmark.json を作成し、eval-viewer/generate_review.py を実行して、ユーザーが出力を確認できるようにする
  • 定量評価を実行する
• ユーザーと納得できるまで繰り返す
• 最終版のスキルをパッケージ化してユーザーに返す

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

頑張ってください！