skill-creator

スキル作成

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

大まかなスキル作成の流れは次のとおりです。

• スキルで何を実現し、どのように実現するかをおおよそ決めます
• スキルのドラフトを作成します
• テスト用のプロンプトをいくつか作成し、スキルを読み込ませた状態でエージェントを実行します
• ユーザーが結果を定性的にも定量的にも評価できるよう支援します
  • 実行がバックグラウンドで進んでいる間に、まだ定量評価がなければいくつか作成します（すでにある場合は、そのまま使うことも、変更が必要だと感じたら修正することもできます）。次に、定量評価についてユーザーに説明します（すでに用意されている場合は、既存のものを説明します）
  • eval-viewer/generate_review.py スクリプトを使って、ユーザーが結果を確認できるようにします。また、定量指標も確認できるようにします
• ユーザーが結果を評価した際のフィードバックに基づいて（また、定量ベンチマークで明らかになった重大な欠陥があればそれも考慮して）、スキルを書き直します
• 満足できるまで繰り返します
• テストセットを拡張し、より大規模に再度試します

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

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

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

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

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

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

スキル作成を利用する人は、コーディング用語に初めて触れる人から経験豊富な開発者まで幅広く、コンピューターの基本的な操作には慣れている人が大半です。

そのため、状況を示す手がかりに注意を払い、伝え方を調整してください。まずは次の点を参考にしてください。

• 「評価」と「ベンチマーク」は、説明なしで使っても差し支えありません
• 「JSON」や「アサーション」は、説明なしで使う前に、ユーザーがそれらを知っていると判断できる明確な手がかりを確認してください

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

---

スキルの作成

意図を把握する

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

1. このスキルで、エージェントに何を実行させますか？
2. どのようなときにこのスキルを起動しますか？（ユーザーが使うフレーズや状況）
3. 期待する出力形式は何ですか？
4. スキルが期待どおりに動作することを確認するため、テストケースを用意しますか？出力を客観的に検証できるスキル（ファイル変換、データ抽出、コード生成、固定された手順など）では、テストケースを用意するのが効果的です。主観的な出力（文章の文体、アートなど）の場合は、通常必要ありません。スキルの種類に応じて適切な初期案を提案しつつ、ユーザーが決められるようにしてください。

インタビューと調査

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

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

SKILL.md の作成

ユーザーへのインタビューに基づいて、次の項目を記入してください。

• name：スキルの識別子
• description：いつ起動するか、何をするか。これは主要な起動メカニズムです。スキルが行うことと、使用する具体的な状況の両方を含めてください。「いつ使うか」に関する情報はすべてここに記載し、本文には含めないでください。注：AI エージェントはスキルを「使いそびれる」傾向があります。役立つ場面でも使わないことがあるためです。これを防ぐため、スキルの説明は少し「強め」にしてください。たとえば、「社内データを表示するシンプルで高速なダッシュボードの構築方法」ではなく、「社内データを表示するシンプルで高速なダッシュボードの構築方法です。ユーザーがダッシュボード、データの可視化、社内指標に言及した場合や、『ダッシュボード』と明示していなくても、あらゆる種類の会社データを表示したい場合は、必ずこのスキルを使用してください」といった説明にします。
• 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
    ├── resources/   - Alternate resource folder used by some hosts
    └── 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

エージェントは関連する参照ファイルのみを読み込みます。

クロスプラットフォームの Frontmatter

移植性を、階層化されたシステムとして扱ってください。

1. 移植可能なベースライン：SKILL.md、YAML frontmatter、Markdown の指示を含むスキルディレクトリ。
2. ホスト固有のオーバーレイ：特定のランタイムとの統合を改善する追加フィールドやファイル。

移植可能なベースラインは常に次のとおりです。

---
name: my-skill
description: What this skill does and when to trigger it.
---

このベースライン単独で機能する状態を維持してください。重要な動作を定義する唯一の場所として、ホスト固有の拡張を使ってはいけません。

対象のランタイムに利点がある場合にのみ、オーバーレイを使用してください。

オーバーレイ	ホスト	備考
agents/openai.yaml	Codex CLI / Codex app	Codex 固有のメタデータ、UI／呼び出しのヒントに関するドキュメント
allowed-tools	ランタイム固有の互換性フィールド	一部の Codex／OpenClaw 環境で便利ですが、移植可能なベースラインには含まれません
compatibility	Claude 系エコシステム	ツール／MCP の依存関係に関する注記。任意の項目です
user-invocable、disable-model-invocation、command-*、requires.*、os、primaryEnv	OpenClaw	ホスト固有のコマンドと利用条件の制御
context: fork、hooks、動的なコンテキスト注入、カスタムエージェントフィールド	Claude Code	Claude Code 専用の拡張です。他のホストでもサポートされると想定してはいけません

Codex オーバーレイの例（agents/openai.yaml）：

allow_implicit_invocation: true
interface:
  display_name: My Skill

OpenClaw オーバーレイの例（ホスト固有のフィールド）：

---
name: my-skill
description: ...
user-invocable: true
disable-model-invocation: false
metadata:
  openclaw:
    requires:
      bins: ["curl"]
    primaryEnv: OPENAI_API_KEY
---

重要な互換性ルール： 汎用スキルを作成する場合は、移植可能なベースラインから始め、ユーザーが対応するホストを明示的に指定した場合にのみオーバーレイを追加してください。

驚きのなさの原則

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

執筆パターン

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

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

## Report structure
Use this template for the report:
# [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": []
    }
  ]
}

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

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

このセクションでは、最初から最後まで一連の作業として進めてください。タイミングデータを取得できるのは実行の完了時だけなので、最後まで続けてください。別のスキルテスト用スキルやショートカットではなく、以下の手順で評価を実行してください。

結果は、スキルディレクトリと同じ階層にある <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、時間、トークン数と、平均値 ± 標準偏差および差分を含む benchmark.json と benchmark.md が生成されます。benchmark.json を手動で作成する場合は、ビューアーが想定する正確なスキーマについて references/schemas.md を確認してください。
   各 with_skill バージョンは、対応するベースラインの前に配置してください。

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> も指定してください。

   ヘッドレス環境の場合： webbrowser.open() が利用できない場合や、環境にディスプレイがない場合は、サーバーを起動する代わりに --static <output_path> を指定して、スタンドアロンの HTML ファイルを出力します。ユーザーが「すべてのレビューを送信」をクリックすると、フィードバックが feedback.json ファイルとしてダウンロードされます。ダウンロード後、次のイテレーションで使えるように、feedback.json をワークスペースディレクトリにコピーしてください。

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

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

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

「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 のフロントマターにある説明フィールドは、エージェントがスキルを呼び出すかどうかを決める主な仕組みです。スキルを作成または改善した後、呼び出し精度を高めるために説明を最適化することを提案してください。

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

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

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

クエリは現実的で、実際のエージェントユーザーが入力しそうなものにしてください。抽象的な依頼ではなく、具体的で詳細な依頼にします。たとえば、ファイルパス、ユーザーの仕事や状況に関する個人的な背景、列名や値、会社名、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 配列（JS 変数への代入なので、引用符で囲みません）
   • __SKILL_NAME_PLACEHOLDER__ → スキルの名前
   • __SKILL_DESCRIPTION_PLACEHOLDER__ → スキルの現在の説明
3. 一時ファイル（例：/tmp/eval_review_<skill-name>.html）に書き込み、開きます：python -m webbrowser /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> \
  --platform <claude-code|openclaw|codex> \
  --optimizer-platform <auto|claude-code|openclaw|codex|anthropic> \
  --model <optional-model-id-for-the-selected-runtime> \
  --max-iterations 5 \
  --verbose

デフォルトでは、オプティマイザーのランタイムは評価プラットフォームと一致します。あるホストで評価しながら、別のホストで説明を書き換える場合に限り、--optimizer-platform を上書きします。OpenClaw でテストするときは、--platform openclaw（および必要に応じて --openclaw-agent <id>）を渡します。

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

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

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

トリガーの仕組みを理解すると、より良い評価クエリを設計できます。スキルは名前と説明とともにエージェントが利用できるスキル一覧に表示され、エージェントはその説明に基づいてスキルを参照するかどうかを判断します。重要なのは、エージェントがスキルを参照するのは、自力では簡単に対応できないタスクの場合だけだということです。説明に完全に一致していても、単純な 1 ステップのクエリではスキルがトリガーされないことがあります。説明に一致する複雑なクエリ、複数ステップのクエリ、または専門的なクエリでは、スキルが確実にトリガーされます。

検出品質はホストによって異なります。

• Claude Code：オプティマイザーは実際の Skill/Read ツールイベントを検査できるため、トリガー評価は信頼性の高いものです。
• Codex CLI / OpenClaw：現在公開されている CLI では、このツールが利用できる形で信頼性の高いスキル読み込みイベントを公開していません。そのため、トリガー評価では、スキルが有効化された場合に一時的なスキルがモデルにセンチネルフレーズを出力させる、文書化されたヒューリスティックなプロキシを使用します。これらのスコアは参考にはなりますが、完全ではないものとして扱ってください。

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

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

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

---

パッケージ化して提示する

対象のエコシステムでインストール可能なバンドルが必要な場合は、スキルをパッケージ化し、生成された .skill ファイルのパスをユーザーに伝えます。必要でない場合は、フォルダー自体を共有すれば十分です。

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

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

参照ファイル

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

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

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

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

---

要点となるサイクルを、念のためもう一度繰り返します。

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

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

頑張ってください！