mpm-orchestration-demo

MPM 编排演示

概述

此技能是 Claude MPM 中 命令 → Agent → 技能 编排模式的权威参考。它演示了一个代码审查工作流，展示命令、Agent 和技能如何组合使用，以及调用技能的两种不同方式。

理解此模式是构建任何复杂 MPM 工作流的基础。

两种调用方式

方式 1：预加载技能（Frontmatter）

技能列在 Agent 的 skills: frontmatter 中。完整的技能内容会在启动时注入 Agent 的上下文，成为内嵌的领域知识。

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

适用场景： Agent 始终需要这类知识。这是 Agent 核心职责的一部分，而非仅在特定情况下需要。

特点：

• 从第一轮开始就能使用这些内容
• 无工具调用开销
• 即使不需要，也会消耗上下文令牌
• 最适合 1–3 个必备知识库

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

在运行时使用 Skill 工具调用技能。命令或 Agent 在需要此能力时调用 Skill(skill: "skill-name")。

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

适用场景： 此能力仅在特定情况下需要，或在收集初始数据后才需要。

特点：

• 仅在需要时调用
• 其他时候可保留上下文令牌
• 支持条件逻辑（“如果发现安全问题，则调用扫描器”）
• 最适合可选、有条件或开销较大的操作

具体示例：代码审查编排

此演示实现了一个由三个组件组成的代码审查系统。

流程

╔══════════════════════════════════════════════════════════════════╗
║              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)

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.

预加载技能：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

新工作流检查清单

• 命令是唯一入口和编排器
• Agent 专业分工明确（各司其职）
• 预加载技能包含始终需要的领域知识
• 动态技能包含有条件触发或特定于输出的逻辑
• Agent 返回结构化数据，而非散文
• 命令负责处理“如何使用结果”的逻辑

反模式

不要预加载所有内容。 向 Agent 加载 5 个技能会浪费上下文令牌并拖慢启动速度。只预加载核心领域知识，其余技能应动态调用。

不要把编排逻辑放进 Agent。 Agent 应专注于一项工作并返回数据。决策逻辑（“如果发现问题，就对其进行格式化”）应放在命令中。

不要从子 Agent 调用其他子 Agent。 子 Agent 无法通过 bash 调用其他子 Agent。所有 Agent 调用都必须通过命令或编排器上下文中的 Agent 工具进行。

不要省略结构化返回值。 返回非结构化散文的 Agent 很难被进一步处理。应定义清晰的返回格式（例如 ISSUE: [line] [severity] [desc]），以便命令作出决策。

不要重复技能内容。 如果两个 Agent 需要相同的知识，应创建一个共享技能并将其预加载到两个 Agent 中。切勿将技能内容复制粘贴到 Agent 定义中。

导航

• 编排模式：深入参考资料——带注释的天气系统示例、各种方式的适用场景、适用于继承父上下文的分叉子 Agent 的 context: fork 模式、Agent 通信模式、错误处理