custom-skill-creator

スキルクリエーター

新しいスキルの作成と、反復的な改善を行うためのスキルです。

⚠️ 完了条件：このワークフローは6つのフェーズで構成されています：意図 → 下書き → テストと評価 → 反復 → 説明の最適化 → パッケージ化。説明の最適化をユーザーに提案するまでは、ワークフローは完了していません。まだそのステップに到達していない場合は、作業が残っています。

始める前に、ユーザーがこのプロセスのどの段階にいるのか、また、残っているフェーズは何かを特定してください。このファイルの後半にあるフェーズも含めてください。残りのフェーズをすべて挙げられるようになるまでは、作業を開始しないでください。

大まかに言うと、スキルの作成プロセスは次のとおりです。

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

このスキルを使う際のあなたの役割は、ユーザーがこのプロセスのどこにいるかを把握し、各段階を進められるよう支援することです。たとえば、「X のスキルを作りたい」と言われた場合、意図を明確にする手助けをし、下書きやテストケースを作成し、評価方法を相談し、すべてのプロンプトを実行して、必要に応じて繰り返すことができます。

一方、ユーザーがすでにスキルの下書きを用意している場合は、評価と反復の段階から始められます。

もちろん、常に柔軟に対応してください。ユーザーが「評価をたくさん実行しなくていいから、気軽に相談したい」と言うなら、そのように対応できます。

そして、ユーザーがスキルの動作に満足した後にも、重要なステップがひとつ残っています。それは 説明の最適化 です。説明欄はClaudeがスキルを呼び出すかどうかを決める主要な仕組みであり、説明を最適化するための専用の反復プロセスがあります。これを省略しないでください。説明が適切でなければ、よくできたスキルでも呼び出されることはありません。

わかりましたか？ よし、では始めましょう。

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

スキルクリエーターは、コーディング用語への習熟度が幅広い人々に使われる可能性があります。ご存じないかもしれませんが（始まったのはごく最近なので当然ですが）、最近は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
Use this 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

ライティングスタイル

強い口調で「必ず」と求めるのではなく、なぜそれが重要なのかをモデルに説明するようにしてください。心の理論を活用し、特定の例に限定されない、幅広く応用できるスキルを目指してください。まず草案を書き、少し時間をおいて見直し、改善してください。

エージェントの認知に合わせた設計

とても重要なのに、多くの人が気づいていないことがあります。エージェントが SKILL.md を読むとき、ファイル全体を均等に扱うわけではありません。次の3つの要因が影響します。

• 初頭効果：最初の約1,000トークンは「中核となるミッション」として扱われます。それ以降は「実装の詳細」として、次第に重みが薄れます。これはプロンプトの問題ではなく、Transformer の注意機構の働きによるものです。
• 貪欲な実行：エージェントは実行可能な手順を見つけると、「読む」ループより「実行する」ループが優先されます。読むのをやめて作業を始めるため、ファイルの最後まで到達しないことがよくあります。
• 中間部分の喪失：長いドキュメントの中間約40％は、どれほど重要な内容でもエージェントの動作への影響が最も弱くなります。これは文献でも十分に報告されており、すべてのモデルに影響します。

その結果、6フェーズのパイプラインでは、エージェントはフェーズ1～3を忠実に実行し、フェーズ4～6を飛ばしてしまいます。指示が書かれていないからではなく、300行目にあるからです。

SKILL.md ファイルはドキュメントではなく、動作の契約です。 次の対策を取り入れて設計してください。

1. パイプライン確認ゲート — エージェントが何らかの操作を行う前に、最後のフェーズを含むすべてのフェーズを認識したことを確認してください。フェーズ5の内容を言えないなら、フェーズ5を読んでいません。

   > This workflow has 4 phases: Research → Draft → Review → Publish.
   > It is incomplete until Publish is done. Confirm all phases before starting.
   

2. 最初に最後の工程に触れる — 最初の10行で、最終フェーズを明示しながら「完了」とはどのような状態かに触れてください。これにより、注意機構が先を見通すようになります。

   > This skill is not finished until the cleanup report is generated (Phase 4).
   

3. 中断しやすい地点にインラインチェックポイントを置く — エージェントが自然に「終わった」と感じる瞬間（主要な作業は終わったものの、クリーンアップや統合が残っている段階）に、残りの作業を明示する停止指示を挿入してください。

   ⚠️ Checkpoint: If you haven't generated the report yet, you're not done.
   Check remaining phases before proceeding.
   

   エージェントが「もう終わりだ」と感じる瞬間、つまり通常は主要な成果物を作成した後、統合、レビュー、パッケージ化に進む前に、これらを配置してください。

4. フェーズごとにモジュール化したファイル — 500行に近づくスキルでは、フェーズを references/ 配下の個別ファイルに分割してください。ファイルを読むたびに初頭効果の影響範囲がリセットされるため、フェーズ4はフェーズ1と注意を奪い合わず、エージェントの注意を十分に引きつけられます。

これらは任意のベストプラクティスではありません。既知の失敗パターンに対する構造的な対策です。最初からすべてのスキルに組み込んでください。

テストケース

スキルの草案を書いた後、現実的なテストプロンプトを2～3個考えてください。実際のユーザーが言いそうな内容にします。ユーザーと共有してください。「試してみたいテストケースをいくつか用意しました。これでよさそうですか？ それとも追加しますか？」（この文言をそのまま使う必要はありません）。その後、テストを実行してください。

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

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

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

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

このセクションは一連の流れになっています。途中で止めたり、先に進んだり、スキルの改善に移ったり、作業が完了したと宣言したりしないでください。次に進む前に、以下の5つのステップをすべて完了する必要があります。/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 には、テスト内容がわかる説明的な名前を付けてください。「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
}

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

Step 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 つのテストケースが表示されます。

• プロンプト：提示されたタスク
• 出力：スキルが生成したファイル。可能な場合はインラインで表示されます
• 前回の出力（イテレーション 2 以降）：前回のイテレーションの出力を表示する折りたたみ可能なセクション
• 正式な評価（評価を実施した場合）：アサーションの合否を表示する折りたたみ可能なセクション
• フィードバック：入力中に自動保存されるテキストボックス
• 前回のフィードバック（イテレーション 2 以降）：前回のコメントをテキストボックスの下に表示

「Benchmark」タブには、各設定の合格率、所要時間、トークン使用量の統計概要が、評価ごとの内訳とアナリストの所見とともに表示されます。

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

Step 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は賢いものです。心の理論をよく備えており、適切な仕組みを与えれば、決まりきった指示に従うだけでなく、実際に成果を上げられます。ユーザーからのフィードバックが簡潔だったり、苛立ちを含んでいたりしても、タスクの内容や、ユーザーがなぜそのように書いたのか、実際に何を書いたのかをきちんと理解し、その理解を指示に反映してください。大文字で 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 がスキルを呼び出すかどうかを決める主要な仕組みです。スキルを作成または改善した後、トリガー精度を高めるための説明の最適化を提案してください。

ステップ 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 スキルに対するネガティブテストとして「Write a fibonacci function」を使うのは簡単すぎて、何も検証できません。ネガティブケースには、実際に判断が難しいものを選んでください。

ステップ 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またはCowork（Claude Codeではない環境）で実行している場合は、references/environment-adaptations.md を読み、ワークフローがどのように変わるかを確認します。主な違いは、サブエージェントの利用可否、ブラウザーへのアクセス、説明の最適化に関するものです。

---

参照ファイル

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

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

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

• references/schemas.md — evals.json、grading.jsonなどのJSON構造
• references/environment-adaptations.md — Claude.aiおよびCowork向けのワークフロー調整

---

完了チェックリスト

このワークフローを完了とする前に、各フェーズに対応したことを確認してください。

• 意図 — スキルが何をすべきか、いつ起動するかを理解しました
• 草案 — エージェントの認知原則を適用して、SKILL.md を作成または編集しました
• テストと評価 — テストケースを実行し、評価ビューアー（generate_review.py）を生成して、人間からフィードバックを得ました
• 反復 — フィードバックに基づいてスキルを改善し、ユーザーが満足するまでテストを再実行しました
• 説明の最適化 — 説明の最適化ループを提案し、（承諾された場合は）実行しました
• パッケージ化 — present_files が利用可能な場合は、パッケージ化を提案しました

未チェックの項目がある場合は、まだ完了していません。忘れないように、これらの手順を TodoList に追加してください。Cowork を使用している場合は、TodoList に「評価用 JSON を作成し、eval-viewer/generate_review.py を実行して、人間がテストケースをレビューできるようにする」を明記してください。

頑張ってください！