Claude Code スキルの蒸留術 - ワークフロー振り返り × ベストプラクティスで品質を高める
この記事について
Claude Code のスキルを作ったあと、実際に使ってみると「ここはこうじゃないんだよな」という場面に遭遇します。
この記事では、ワークフローを振り返り、出力をセルフレビューさせ、ベストプラクティスを読ませてリファクタリングするという手法を紹介します。
蒸留プロセスの流れ
- スキルを実行する
- ワークフローを振り返る（何がうまくいったか）
- 出力をレビューさせる（Claude に問題点を特定させる）
- ベストプラクティスを読ませる（公式ドキュメントを参照）
- リファクタリングする
- 繰り返す
実例: リリースノート生成スキル
複数の PR からリリースノートを自動生成するスキルを例に説明します。
スキルの構成
Phase 1: PR解析（並列実行）
├── Task(pr-analyzer, PR1) → 要約1
├── Task(pr-analyzer, PR2) → 要約2
└── ...
Phase 2: リリースノート生成
Task(release-note-composer, 要約1+2+...) → release-notes.md
8つの PR を渡してスキルを実行しました。
Step 1: ワークフローを振り返る
スキル実行後、以下のプロンプトでワークフローを振り返らせます。
ワークフローを通して得た知見を元にリファクタリングしてください。
うまくいったこと
| パターン | 効果 |
|---|---|
**CRITICAL** での強調 |
PR URL がない場合の確認が確実に動作 |
| 並列実行の明示的な指示 | 8つの PR が同時に解析され高速化 |
| ワークフローチェックリスト | 進捗が可視化され、ステップの抜け漏れがなくなった |
改善が必要だったこと
| 問題 | 原因 |
|---|---|
| サブエージェントが参照ファイルを見つけられない | 相対パスの指定が曖昧だった |
| 一部のステップがスキップされる | ワークフローの依存関係が不明確だった |
Step 2: 出力をレビューさせる
生成されたファイルを Claude に見せて、改善点を特定させます。
出力(release-notes.md)を見直し、スキルをリファクタリングしてください。
Claude が特定した問題点
| 問題 | 原因 | 影響 |
|---|---|---|
| 作成者が「Claude」になっている | 明示的な指示がない | 誰が作成したか不明 |
| 変更点が1つのリストに詰め込まれている | カテゴリ分けのルールがない | 読みにくい |
| 説明が冗長 | 簡潔さの指示がない | ドキュメントが長すぎる |
Step 3: ベストプラクティスを読ませる
公式ドキュメントを読ませてリファクタリングします。
https://platform.claude.com/docs/ja/agents-and-tools/agent-skills/best-practices
を元にリファクタリングしてください。
抽出された改善点
1. 簡潔さが鍵
SKILL.md を500行以下に保つ。Claude は既に賢いので、過度な説明は不要。
2. 段階的開示パターン
必要な時だけ参照ファイルを読み込む。すべてを SKILL.md に詰め込まない。
3. ワークフローチェックリスト
複雑なタスクは進捗チェックリストで追跡させる。
4. 1レベル深い参照
参照ファイルは SKILL.md から直接リンクする。ネストした参照は避ける。
リファクタリング結果
行数の変化
| ファイル | Before | After | 削減率 |
|---|---|---|---|
| SKILL.md | 164行 | 84行 | 49% |
| release-note-composer.md | 131行 | 100行 | 24% |
| pr-analyzer.md | 83行 | 66行 | 20% |
ワークフロー振り返りからの改善
CRITICAL での強調がうまくいったので、他の重要な指示にも適用しました。
## 起動時の処理
**CRITICAL**: PR URL がなければ即座にユーザーに尋ねる
並列実行を確実にするための指示を追加しました。
### Phase 1: PR 解析（並列）
**重要**: すべての Task を1つのメッセージで呼び出すこと。
出力レビューからの改善
出力の問題に対して、具体的なルールを追加しました。
**メタ情報のルール**:
- 作成者フィールドは **空欄にする**（後で人間が記入）
**カテゴリ分けルール**:
- **種類別に分割する**（1つのリストに全変更を詰め込まない）
- 例: 新機能、バグ修正、破壊的変更、依存関係更新など
**説明のルール**:
- 各項目は簡潔に記述（何が変わったか、なぜ変わったかのみ）
- 技術的な詳細は必要最小限に
この手法が効く理由
Claude は自分の出力を客観視できる
人間が「ここがダメ」と指摘するより、Claude 自身に「この出力を評価して」と聞く方が効率的です。Claude は自分の出力パターンを理解しているので、改善点を的確に特定できます。
公式ドキュメントは常に最新
ベストプラクティスは更新されていきます。毎回ドキュメントを「読ませる」ことで、最新のパターンを取り込めます。
蒸留は繰り返すほど効く
1回目の蒸留で完璧にはなりません。実際に使い続けて、新しい問題を見つけたらまた蒸留します。
蒸留のコツ
ワークフローを振り返らせる
# ❌ いきなりリファクタリング
スキルを改善してください
# ✅ ワークフローを振り返らせる
ワークフローを通して得た知見を元にリファクタリングしてください
出力を具体的に見せる
# ❌ 抽象的な依頼
出力を改善してください
# ✅ 具体的な出力を見せる
出力(release-notes.md)を見直し、スキルをリファクタリングしてください
ベストプラクティスの URL を渡す
# ❌ 自分の知識だけでリファクタリング
リファクタリングしてください
# ✅ 公式ドキュメントを参照させる
https://platform.claude.com/docs/ja/agents-and-tools/agent-skills/best-practices
を元にリファクタリングしてください
まとめ
スキルの蒸留は以下のサイクルで行います。
- 実行: スキルを実際に使う
- 振り返り: ワークフローで何がうまくいったかを特定する
- レビュー: 出力を Claude に評価させる
- 参照: ベストプラクティスを読ませる
- 改善: リファクタリングさせる
- 繰り返し: 新しい問題が見つかったらまた蒸留
ワークフローの振り返りと、Claude 自身に出力を評価させるアプローチが、スキルの品質を効率的に高める鍵です。
Discussion