Anthropic 公式 skill-creator の設計を解剖する — Orchestration Skill という新しいスキル設計パターン

@gyakuse（逆瀬川）氏のポストが、Anthropic 公式の skill-creator を分析した記事を公開し、大きな反響を呼んでいます（いいね 330、ブックマーク 372）。

Anthropicのskill-creatorがめちゃくちゃいいスキルだったので、中身を分析して、今後どういうふうにAgent Skillを作るべきかまとめました。Orchestrator系のSkillはみんなが無意識に作りつつありますが、意識的に作ると結構便利な気がします。

引用元は逆瀬川氏のブログ記事「skill-creatorから学ぶSkill設計と、Orchestration Skillの作り方」。Anthropic が GitHub で公開している skill-creator の内部構造を詳細に分析し、Skills の設計パターンを体系化した記事です。

本記事では、skill-creator の設計思想、7つのベストプラクティス、2つのオーケストレーションアーキテクチャ、そして未解決の課題を解説します。

skill-creator とは何か

「スキルを作るためのスキル」

skill-creator は、Claude Code の Skills を作成・テスト・改善するためのメタスキルです。Anthropic が公式リポジトリ anthropics/skills で公開しています。

4つのモードで Skills の開発ライフサイクル全体をカバーします。

モード	機能
Create	インタビュー → SKILL.md ドラフト作成 → テストケース生成
Eval	並列評価（スキルあり版 vs ベースライン版を同時実行）
Improve	採点・分析 → HTML ビューアでレビュー → フィードバック反映
Benchmark	統計集約 → Description 最適化 → パッケージング

4つの専門エージェント

skill-creator は内部で4つのサブエージェントを使い分けています。

エージェント	役割
Executor	Skills を実際に実行してテスト
Grader（224行）	出力を期待値と照合して採点
Comparator（203行）	スキルあり版とベースライン版を盲検比較
Analyzer（275行）	結果を分析して改善提案を生成

注目すべき数値があります。SKILL.md 本体は 480行のフロー制御ですが、サブエージェントのプロンプトは合計 700行以上。オーケストレーターよりも専門家プロンプトの方が分量が多いのです。

Progressive Disclosure — Skills の3層構造

なぜ3層なのか

Skills の設計において最も重要な概念は **Progressive Disclosure（段階的開示）**です。Anthropic の公式ドキュメントとエンジニアリングブログが、この原則を推奨しています。

[Level 1] name + description ← 常時システムプロンプトに注入（軽量）
    ↓ トリガー時のみ
[Level 2] SKILL.md ボディ   ← スキル発動時に読み込み
    ↓ 参照時のみ
[Level 3] scripts / references / assets ← 必要な時だけ読み込み

レベル	読み込みタイミング	コンテキスト消費
Level 1	常時（全セッション）	最小（name + description のみ）
Level 2	スキル発動時	中（SKILL.md 全文）
Level 3	参照時	大（スクリプト、リファレンス等）

この3層構造により、多数の Skills をインストールしてもコンテキストを圧迫しない設計が実現されています。Level 1 の description だけがシステムプロンプトに常駐し、残りは必要な時だけ読み込まれます。

7つのベストプラクティス

元記事が skill-creator の分析から導き出した7つのベストプラクティスを解説します。

1. SKILL.md はオーケストレーターに徹する

SKILL.md に処理の詳細を書かず、フロー制御に専念させます。専門的な処理は agents/ ディレクトリのサブエージェントプロンプトに委譲します。

.claude/skills/my-skill/
├── SKILL.md          ← フロー制御のみ（「何を」「どの順で」）
├── agents/
│   ├── grader.md     ← 採点の専門知識（「どう評価するか」）
│   ├── comparator.md ← 比較の専門知識（「どう比較するか」）
│   └── analyzer.md   ← 分析の専門知識（「どう改善するか」）
├── scripts/
│   └── run_eval.py   ← 確定的処理
└── references/
    └── schemas.md    ← データ契約

これは Anthropic の「Building Effective Agents」が定義する Orchestrator-Workers パターンの直接的な実装です。

2. 確定的処理をスクリプトにオフロードする

LLM が苦手な処理（数値計算、ファイル操作、並列実行）は Python や Bash スクリプトに移します。

スクリプト	処理内容	LLM が苦手な理由
`run_eval.py`	並列実行・ストリーム監視	並行処理の制御
`aggregate_benchmark.py`	3段階の数値集計	正確な数値計算
`improve_description.py`	Extended Thinking 活用	API パラメータの精密制御
`package_skill.py`	ファイル操作	ファイルシステム操作の信頼性

3. スキーマ契約で接続点を厳密化する

references/schemas.md で JSON スキーマを定義し、コンポーネント間のデータ形式を統一します。skill-creator は 7種のスキーマ（evals.json、grading.json、benchmark.json 等）を定義しています。

フィールド名の不一致がビューアのエラーに直結するため、スキーマは最初に設計することが推奨されます。

4. Why-driven Prompt Design

ルールを列挙するのではなく、理由を説明するプロンプトが効果的です。

1
2
❌ "ALWAYS validate input before processing"
✅ "Validation prevents API errors that waste tokens and break the workflow"

理由を説明することで、AI が未知のケースに遭遇した際にも原則に基づいて判断できます。ただし、絶対に守るべき制約（データ破壊を防ぐ操作など）には Must-driven で明示的に制約を書きます。

場面	アプローチ
一般的なガイダンス	Why-driven（理由を説明）
クリティカルな制約	Must-driven（ルールを明示）

5. description はトリガーの生命線

description は Skills の中で最も重要なフィールドです。システムプロンプトに常時注入されるのは name と description だけであり、Claude がスキルを使うかどうかは description で判断されます。

Anthropic の公式ベストプラクティスが指摘する重要な傾向があります。

Claude has a tendency to “undertrigger” skills – to not use them when they’d be useful.

Claude は Skills を使うべき場面で使わない「undertrigger」傾向があります。そのため、description は押し強めに書くことが推奨されています。

1
2
3
4
5
6
7
8
9
# ❌ 控えめな description
description: "Helps with data analysis"

# ✅ 押し強めの description
description: >
  Analyzes data and creates visualizations.
  Make sure to use this skill whenever user mentions
  dashboards, data visualization, charts, graphs,
  or asks to analyze CSV/Excel files.

skill-creator は description の最適化だけで専用スクリプト3個（run_loop.py、improve_description.py、run_eval.py）を使い、train/test 分割・3回実行・Extended Thinking（budget_tokens=10000）による統計的アプローチを取っています。

6. Human-in-the-Loop はチャット外に生成する

テキストベースのフィードバックには限界があります。skill-creator は eval-viewer/ で HTML ダッシュボードを生成し、ブラウザ上で構造化されたレビューを可能にしています。5秒の自動リフレッシュで最適化の進捗をリアルタイム表示します。

7. 環境別フォールバック

Claude Code / Claude.ai / Cowork など、異なる実行環境でも同じワークフローが動くよう、機能制約の明示と代替手段を提供します。コアワークフロー（ドラフト→テスト→レビュー→改善）は不変に保ち、実行方法だけを環境に適応させます。

2つのオーケストレーションアーキテクチャ

元記事が特に価値のある貢献をしているのは、Orchestration Skill を2つのアーキテクチャに分類した点です。

Sub-agent 型（skill-creator が採用）

SKILL.md（マネージャー）
  ├── Spawn → with_skill 版実行（並列）
  ├── Spawn → baseline 版実行（同ターン）
  ├── Spawn → agents/grader.md（評価）
  ├── Spawn → agents/comparator.md（盲検比較）
  └── agents/analyzer.md（分析）
  ↓
  集約 → ビューア → フィードバック → 改善 → 再ループ

特徴: 1つのスキル内でサブエージェントを動的に生成。並列性が高く、親の文脈を継承する。人間フィードバックが改善ループの中核。

Skill Chain 型

agentic-bench（制御）
  ↓ Phase 1
model-researcher スキル（調査）
  ↓ Phase 2
gpu-runner スキル（実行）
  ↓ Phase 3
eval-reporter スキル（レポート）

特徴: 独立したスキルを直列に連結。各スキルが単体でも利用可能。明確な順序性を持つ。

比較と選択基準

設計軸	Sub-agent 型	Skill Chain 型
実行モデル	スキル内でサブエージェント生成	独立スキルの連結
コンテキスト	サブが親の文脈を継承	各スキルがドメイン知識を保持
フロー	並列（同時 Spawn）	直列（順序フェーズ）
単体利用	サブエージェントは単体不可	各スキルが独立利用可能
人間関与	中間フィードバックが中核	コストゲートのみ
scripts/	必須コンポーネント	オプショナル

選択基準: タスクに並列性が必要（評価の同時実行、A/B テスト等）なら Sub-agent 型、明確な順序性があり各フェーズが独立再利用可能なら Skill Chain 型。

Anthropic の5パターンとの対応

Anthropic「Building Effective Agents」が定義する5つのエージェントパターンとの対応関係は以下の通りです。

Anthropic パターン	Skills での実装
Prompt Chaining	Skill Chain 型
Routing	description によるスキル選択
Parallelization	Sub-agent の並列 Spawn
Orchestrator-Workers	SKILL.md からサブエージェントへの委譲
Evaluator-Optimizer	skill-creator の改善ループ

skill-creator が優れているのは、これらのパターンを複合的に実装している点です。単一のパターンではなく、複数パターンの組み合わせでスキル開発ライフサイクル全体をカバーしています。

Skills は「小さなソフトウェア」になる

元記事が指摘する最も重要な変化は、Skills が「プロンプトの束」から**「小さなソフトウェア」**に進化していることです。

[Skills のソフトウェア的構造]

SKILL.md        → コントローラー（フロー制御）
agents/         → ドメインロジック（専門処理）
references/     → データ層（スキーマ、知識）
scripts/        → インフラ層（確定的処理）
eval-viewer/    → UI 層（人間向けダッシュボード）

これは MVC アーキテクチャとの類似性があります。SKILL.md がコントローラー、agents/ がモデル、eval-viewer/ がビューに対応します。

未解決の課題: Attention 競合問題

元記事が指摘する skill-creator の限界は、他スキルとの Attention 競合を考慮していない点です。

問題の構造

description の最適化は、対象スキルのみをインストールした環境でテストされます。しかし実際の運用では、複数のスキルが同時にシステムプロンプトに注入されます。

[テスト環境]
システムプロンプト + スキルA の description → トリガー率95%

[本番環境]
システムプロンプト + スキルA + スキルB + スキルC + ... の description
→ スキルA のトリガー率が低下（Attention が分散）

課題	説明
ゼロサム的 Attention 競合	スキル A の description を強化すると、スキル B のトリガー率が低下する可能性
テスト環境と本番の乖離	単体テストでは問題なくても、複数スキル共存時に不具合
description 長のジレンマ	長い description はトリガー率を上げるが、他スキルの Attention を奪う

今後の方向性

この課題の解決には、スキルセット全体（ポートフォリオ）の最適化が必要です。個別スキルの最適化ではなく、複数スキルの description を同時に最適化し、全体としてのトリガー精度を最大化するアプローチです。

まとめ

skill-creator は「スキルを作るスキル」: Create → Eval → Improve → Benchmark の4モードでスキル開発ライフサイクル全体をカバーするメタスキル
SKILL.md はオーケストレーターに徹する: 詳細処理はサブエージェントとスクリプトに委譲。SKILL.md 480行に対しサブエージェント700行以上
Progressive Disclosure の3層構造: name+description（常時）→ SKILL.md（発動時）→ scripts/references（参照時）でコンテキストを効率管理
description は「押し強め」に書く: Claude は undertrigger 傾向があるため、具体的な使用場面を明示的に列挙する
2つのオーケストレーションアーキテクチャ: 並列性なら Sub-agent 型、順序性なら Skill Chain 型を選択
Skills は「小さなソフトウェア」に進化: MVC 的な責務分離により、プロンプトの束からソフトウェア的な構造へ変化
未解決: Attention 競合問題: 複数スキル共存時のトリガー率低下を解決するポートフォリオ最適化が今後の課題

Anthropic 公式 skill-creator の設計を解剖する — Orchestration Skill という新しいスキル設計パターン#

skill-creator とは何か#

「スキルを作るためのスキル」#

4つの専門エージェント#

Progressive Disclosure — Skills の3層構造#

なぜ3層なのか#

7つのベストプラクティス#

1. SKILL.md はオーケストレーターに徹する#

2. 確定的処理をスクリプトにオフロードする#

3. スキーマ契約で接続点を厳密化する#

4. Why-driven Prompt Design#

5. description はトリガーの生命線#

6. Human-in-the-Loop はチャット外に生成する#

7. 環境別フォールバック#

2つのオーケストレーションアーキテクチャ#

Sub-agent 型（skill-creator が採用）#

Skill Chain 型#

比較と選択基準#

Anthropic の5パターンとの対応#

Skills は「小さなソフトウェア」になる#

未解決の課題: Attention 競合問題#

問題の構造#

今後の方向性#

まとめ#

参考#