mpm-orchestration-demo

What this skill does

# MPM Orchestration Demo

## Overview

This skill is the canonical reference for the **Command → Agent → Skill** orchestration pattern in Claude MPM. It demonstrates a code review workflow that shows how commands, agents, and skills compose together — and the two distinct ways a skill can be invoked.

Understanding this pattern is the foundation for building any non-trivial MPM workflow.

## The Two Invocation Styles

### Style 1: Preloaded Skills (Frontmatter)

A skill is listed in an agent's `skills:` frontmatter. The full skill content is injected into the agent's context at startup, becoming embedded domain knowledge.

```yaml
# .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
---
```

**When to use:** The agent always needs this knowledge. It's core to the agent's purpose — not situational.

**Characteristics:**
- Content is present from the first turn
- No tool call overhead
- Consumes context tokens even if not needed
- Best for 1–3 essential knowledge bases

### Style 2: Dynamic Invocation (Skill Tool)

A skill is invoked at runtime using the `Skill` tool. The command or agent calls `Skill(skill: "skill-name")` when it needs that capability.

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

**When to use:** The capability is situational — only needed under certain conditions or after gathering initial data.

**Characteristics:**
- Invoked only when needed
- Preserves context tokens otherwise
- Enables conditional logic ("if security issues found, invoke scanner")
- Best for optional, conditional, or heavyweight operations

## Concrete Example: Code Review Orchestration

This demo implements a three-component code review system.

### Flow

```
╔══════════════════════════════════════════════════════════════════╗
║              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   │
                      └─────────────────────┘
```

### Component Definitions

#### Command: `/code-review-demo`

```markdown
---
# .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)
```

#### Agent: `code-reviewer`

```markdown
---
# .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.
```

#### Preloaded Skill: `code-review-checklist`

```markdown
---
# .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]
```

#### Dynamic Skill: `issue-formatter`

```markdown
---
# .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)
```

## Pattern Template

Copy this template when building a new MPM orchestration workflow:

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

### Checklist for New Workflows

- [ ] Command is the single entry point and orchestrator
- [ ] Agents are specialized (one responsibility)
- [ ] Preloaded skills contain always-needed domain knowledge
- [ ] Dynamic skills contain conditional or output-specific logic
- [ ] Agent returns structured data, not prose
- [ ] Command handles the "what to do with results" logic

## Anti-Patterns

**Don't preload everything.** Loading 5 skills into an agent wastes context tokens and slows startup. Preload only core domain knowledge; invoke the rest dynamically.

**Don't put orchestration logic in agents.** An agent should do one thing and return data. Decision logic ("if issues found, format them") belongs in the command.

**Don't invoke subagents from subagents.** Subagents cannot invoke other subagents via bash. All agent invocations must go through the Agent tool from a command or orchestrator context.

**Don't skip structured return values.** An agent that returns unstructured prose is hard to act on. Define a clear return format (e.g., `ISSUE: [line] [severity] [desc]`) so the command can make decisions.

**Don't duplicate skill content.** If two agents need the same knowledge, create one shared skill and preload it into both. Never copy-paste skill content into agent definitions.

## Navigation

- **[Orchestration Patterns](references/orchestration-patterns.md)**: Deep-dive reference — annotated weather system example, when to use each style, agent communicatio