mpm-orchestration-demo

MPM オーケストレーションのデモ

概要

このスキルは、Claude MPM における コマンド → エージェント → スキル のオーケストレーションパターンを示す標準リファレンスです。コマンド、エージェント、スキルを組み合わせる方法と、スキルを呼び出す 2 つの異なる方法を紹介するコードレビューのワークフローを実演します。

このパターンを理解することが、複雑な MPM ワークフローを構築するための基盤となります。

2 つの呼び出し方法

方法 1：事前読み込みスキル（フロントマター）

エージェントの skills: フロントマターにスキルを記載します。スキルの内容全体が起動時にエージェントのコンテキストに挿入され、組み込みのドメイン知識となります。

# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: Reviews code for quality, security, and correctness
skills:
  - code-review-checklist    # Injected at startup
model: sonnet
---

使用するタイミング： エージェントが常にこの知識を必要とする場合です。状況に応じて使うものではなく、エージェントの目的の中核となる知識です。

特徴：

• 最初のターンから内容を利用できます
• ツール呼び出しのオーバーヘッドがありません
• 必要ない場合でもコンテキストトークンを消費します
• 1～3 個の必須ナレッジベースに最適です

方法 2：動的呼び出し（スキルツール）

Skill ツールを使用して、実行時にスキルを呼び出します。必要になったときに、コマンドまたはエージェントが Skill(skill: "skill-name") を呼び出します。

# In a command or agent's instructions
Skill(skill: "security-scanner")

使用するタイミング： 特定の条件下、または初期データを収集した後にのみ必要となる、状況依存の機能に使用します。

特徴：

• 必要なときだけ呼び出されます
• それ以外の場合はコンテキストトークンを節約できます
• 条件付きロジックを実現できます（「セキュリティ上の問題が見つかったら、スキャナーを呼び出す」など）
• 任意の処理、条件付き処理、または負荷の高い処理に最適です

具体例：コードレビューのオーケストレーション

このデモでは、3 つのコンポーネントで構成されるコードレビューシステムを実装します。

フロー

╔══════════════════════════════════════════════════════════════════╗
║              CODE REVIEW ORCHESTRATION                           ║
║           Command  →  Agent  →  Skill                            ║
╚══════════════════════════════════════════════════════════════════╝

                       ┌─────────────────────┐
                       │    User invokes      │
                       │  /code-review-demo   │
                       └──────────┬──────────┘
                                  │
                                  ▼
         ┌──────────────────────────────────────────────────┐
         │  /code-review-demo — Command (Entry Point)       │
         │  1. Accept file path argument                    │
         │  2. Invoke code-reviewer agent (Agent tool)      │
         │  3. If issues found: Skill("issue-formatter")    │
         └──────────────────────┬───────────────────────────┘
                                │
                        Agent tool call
                                │
                                ▼
         ┌──────────────────────────────────────────────────┐
         │  code-reviewer — Agent                           │
         │  skills: [code-review-checklist]  ← Style 1     │
         │                                                  │
         │  Uses preloaded checklist to review the file     │
         │  Returns: list of issues (or "no issues")        │
         └──────────────────────┬───────────────────────────┘
                                │
                       Returns issues
                                │
         ┌──────────────────────▼───────────────────────────┐
         │  Command receives issues                         │
         │  Conditionally invokes:                          │
         │  Skill("issue-formatter")  ← Style 2             │
         └──────────────────────┬───────────────────────────┘
                                │
                                ▼
                      ┌─────────────────────┐
                      │  issue-formatter    │
                      │  Formats and writes │
                      │  review-report.md   │
                      └─────────────────────┘

コンポーネントの定義

コマンド：/code-review-demo

---
# .claude/commands/code-review-demo.md
description: Demo orchestration command for code review workflow
model: haiku
---

# Code Review Demo

Accept a file path as $ARGUMENTS.

1. Use the Agent tool to invoke code-reviewer:
   Agent(subagent_type="code-reviewer", prompt="Review $ARGUMENTS for quality and security issues")

2. If the agent returns any issues:
   Skill(skill: "issue-formatter")

3. Report: file reviewed, issue count, report location (if written)

エージェント：code-reviewer

---
# .claude/agents/code-reviewer.md
name: code-reviewer
description: Reviews code files for quality, security, and correctness
tools: Read
model: sonnet
skills:
  - code-review-checklist
---

You are a code reviewer. Use your preloaded code-review-checklist skill to
evaluate the file specified in the prompt. Return a structured list of issues,
or "NO_ISSUES" if the code is clean.

事前読み込みスキル：code-review-checklist

---
# .claude/skills/code-review-checklist/SKILL.md
name: code-review-checklist
user-invocable: false
---

# Code Review Checklist

Review code against these criteria:

1. Input validation — are all inputs validated before use?
2. Error handling — are errors caught and handled gracefully?
3. Null safety — are null/undefined values handled?
4. Security — SQL injection, XSS, hardcoded secrets?
5. Complexity — functions over 20 lines or cyclomatic complexity > 5?

Return findings as:
ISSUE: [line] [severity] [description]

動的スキル：issue-formatter

---
# .claude/skills/issue-formatter/SKILL.md
name: issue-formatter
description: Formats code review findings into a structured markdown report
---

# Issue Formatter

Format the issues from the current conversation into review-report.md.

Structure:
- Summary: total issues by severity
- Critical issues (fix before merge)
- Warnings (should fix)
- Suggestions (optional improvements)

パターンテンプレート

新しい MPM オーケストレーションワークフローを構築するときは、このテンプレートをコピーしてください。

COMMAND (.claude/commands/my-workflow.md)
  ├── Accepts user arguments
  ├── Invokes specialized AGENT via Agent tool
  │     └── Agent has PRELOADED SKILL(s) for core knowledge (Style 1)
  ├── Receives structured result from agent
  └── Conditionally invokes DYNAMIC SKILL via Skill tool (Style 2)
        └── Skill formats or persists the result

新しいワークフローのチェックリスト

• コマンドが唯一のエントリーポイント兼オーケストレーターである
• エージェントが専門化されている（責任は 1 つ）
• 事前読み込みスキルに、常に必要なドメイン知識が含まれている
• 動的スキルに、条件付きロジックまたは出力固有のロジックが含まれている
• エージェントが散文ではなく、構造化データを返す
• コマンドが「結果をどう扱うか」のロジックを担う

アンチパターン

すべてを事前読み込みしないでください。 5 つのスキルをエージェントに読み込むと、コンテキストトークンを浪費し、起動が遅くなります。事前読み込みは中核となるドメイン知識だけにし、それ以外は動的に呼び出してください。

オーケストレーションのロジックをエージェントに含めないでください。 エージェントは 1 つの処理を行い、データを返すべきです。「問題が見つかったら整形する」といった判断ロジックは、コマンドに含めてください。

サブエージェントから別のサブエージェントを呼び出さないでください。 サブエージェントは bash 経由で別のサブエージェントを呼び出せません。エージェントの呼び出しはすべて、コマンドまたはオーケストレーターのコンテキストから Agent ツールを通じて行う必要があります。

構造化された戻り値を省略しないでください。 構造化されていない散文を返すエージェントの出力は、処理が困難です。コマンドが判断できるよう、明確な戻り値の形式（例：ISSUE: [line] [severity] [desc]）を定義してください。

スキルの内容を重複させないでください。 2 つのエージェントが同じ知識を必要とする場合は、共有スキルを 1 つ作成し、両方に事前読み込みしてください。スキルの内容をエージェント定義にコピー＆ペーストしないでください。

ナビゲーション

• オーケストレーションパターン：詳細なリファレンス — 注釈付きの気象システムの例、各方法を使うタイミング、親コンテキストを引き継ぐフォークされたサブエージェント向けの context: fork パターン、エージェント間の通信パターン、エラー処理