Back to Details

mpm-orchestration-demo

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

MPM Orchestration Demo

MPM编排演示

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.
本技能是Claude MPM中Command→Agent→Skill编排模式的标准参考实现。它演示了一个代码审查工作流，展示了命令、代理和技能如何组合在一起，以及调用技能的两种不同方式。
理解此模式是构建任何复杂MPM工作流的基础。

The Two Invocation Styles

两种调用方式

Style 1: Preloaded Skills (Frontmatter)

方式1：预加载技能（前置元数据）

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
undefined
技能在代理的
skills:
前置元数据中列出。完整的技能内容会在启动时注入到代理的上下文环境中，成为嵌入的领域知识。
yaml
undefined

.claude/agents/code-reviewer.md

.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
name: code-reviewer description: Reviews code for quality, security, and correctness skills:
  • code-review-checklist # Injected at startup model: sonnet

**适用场景：** 代理始终需要该知识，它是代理核心用途的一部分，而非情境性需求。

**特点：**
- 内容从第一轮交互就存在
- 无工具调用开销
- 即使不需要也会消耗上下文令牌
- 最适合1–3个核心知识库

Style 2: Dynamic Invocation (Skill Tool)

方式2：动态调用（Skill工具）

A skill is invoked at runtime using the 
Skill
tool. The command or agent calls 
Skill(skill: "skill-name")
when it needs that capability.
undefined
在运行时使用
Skill
工具调用技能。当命令或代理需要该能力时，会调用
Skill(skill: "skill-name")
。
undefined

In a command or agent's instructions

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
Skill(skill: "security-scanner")

**适用场景：** 该能力是情境性的——仅在特定条件下或收集初始数据后才需要。

**特点：**
- 仅在需要时调用
- 否则可节省上下文令牌
- 支持条件逻辑（"如果发现安全问题，则调用扫描器"）
- 最适合可选、条件性或重量级操作

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

命令：
/code-review-demo

markdown
---
markdown
---

.claude/commands/code-review-demo.md

.claude/commands/code-review-demo.md

description: Demo orchestration command for code review workflow model: haiku

description: Demo orchestration command for code review workflow model: haiku

Code Review Demo

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)
undefined
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)
undefined

Agent: 
code-reviewer

代理：
code-reviewer

markdown
---
markdown
---

.claude/agents/code-reviewer.md

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

Preloaded Skill: 
code-review-checklist

预加载技能：
code-review-checklist

markdown
---
markdown
---

.claude/skills/code-review-checklist/SKILL.md

.claude/skills/code-review-checklist/SKILL.md

name: code-review-checklist user-invocable: false

name: code-review-checklist user-invocable: false

Code Review Checklist

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]
undefined
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]
undefined

Dynamic Skill: 
issue-formatter

动态技能：
issue-formatter

markdown
---
markdown
---

.claude/skills/issue-formatter/SKILL.md

.claude/skills/issue-formatter/SKILL.md

name: issue-formatter description: Formats code review findings into a structured markdown report

name: issue-formatter description: Formats code review findings into a structured markdown report

Issue Formatter

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)
undefined
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)
undefined

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
构建新的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

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.
不要预加载所有内容。 向代理加载5个技能会浪费上下文令牌并减慢启动速度。仅预加载核心领域知识；其余内容通过动态调用。
不要在代理中放入编排逻辑。 代理应专注于完成一件事并返回数据。决策逻辑（“如果发现问题，则格式化它们”）应放在命令中。
不要从子代理调用子代理。 子代理无法通过bash调用其他子代理。所有代理调用必须通过命令或编排器上下文使用Agent工具进行。
不要跳过结构化返回值。 返回非结构化散文的代理难以被后续操作处理。定义清晰的返回格式（例如
ISSUE: [line] [severity] [desc]
），以便命令可以做出决策。
不要重复技能内容。 如果两个代理需要相同的知识，创建一个共享技能并将其预加载到两个代理中。切勿将技能内容复制粘贴到代理定义中。

Navigation

导航

  • Orchestration Patterns: 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
  • 编排模式: 深度参考——带注释的天气系统示例、每种方式的适用场景、用于继承父上下文的分叉子代理的
    context: fork
    模式、代理通信模式、错误处理