Claude Code Skill の Eval / Gotchas — 全スキルに必要か？運用6週間で出た答え
はじめに
Claude Code の Skill（~/.claude/skills/<name>/SKILL.md）を40本以上運用してみて気づいたことがある。
「## Eval と ## Gotchas を全 Skill に書くべき」という設計で始めたが、6週間後に振り返ると54スキル中 Gotchas の実追記があったのは3スキルのみだった。
残り51本は空テンプレを貼っただけ。これはルールの問題ではなく 設計の問題 だと気づき、3分類に再設計した。その記録を共有する。
最初の設計：全スキル一律
当初のルール：
## Eval
スキル完了時に自己採点し skills-usage.json に記録する
## Gotchas
<!-- エッジケースに遭遇したらここに追記 -->
このテンプレを全 SKILL.md の末尾に貼り、「使うほど賢くなるループ」を目指した。
6週間後の実測値：
| 指標 | 計測値 |
|---|---|
| Eval 設置率 | 42/54（78%） |
| Gotchas 設置率 | 32/54（59%） |
| Gotchas に実際の追記がある | 3/54（6%） |
ループは回っていなかった。
なぜ機能しなかったか
原因を探ると、スキルには性質の違う3種類が混在していた。
A. 本番影響系（外部書き込み・自動実行）
例：Qiita 自動投稿 / DB 更新 / ニュースレター配信
人間がその場でレビューしない。失敗が気づかれないまま進む。
この種のスキルは Eval も Gotchas も真剣に書く価値がある。
B. 知識蓄積系（繰り返し使うが副作用なし）
例：SEO記事ライター / コードレビュー / デバッグ
同じ罠を踏みやすい。失敗パターンがテキストで表現できる。
Gotchas は価値があるが、Eval（自己採点）は不要。人間がすぐ結果を見るから。
C. ワンショット系（1回完結・対話的・無害）
例：defuddle / firecrawl-scrape / YouTube要約 / brainstorm
人間がリアルタイムで結果を見る。副作用なし。失敗してもすぐわかる。
Eval も Gotchas もそもそも要らない。テンプレを置くだけで SKILL.md が太り、LLM の指示追従精度が落ちる。
実際に機能したのはどこか
A 分類の qiita-daily-writer（Qiita 自動投稿スキル）では Gotchas が機能した。
経緯：
- シェル変数経由で JSON を渡していたところ、制御文字エラーで POST が失敗
- エラーに気づかず
curlを再実行 → 重複投稿3件 - Gotchas に追記：「curl は tempfile を使え・再POSTする前に GET で確認」
- 翌日から Step 5-0（投稿前重複チェック）を追加
- その後の事故ゼロ
## Gotchas
### Step 5: curl二重POST問題（YYYY-MM-DD）
- **原因**: シェル変数経由の JSON が制御文字エラーを起こし Python が失敗
- **対策**: tempfile に書き出し `--data-binary @file` で渡す
- **検知**: 投稿後 GET で当日件数確認、2件以上なら削除
LLM は SKILL.md を毎回読む。Gotchas に追記するだけで、コード変更なしに次回実行から挙動が変わる。これが効いた。
3分類への再設計
上記の気づきをもとに分類ルールを整理した。
| 分類 | 定義 | Eval | Gotchas |
|---|---|---|---|
| A: 本番影響系 | 外部書き込み・自動実行・スケジュールタスク | ✅ | ✅ |
| B: 知識蓄積系 | 繰り返し使う・罠パターンが蓄積できる | ❌ | ✅ |
| C: ワンショット系 | 1回完結・対話的・副作用なし | ❌ | ❌ |
新規スキル作成時の判定チェック：
Q1: curl -X POST など外部への書き込みがあるか？
→ YES → A（Eval + Gotchas 必須）
Q2: 同じスキルを繰り返し使い、失敗パターンが蓄積できるか？
→ YES → B（Gotchas のみ）
それ以外 → C（何も置かない・SKILL.md を軽く保つ）
実施後の数値（54スキル）：
| 指標 | Before | After |
|---|---|---|
| Eval 設置数 | 42 | 6（A のみ） |
| Gotchas 設置数 | 32 | 25（A+B） |
| SKILL.md 削除行数 | — | 1,054行 |
B 分類スキルから Eval を削除し、C 分類から両方を削除した結果、合計 1,054 行のボイラープレートが消えた。
Eval は「完了の定義」として機能する
A 分類スキルに残した Eval の役割は「自己採点」ではなく 「完了の定義の明文化」 だ。
## Eval
**成功判定**:
- `pass`: 記事ファイル生成 + Qiita 投稿成功 + プランナー更新完了
- `fail`: 上記のいずれかが欠けている
**完了宣言禁止条件**:
- RESPONSE_FILE が空のまま終了した場合（curl エラーかも）
- meta.json の status が published になっていない場合
「完了しました」と言う前にこのチェックリストを参照させることで、LLM が自分で手を止めて確認する動線を作れる。
まとめ
- 全スキルへの一律適用は逆効果：SKILL.md が太ると LLM の精度が落ちる
- A分類（本番影響系）にだけ集中投下：6スキルで本当に機能させる
- Gotchas は「追記した瞬間に次回から有効」：コード変更ゼロで挙動が変わる最安コストの改善
- C分類には何も置かない：スキルを軽くすることも品質の一部
- 分類ルールを
skill-management.mdに書いておくと、新規スキル作成時に迷わない