Mpm Orchestration Demo

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.

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

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

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

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

---
# .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, the context: fork pattern for forked sub-agents that inherit parent context, agent communication patterns, error handling

Orchestration Patterns — Deep Dive

The Canonical Example: Weather System

The weather system in claude-code-best-practice is the reference implementation for Command → Agent → Skill orchestration. This section walks through it annotated, then generalizes the patterns.

Weather System Components

/weather-orchestrator   ← Command: entry point, user interaction
    │
    ├─ Agent("weather-agent")        ← Agent tool call
    │      skills: [weather-fetcher]  ← Style 1: preloaded
    │      Returns: temperature + unit
    │
    └─ Skill("weather-svg-creator")  ← Style 2: dynamic
           Creates: weather.svg, output.md

Why this structure?

The command splits responsibilities cleanly:

• "Get the data" goes to a specialized agent with domain knowledge preloaded
• "Render the data" goes to a skill invoked after the data is available

Neither the agent nor the SVG skill needs to know about the other. The command is the only component with the full picture.

Annotated Flow

Step 1: User runs /weather-orchestrator
        Command: "Celsius or Fahrenheit?" → user responds

Step 2: Command → Agent tool
        Agent: weather-agent
        Prompt: "Get Dubai temperature in Celsius"

        weather-agent has weather-fetcher preloaded:
        └─ Skill content injected at agent startup
        └─ Agent follows skill instructions, calls Open-Meteo API
        └─ Returns: "temperature=26, unit=Celsius"

Step 3: Command receives structured result
        Command → Skill tool
        Skill: weather-svg-creator
        Context includes: temperature=26, unit=Celsius

        weather-svg-creator runs:
        └─ Reads SVG template from reference.md
        └─ Writes orchestration-workflow/weather.svg
        └─ Writes orchestration-workflow/output.md

Step 4: Command reports result to user

When to Use Each Style

Use Preloaded Skills (Style 1) When

The knowledge is always relevant to the agent's purpose.

# Good: security-auditor always needs these standards
skills:
  - owasp-top-10
  - secure-coding-checklist

The knowledge is compact (under ~400 tokens). Preloading large skills wastes context.

You have 1–3 skills. Beyond that, consider whether some should be invoked dynamically instead.

Examples:

• A sql-optimizer agent preloading query-patterns
• A docs-writer agent preloading style-guide
• A test-runner agent preloading test-standards

Use Dynamic Invocation (Style 2) When

The skill is conditional — only needed based on what was found.

# Only format a report if issues were found
if issues:
    Skill("issue-formatter")

The skill produces output — files, reports, artifacts. These are naturally downstream.

The skill is heavyweight — large context, many instructions. Don't pay the cost unless needed.

The skill is shared across commands — a formatting skill invoked by multiple commands.

Examples:

• A report formatter invoked only when there's something to report
• A notification skill invoked only on failure
• A diagram generator invoked after analysis completes

The context: fork Pattern

Beyond preloaded (Style 1) and dynamic (Style 2) skill invocation, an agent can run as a forked sub-agent that inherits the parent's accumulated context. This is the context: fork pattern: instead of starting the sub-agent with a clean slate, the orchestrator forks the current context so the sub-agent sees everything gathered so far.

Fresh Context vs. Forked Context

DEFAULT (fresh context):
  Command gathers data → Agent("specialist") starts CLEAN
  └─ Sub-agent sees only the prompt; parent findings must be
     re-passed explicitly in the prompt string.

context: fork:
  Command gathers data → Agent("specialist", context: fork)
  └─ Sub-agent INHERITS the parent conversation: prior findings,
     file reads, and intermediate results are already present.

Where Fork Fits in the Orchestration Flow

Step 1: /code-review-demo gathers context
        └─ Reads src/auth.py, src/api.py (now in parent context)

Step 2: Command → Agent tool with fork
        Agent(
          subagent_type="code-reviewer",
          context: fork,                  ← inherit parent context
          prompt="Review the files already read for security issues"
        )
        └─ Forked code-reviewer already sees the file contents;
           no need to re-read or re-pass them.

Step 3: Forked agent returns structured issues
        └─ Parent continues; context: fork did not pollute the
           parent with the agent's internal reasoning.

When to Fork vs. Start Fresh

Use context: fork when the sub-agent's work depends on substantial context the orchestrator already gathered — file contents, prior analysis, or a running decision trail — and re-passing it in the prompt would be lossy or expensive.

Start fresh (the default) when the sub-agent's task is self-contained and a clean, focused context produces better results. A fresh context avoids distracting the sub-agent with irrelevant parent history.

Fork and the Two Invocation Styles

context: fork composes with both styles. A forked agent still preloads its skills: frontmatter (Style 1) and can still invoke dynamic skills via the Skill tool (Style 2). Fork governs what context the agent starts with, not how skills attach to it. Preloaded skills are injected on top of the inherited context; dynamic skills run downstream as usual.

Anti-pattern: Do not fork by default. Forking every sub-agent carries the full parent history into each one, inflating token cost and risking context pollution where a focused, fresh agent would perform better. Reserve fork for genuine context-dependence.

Agent Communication Patterns

Return Format Contract

Agents should return structured data that commands can parse and act on. Define the contract explicitly in the agent definition.

Good: structured return

# In agent definition
Return your findings as:
RESULT: [status]
ISSUES: [count]
DETAILS:
- ISSUE: [line] [severity] [description]

Bad: unstructured prose

I reviewed the code and found a few potential issues. The function on line 47
could potentially throw a NullPointerException if the input is null...

Prose requires the command to interpret natural language. Structured data enables deterministic logic.

Passing Data to Skills

When a command invokes a dynamic skill via Skill(skill: "name"), the skill receives the full conversation context. This means data the agent returned is automatically available.

Command receives: "temperature=26, unit=Celsius"
Command invokes: Skill("weather-svg-creator")
Skill sees in context: "temperature=26, unit=Celsius"
Skill uses it: no explicit parameter passing needed

This is the key insight: skills read from context, not from explicit arguments. Structure agent return values so downstream skills can find what they need.

Agent Tool Syntax

# Correct: use subagent_type, not "launch" or "run"
Agent(
    subagent_type="code-reviewer",
    description="Review src/auth.py for security issues",
    prompt="Review the file src/auth.py. Return findings in structured format."
)

Note: use subagent_type, not a bash invocation. Subagents cannot be launched via shell commands.

Error Handling in Orchestration Chains

At the Command Level

Commands should handle agent failures explicitly:

# In command definition
If the agent returns an error or "FAILED":
- Log the error
- Report failure to user with context
- Do NOT proceed to downstream skills

At the Agent Level

Agents should return distinguishable failure states:

SUCCESS: [data]
FAILED: [reason]
NO_RESULT: [explanation]

Never let an agent return empty output — the command cannot distinguish "nothing to report" from "I failed silently."

Defensive Skill Design

Skills should validate their inputs from context before proceeding:

# In skill definition
Before creating output:
1. Verify the required data is present in context
2. If missing: output "ERROR: required data not found — [what was expected]"
3. Do not create partial output files

Composition Depth

Keep orchestration chains to two levels: Command → Agent → Skill.

GOOD: Command → Agent (with preloaded skill) → Dynamic Skill
BAD:  Command → Agent → Agent → Agent → Skill

Deep chains create debugging nightmares. If you need more steps, structure them sequentially in the command rather than nesting agents.

# Better: sequential steps in command
1. Agent("analyzer") → findings
2. Agent("planner", context=findings) → plan
3. Skill("reporter", context=plan) → report

Each step is visible and debuggable from the command level.

File Organization Reference

.claude/
├── commands/
│   └── my-workflow.md          # Entry point command
├── agents/
│   └── my-specialist.md        # Specialized agent
│       # skills: [preloaded-knowledge]
└── skills/
    ├── preloaded-knowledge/
    │   └── SKILL.md             # Style 1: preloaded
    │       # user-invocable: false
    └── output-formatter/
        └── SKILL.md             # Style 2: dynamic
            # description: enables auto-discovery

Quick Reference Card