skill-creator

スキル作成ツール

新しいスキルを作成し、繰り返し改善するためのスキルです。

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

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

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

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

もちろん、常に柔軟に対応してください。「たくさん評価を実行する必要はないので、気軽に相談に乗ってほしい」と言われた場合は、そのように進めてもかまいません。

スキルが完成したら（ただし、進める順序は柔軟に変えられます）、別のスクリプト一式を使ってスキルの説明を改善し、スキルが起動されやすくなるよう最適化することもできます。

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

---

DeerFlow 環境（⚠️ 最初にお読みください）

DeerFlow のサンドボックス化されたエージェント環境（skill_manage ツールを利用できる環境）で実行している場合は、すべてのスキルファイル操作で以下のルールに従う必要があります。これらのルールは、以下に記載されている一般的なファイル書き込みおよびパッケージ化の手順より優先されます。

重要な理由

DeerFlow では、サンドボックスのファイルシステムが分離されています。write_file で書き込んだファイルは /mnt/user-data/outputs/ に保存されますが、ここはスレッドごとの出力ディレクトリであり、新しいチャットからはファイルを参照できません。スキルは専用の skill_manage ツールを通じて保存する必要があります。これにより、ユーザーごとのスキルディレクトリに保存され、以後のすべてのチャットからすぐに参照できます。

すべてのスキルファイル操作に skill_manage を使用する

操作	skill_manage のアクション	例
新しいスキルを作成する	action="create"	skill_manage(action="create", name="my-skill", content="---\nname: my-skill\n---\n...")
SKILL.md 全体を置き換える	action="edit"	skill_manage(action="edit", name="my-skill", content="updated SKILL.md")
部分編集（検索して置換）	action="patch"	skill_manage(action="patch", name="my-skill", find="old text", replace="new text")
スキルを削除する	action="delete"	skill_manage(action="delete", name="my-skill")
補助ファイルを追加する	action="write_file"	skill_manage(action="write_file", name="my-skill", path="scripts/helper.py", content="...")
補助ファイルを削除する	action="remove_file"	skill_manage(action="remove_file", name="my-skill", path="scripts/helper.py")

主なルール

1. サンドボックスの write_file を使って、スキルファイル（SKILL.md、scripts/、references/、assets/）を作成または変更しないでください。これらは /mnt/user-data/outputs/ に保存され、今後のチャットから参照できません。必ず skill_manage を使用してください。

2. package_skill.py の手順は省略してください。DeerFlow では、skill_manage がスキルをユーザーごとの正しいディレクトリに保存します。.skill へのパッケージ化や手動インストールは不要です。スキルはすべての新しいチャットですぐに利用できます。

3. スキルには present_files の手順を使わないでください。スキルは納品物ではありません。skill_manage で保存され、スキルシステムによって自動的に読み込まれます。present_files はスキル以外の出力（評価レポート、ベンチマークなど）にのみ使用してください。

4. 評価用ワークスペースのファイルはサンドボックスに保存してかまいません。テスト用プロンプト、ベンチマークデータ、評価ビューアーの HTML、採点結果などはスキルファイルではありません。通常どおり、サンドボックスの write_file を使って /mnt/user-data/outputs/ または /mnt/user-data/workspace/ に書き込めます。

5. 既存のスキルの SKILL.md を読むには、サンドボックスで read_file("/mnt/skills/custom/<name>/SKILL.md") を使用してください（ユーザーごとのスキルディレクトリに対応しています）。

6. 既存のスキルを更新する場合：skill_manage(action="edit") または skill_manage(action="patch") を使用してください。最初に /tmp/ にコピーしないでください。skill_manage がユーザーごとのストレージを直接処理します。

DeerFlow でのワークフロー

基本的な流れは同じですが、保存方法が変わります。

1. 意図を把握 → ヒアリング → SKILL.md の内容を下書き
2. skill_manage(action="create", name=<name>, content=<SKILL.md>) を呼び出してスキルを保存
3. テストケースを実行（評価用ワークスペースのファイルにはサンドボックスの write_file を使用）
4. 結果を評価し、フィードバックを収集
5. skill_manage(action="edit") または skill_manage(action="patch") を呼び出してスキルを改善
6. 納得できるまで繰り返す
7. **完了です。パッケージ化は不要です。**スキルはすでに保存されており、今後のすべてのチャットから利用できます。

---

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

スキル作成者は、コーディング用語への習熟度がさまざまな人々に利用される可能性があります。まだ聞いたことがないかもしれません（始まったのはごく最近のことなので、無理もありません）が、今では 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

例のパターン — 例を含めると役立ちます。次のように書式設定できます（ただし、例に「入力」と「出力」が含まれる場合は、少し変更してもよいでしょう）。

## Commit message format
**Example 1:**
Input: Added user authentication with JWT tokens
Output: feat(auth): implement JWT-based authentication

文体

強い MUST の連発を避け、なぜそれが重要なのかをモデルに説明するようにしてください。心の理論を活用し、特定の例に過度に限定されない汎用的なスキルを目指してください。まず草案を作成し、あらためて見直して改善してください。

テストケース

スキルの草案を書いたら、現実的なテストプロンプトを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-test や、ほかのテスト用スキルは使用しないでください。

結果は、スキルディレクトリと同じ階層にある <skill-name>-workspace/ に保存してください。ワークスペース内では、イテレーションごとに整理します（iteration-1/、iteration-2/ など）。その中で、各テストケースにディレクトリを割り当てます（eval-0/、eval-1/ など）。これらのディレクトリを一度にすべて作成せず、必要に応じて作成してください。

Step 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": []
}

Step 2: 実行中にアサーションを作成する

実行が終わるのをただ待つのではなく、その時間を有効に使ってください。各テストケースについて、定量的なアサーションを作成し、内容をユーザーに説明します。evals/evals.json にアサーションがすでにある場合は、その内容を確認して、何をチェックするものか説明してください。

適切なアサーションは客観的に検証でき、説明的な名前が付いているものです。ベンチマークビューアーで結果を見た人が、それぞれのチェック内容をすぐ理解できるように記述してください。文体やデザインの品質など、主観的なスキルは定性的に評価するほうが適しています。人の判断が必要なものに、無理にアサーションを設定しないでください。

アサーションを作成したら、eval_metadata.json と evals/evals.json を更新してください。また、定性的な出力と定量的なベンチマークの両方について、ビューアーでユーザーが確認できる内容を説明してください。

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

• Prompt：与えられたタスク
• Output：スキルが生成したファイル（可能な場合はインラインで表示）
• Previous Output（反復 2 以降）：前回の反復の出力を表示する折りたたみセクション
• Formal Grades（採点を実施した場合）：アサーションの合否を表示する折りたたみセクション
• Feedback：入力中に自動保存されるテキストボックス
• Previous Feedback（反復 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. フィードバックから一般化します。 ここで起きていることの全体像は、さまざまなプロンプトで何百万回（文字どおり、あるいはそれ以上かもしれません）も使えるスキルを作ろうとしている、ということです。ここでは、作業を速めるために、あなたとユーザーが何度も少数の例を反復しています。ユーザーはそれらの例を熟知しており、新しい出力もすぐに評価できます。しかし、あなたとユーザーが共同開発しているスキルがその例だけでしか機能しないなら、役に立ちません。細かく過剰適合する変更や、過度に制約の厳しい 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 を返します。

説明の最適化には PyYAML が必要です（パッケージバリデーターでも使用されます）。名前と説明のフィールドは、エスケープされた引用符、コメント、ブロックスカラーを含め、YAML 文字列として解析されます。メタデータが無効な場合、評価器、最適化ツール、または説明改善コマンドは停止し、標準エラー出力に Error: を出力して終了ステータス 1 を返します。

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

トリガーの仕組みを理解すると、より適切な評価クエリを設計できます。スキルは名前と説明とともに 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 でも基本的なワークフロー（下書き → テスト → レビュー → 改善 → 繰り返し）は同じですが、サブエージェントがないため、いくつかの手順が異なります。以下を調整してください。

テストケースの実行：サブエージェントがないため、並列実行はできません。テストケースごとに、スキルの SKILL.md を読み、その指示に従ってテスト用プロンプトを自分で実行してください。1 つずつ進めます。スキルを書いたあなた自身が実行するため、すべての文脈を把握しており、独立したサブエージェントを使う場合より厳密さに欠けますが、有用な簡易チェックになります。また、人間によるレビューの手順がそれを補います。ベースラインの実行は省略し、スキルを使って依頼されたタスクを完了してください。

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

ベンチマーク：定量的なベンチマークは省略してください。ベースラインとの比較に依存しており、サブエージェントがなければ意味のある比較にならないためです。ユーザーからの定性的なフィードバックを重視してください。

反復のループ：これまでと同様に、スキルを改善し、テストケースを再実行して、フィードバックを求めます。途中にブラウザーでのレビューを挟まない点だけが異なります。ファイルシステムを利用できる場合は、結果をイテレーションごとのディレクトリに整理することもできます。

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

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

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

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

• 元の名前を維持してください。 スキルのディレクトリ名と name フロントマターのフィールドを確認し、変更せずに使用してください。たとえば、インストール済みのスキルが 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 を実行する」と記載してください。

頑張ってください！