# Skill Creator

> スキルを新規作成し、既存のスキルを修正・改善し、スキルの性能を測る。ユーザーがスキルをゼロから作りたいとき、既存のスキルを編集・最適化したいとき、eval を回してスキルをテストしたいとき、ばらつきの分析を伴うベンチマークを取りたいとき、トリガー精度を上げるために description を最適化したいときに使う。

- Skill: `sinnlosses/skill-creator` (Agent Skill, multi-file: 18 files)
- Install (CLI): `npx skillmds@latest add sinnlosses/skill-creator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sinnlosses/skill-creator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: sinnlosses (https://skillmd.com/u/sinnlosses)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/sinnlosses/skill-creator

---


# スキルクリエイター

スキルを作り、反復して改善するためのスキル。

大まかに言うと、スキル作成の流れはこうなる。

- そのスキルに何をさせたいか、だいたいどうやらせるかを決める
- スキルの草稿を書く
- テスト用のプロンプトをいくつか作り、**そのスキルを持った claude** をそれで走らせる
- 結果を定性・定量の両面で評価する手助けをする
  - 実行がバックグラウンドで進む間に、定量的な eval がなければ草稿を書く（既にあるなら、そのまま使うか、変えるべきだと感じたら直す）。そしてユーザーに説明する（既にあったものなら、その既存のものを説明する）
  - `eval-viewer/generate_review.py` スクリプトで結果をユーザーに見せ、定量的な指標も見てもらう
- ユーザーによる結果の評価のフィードバックを基に、スキルを書き直す（定量的なベンチマークから明らかな欠陥が見えたなら、それも踏まえる）
- 満足するまで繰り返す
- テストセットを広げ、より大きな規模でもう一度試す

このスキルを使うときの仕事は、**ユーザーがこの流れのどこにいるかを見極め、そこから先へ進む手伝いをする**こと。例えば「X のためのスキルを作りたい」と言われたら、意味を絞り込み、草稿を書き、テストケースを書き、どう評価したいかを決め、すべてのプロンプトを走らせ、繰り返す。

一方で、既にスキルの草稿を持っている場合もある。そのときはループの eval / 反復の部分から直接始めてよい。

もちろん常に柔軟でいること。「たくさん評価を回す必要はない、感覚で一緒にやってくれ」と言われたら、そうする。

スキルができあがったら（これも順序は柔軟だが）、専用のスクリプトがある description 改善ツールを回して、スキルのトリガーを最適化することもできる。

いい感じ？ いい感じ。

## ユーザーとのやり取り

スキルクリエイターは、コーディングの専門用語への馴染みが大きく異なる人たちに使われる。最近始まったばかりの流れだが、Claude の力に触発されて配管工がターミナルを開き、親や祖父母が「npm のインストール方法」を検索するようになっている。一方で、利用者の大半はそれなりにコンピュータに慣れているだろう。

だから、**文脈の手がかりに注意して言い方を選ぶこと。** 既定の場合の目安を挙げると:

- 「評価（evaluation）」「ベンチマーク」は際どいが、まあ大丈夫
- 「JSON」「アサーション」は、ユーザーがそれを知っているという明確な手がかりが見えるまで、説明なしに使わない

迷ったら用語を簡単に説明してよい。ユーザーに伝わるか不安なときは、短い定義を添えて構わない。

---

## スキルを作る

### 意図を捉える

まずユーザーの意図を理解する。今の会話に、ユーザーが残したい作業の流れが既に含まれていることもある（「これをスキルにして」と言われた場合など）。そのときは、**まず会話の履歴から答えを引き出す**。使ったツール、手順の並び、ユーザーが入れた訂正、観察された入出力の形式。足りない部分はユーザーに埋めてもらい、次の手順へ進む前に確認を取る。

1. このスキルは Claude に何をできるようにするのか？
2. このスキルはいつ起動すべきか？（どんなユーザーの言い回し・文脈で）
3. 期待される出力の形式は？
4. スキルが動くことを確かめるテストケースを用意すべきか？ 客観的に検証できる出力を持つスキル（ファイル変換、データ抽出、コード生成、決まった手順の作業）はテストケースの恩恵を受ける。主観的な出力のスキル（文体、アート）は不要なことが多い。スキルの種類に応じて適切な既定を提案しつつ、決めるのはユーザーに任せる。

### 聞き取りと調査

エッジケース、入出力の形式、例となるファイル、成功の基準、依存関係について、こちらから積極的に質問する。**この部分が固まるまでテスト用のプロンプトは書かない。**

利用できる MCP を確認する。調査（ドキュメントの検索、似たスキルを探す、指針を調べる）に役立つなら、サブエージェントが使えるなら並列で、使えないならその場で調査する。ユーザーの負担を減らすため、文脈を用意してから臨むこと。

### SKILL.md を書く

ユーザーへの聞き取りを基に、次の要素を埋める。

- **name**: スキルの識別子
- **description**: いつ起動するか、何をするか。**これがトリガーの主要な仕組み**なので、スキルが何をするかと、いつ使うかの具体的な文脈の**両方**を含める。「いつ使うか」の情報はすべてここに書き、本文には書かない。注意: 現在の Claude はスキルを「起動しなさすぎる」傾向がある（役に立つ場面でも使わない）。これに対抗するため、description は少し**押しが強い**くらいにすること。例えば「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)
```

#### 段階的な開示（progressive disclosure）

スキルは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 として演じる」といったものは問題ない。

#### 書き方のパターン

指示には命令形を使うのが望ましい。

**出力形式の定義** - 次のように書ける:
```markdown
## Report structure
ALWAYS use this exact template:
# [Title]
## Executive summary
## Key findings
## Recommendations
```

**例のパターン** - 例を入れると役に立つ。次のように整形できる（ただし例の中に「Input」「Output」が出てくる場合は、少し形を変えたほうがよい）:
```markdown
## 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` に保存する。**アサーションはまだ書かない** — プロンプトだけ。アサーションは次の手順で、実行が進んでいる間に草稿を書く。

```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/` など）。**最初に全部作らない** — 進みながら作る。

### 手順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 ディレクトリごとにこれらのファイルを作る。前の反復から引き継がれると思い込まないこと。

```json
{
  "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` に保存する。

```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 のディレクトリから集計スクリプトを実行する:
   ```bash
   python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name>
   ```
   これは `benchmark.json` と `benchmark.md` を生成し、構成ごとの pass_rate・時間・トークン数を、平均±標準偏差と差分とともに出す。benchmark.json を手で作る場合は、ビューアが期待する正確なスキーマを `references/schemas.md` で確認すること。
各 with_skill の版は、対応するベースラインの前に置く。

3. **分析のパスを行う** — ベンチマークのデータを読み、集計された統計が隠しているパターンを浮かび上がらせる。何を見るべきかは `agents/analyzer.md`（「Analyzing Benchmark Results」の節）を参照。スキルの有無に関わらず常に通るアサーション（識別力がない）、ばらつきの大きい eval（不安定かもしれない）、時間とトークンのトレードオフといったもの。

4. **ビューアを立ち上げる** — 定性的な出力と定量的なデータの両方を渡す:
   ```bash
   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」タブは統計の要約を表示する。構成ごとの合格率・所要時間・トークン使用量と、eval ごとの内訳、分析の所見。

移動は前後のボタンか矢印キー。終わったら「Submit All Reviews」を押すと、すべてのフィードバックが `feedback.json` に保存される。

### 手順5: フィードバックを読む

ユーザーから終わったと伝えられたら、`feedback.json` を読む。

```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"
}
```

フィードバックが空なら、ユーザーはそれで問題ないと思ったということ。**ユーザーが具体的な不満を書いたテストケースに改善を集中する。**

使い終わったらビューアのサーバを落とす:

```bash
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つの出力を独立したエージェントに渡し、品質を判定させる。そのうえで、勝った側がなぜ勝ったのかを分析する。

これは任意で、サブエージェントが必要であり、ほとんどのユーザーには不要。人間によるレビューのループで普通は十分。

---

## description の最適化

SKILL.md の frontmatter の description フィールドは、**Claude がそのスキルを呼び出すかどうかを決める主要な仕組み**。スキルを作った、あるいは改善したあとで、トリガー精度を上げるための description の最適化を提案する。

### 手順1: トリガーの eval クエリを作る

eval クエリを20個作る。起動すべきものと起動すべきでないものを混ぜる。JSON として保存する。

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

クエリは**現実的**で、Claude Code や Claude.ai のユーザーが実際に打ちそうなものにすること。抽象的な依頼ではなく、具体的で詳細を伴うもの。例えばファイルパス、ユーザーの仕事や状況についての個人的な文脈、列名と値、会社名、URL。ちょっとした背景も。小文字だけのもの、略語・打ち間違い・くだけた話し言葉を含むものがあってよい。長さもいろいろ混ぜ、白黒はっきりしたものより**際どい場合**に focus する（ユーザーが最後に承認する機会がある）。

悪い例: `"このデータを整形して"`、`"PDF からテキストを抽出して"`、`"グラフを作って"`

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

**起動すべき**クエリ（8〜10個）については、網羅性を考える。同じ意図の異なる言い回し（硬いもの、くだけたもの）が欲しい。ユーザーがスキル名やファイル種別を明示していないが明らかにそれを必要としている場合も入れる。珍しい使い方や、他のスキルと競合するがこちらが勝つべき場合も混ぜる。

**起動すべきでない**クエリ（8〜10個）については、**惜しいもの**が最も価値がある。スキルとキーワードや概念を共有しているが、実際には別のものが必要なクエリ。隣接する領域、素朴なキーワード一致なら起動してしまうが起動すべきでない曖昧な言い回し、スキルが扱う何かに触れてはいるが別のツールのほうが適切な文脈、といったもの。

避けるべき肝心な点: **起動すべきでないクエリを、明らかに無関係なものにしない。** PDF のスキルに対する否定テストとして「フィボナッチ関数を書いて」は簡単すぎる — 何もテストしていない。否定の事例は本当に難しいものにすること。

### 手順2: ユーザーとレビューする

HTML のテンプレートを使って、eval のセットをユーザーにレビューしてもらう。

1. `assets/eval_review.html` からテンプレートを読む
2. プレースホルダを置き換える:
   - `__EVAL_DATA_PLACEHOLDER__` → eval 項目の JSON 配列（引用符で囲まない。JS の変数への代入なので）
   - `__SKILL_NAME_PLACEHOLDER__` → スキルの名前
   - `__SKILL_DESCRIPTION_PLACEHOLDER__` → スキルの現在の description
3. 一時ファイル（例: `/tmp/eval_review_<skill-name>.html`）に書き出して開く: `open /tmp/eval_review_<skill-name>.html`
4. ユーザーはクエリを編集し、should-trigger を切り替え、項目を追加・削除してから「Export Eval Set」を押す
5. ファイルは `~/Downloads/eval_set.json` にダウンロードされる。複数ある場合に備えて（`eval_set (1).json` など）、ダウンロードフォルダで最も新しい版を確認する

**この手順は重要** — 悪い eval クエリは悪い description につながる。

### 手順3: 最適化のループを回す

ユーザーにこう伝える:「これは少し時間がかかります。最適化のループをバックグラウンドで回して、定期的に様子を見ます。」

eval のセットをワークスペースに保存し、バックグラウンドで実行する。

```bash
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**（今のセッションを動かしているもの）を使う。

実行中は定期的に出力を tail して、今どの反復にいるか、スコアがどうなっているかをユーザーに伝える。

これは最適化のループ全体を自動で処理する。eval のセットを訓練60%・ホールドアウトのテスト40%に分け、現在の description を評価し（信頼できるトリガー率を得るため各クエリを3回実行）、失敗した内容を基に Claude に改善案を出させる。新しい description それぞれを訓練とテストの両方で再評価し、最大5回まで反復する。終わるとブラウザで反復ごとの結果を示す HTML レポートを開き、`best_description` を含む JSON を返す。過学習を避けるため、**訓練スコアではなくテストスコア**で選ばれる。

### スキルのトリガーはどう働くか

トリガーの仕組みを理解すると、より良い eval クエリを設計できる。スキルは Claude の `available_skills` の一覧に name + description とともに現れ、Claude はその description を基にスキルを参照するかどうかを決める。**重要なのは、Claude は自分で簡単に扱えないタスクでしかスキルを参照しない**ということ。「この PDF を読んで」のような単純な一段のクエリは、description が完璧に一致していてもスキルを起動しないことがある。基本的なツールで直接扱えてしまうからだ。複雑・多段・専門的なクエリは、description が一致していれば確実にスキルを起動する。

つまり eval クエリは、**Claude がスキルを参照することで実際に恩恵を受けるくらい中身のあるもの**にすべきである。「ファイル X を読んで」のような単純なクエリはテストケースとして質が悪い。description の質に関わらずスキルを起動しない。

### 手順4: 結果を適用する

JSON の出力から `best_description` を取り出し、スキルの SKILL.md の frontmatter を更新する。ユーザーに変更前後を見せ、スコアを報告する。

---

### パッケージ化して渡す（`present_files` ツールが使える場合のみ）

`present_files` ツールが使えるかを確認する。使えないならこの手順を飛ばす。使えるなら、スキルをパッケージ化して .skill ファイルをユーザーに渡す。

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

パッケージ化したら、インストールできるよう、できあがった `.skill` ファイルのパスをユーザーに案内する。

---

## Claude.ai 固有の指示

Claude.ai でも中心の流れは同じ（草稿 → テスト → レビュー → 改善 → 繰り返し）。ただし Claude.ai にはサブエージェントがないので、仕組みの一部が変わる。次のように適応する。

**テストケースの実行**: サブエージェントがないので並列実行もない。各テストケースについて、スキルの SKILL.md を読み、その指示に従って自分でテスト用プロンプトのタスクをこなす。1件ずつ行う。独立したサブエージェントより厳密さは劣るが（スキルを書いた本人が実行するので、文脈を全部持っている）、健全性の確認としては有用であり、人間によるレビューの手順が補う。ベースラインの実行は飛ばし、依頼どおりスキルを使ってタスクを完了するだけでよい。

**結果のレビュー**: ブラウザを開けない場合（Claude.ai の VM にディスプレイがない、リモートサーバ上にいるなど）は、ブラウザのレビュー画面を完全に飛ばす。代わりに会話の中で結果を直接示す。各テストケースについて、プロンプトと出力を見せる。出力がユーザーの見るべきファイル（.docx や .xlsx など）なら、ファイルシステムに保存し、ダウンロードして確認できるよう場所を伝える。フィードバックはその場で聞く:「これはどうでしょう？ 変えたいところはありますか？」

**ベンチマーク**: 定量的なベンチマークは飛ばす。サブエージェントなしでは意味を持たないベースライン比較に依存しているため。ユーザーからの定性的なフィードバックに集中する。

**反復のループ**: これまでと同じ（スキルを改善し、テストケースを再実行し、フィードバックを求める）。途中にブラウザのレビュー画面がないだけ。ファイルシステムがあるなら、結果を反復ごとのディレクトリに整理することはできる。

**description の最適化**: この節は `claude` CLI（具体的には `claude -p`）を必要とし、これは Claude Code でしか使えない。Claude.ai にいるなら飛ばす。

**ブラインド比較**: サブエージェントが必要。飛ばす。

**パッケージ化**: `package_skill.py` は Python とファイルシステムがあればどこでも動く。Claude.ai でも実行でき、ユーザーはできあがった `.skill` ファイルをダウンロードできる。

**既存のスキルの更新**: ユーザーが求めているのが新規作成ではなく既存スキルの更新であることもある。その場合:
- **元の名前を保つ。** スキルのディレクトリ名と frontmatter の `name` フィールドを確認し、そのまま使う。例えばインストール済みのスキルが `research-helper` なら、出力は `research-helper.skill`（`research-helper-v2` ではない）
- **編集する前に書き込める場所へコピーする。** インストール済みのスキルのパスは読み取り専用かもしれない。`/tmp/skill-name/` にコピーし、そこで編集し、コピーからパッケージ化する
- **手でパッケージ化する場合は、まず `/tmp/` に置く**。それから出力先のディレクトリにコピーする。直接書き込むと権限で失敗しうる

---

## Cowork 固有の指示

Cowork にいる場合、知っておくべき主な点は次のとおり。

- サブエージェントが使えるので、主要な流れ（テストケースを並列で起こす、ベースラインを実行する、採点する、など）はすべて動く。（ただしタイムアウトで深刻な問題が起きるなら、テスト用プロンプトを並列でなく直列で実行してよい）
- ブラウザもディスプレイもないので、eval のビューアを作るときはサーバを起こす代わりに `--static <output_path>` で単体の HTML ファイルを書き出す。そのうえで、ユーザーがブラウザで開けるリンクを差し出す
- 理由は分からないが、Cowork の環境では、テスト実行後に eval のビューアを作ることを Claude が避けたがるように見える。だから念のため繰り返す。**Cowork にいようと Claude Code にいようと、テストを実行したら、自分で修正を試みる前に、必ず `generate_review.py` で eval のビューアを作って人間に例を見てもらうこと**（独自の凝った HTML を書かない）。先に謝っておくが、ここは大文字で言う: **自分で入力を評価する*前*に、eval のビューアを作れ。** 人間の前にできるだけ早く出したいのだ
- フィードバックの扱いが異なる。サーバが動いていないので、ビューアの「Submit All Reviews」ボタンは `feedback.json` をファイルとしてダウンロードする。そこから読める（先にアクセスを要求する必要があるかもしれない）
- パッケージ化は動く。`package_skill.py` は Python とファイルシステムがあればよい
- description の最適化（`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` を実行してユーザーのレビューを助ける
  - 定量的な eval を回す
- 自分とユーザーが満足するまで繰り返す
- 最終的なスキルをパッケージ化してユーザーに返す

TodoList のような仕組みがあるなら、忘れないよう手順を登録しておくこと。Cowork にいるなら、確実に実行されるよう「evals の JSON を作り、`eval-viewer/generate_review.py` を実行して人間がテストケースをレビューできるようにする」を TodoList に入れること。

幸運を！