菜单
Patterns for designing multi-agent systems with Claude Code - job description method, shared folder communication, handbook consolidation, context management. Use when building complex agent orchestrations.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/majesticlabs-dev/majestic-marketplace --skill multi-agent-architecture命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
基于 SOC 职业分类
正在显示 SKILL.md
| name | multi-agent-architecture |
| description | Patterns for designing multi-agent systems with Claude Code - job description method, shared folder communication, handbook consolidation, context management. Use when building complex agent orchestrations. |
Design principles for orchestrating many sub-agents without context overflow.
Treat agent design like human hiring: write a job description first, then translate to architecture. The framing shapes every decision.
Before writing any agent code:
| JD Section | Architecture Element |
|---|---|
| Responsibilities | Agent workflows |
| Required skills | Tool permissions |
| Success indicators | Output schemas |
| Escalation criteria | Error handling |
| Onboarding materials | Skills/handbook |
Problem: Orchestrator context overwhelmed when 10+ sub-agents return detailed reports simultaneously.
Solution: Sub-agents write to temp folder → downstream agents read directly.
.claude/workspace/
├── phase-1/
│ ├── gmail-analysis.md
│ ├── calendar-analysis.md
│ └── drive-inventory.md
├── phase-2/
│ ├── client-summary.md
│ └── action-items.md
└── manifest.yml
Workflow:
1. Orchestrator spawns sub-agents
2. Each sub-agent:
- Does work
- Writes report to .claude/workspace/{phase}/{name}.md
- Returns only: { status: "complete", path: "..." }
3. Downstream agents read prior phase outputs directly
4. Orchestrator reads manifest, not full reports
Benefits:
Problem: Many narrow skills create fragility and maintenance burden.
Solution: One handbook organized by chapters, read foundation + relevant sections.
skills/project-manager/
├── SKILL.md # Entry point, routes to chapters
└── references/
├── 01-foundation.md # Who we are, tools, escalation, standards
├── 02-daily-ops.md # Data gathering procedures
├── 03-dashboards.md # Structure, quality checks
└── 04-onboarding.md # New client setup
Chapter Structure:
| Chapter | Contents |
|---|---|
| Foundation | Team, tools, data sources, escalation rules, quality standards |
| Domain chapters | Specific procedures for each responsibility area |
Reading Pattern:
Sub-agent reads:
1. Foundation chapter (always)
2. Relevant domain chapter(s) (based on task)
| Strategy | When to Use |
|---|---|
| Shared folder | 5+ sub-agents, inter-agent dependencies |
| Context proxy | Research agents returning verbose results |
| Manifest files | Orchestrator needs status, not details |
| Chunked execution | Serial phases when parallel overwhelms |
How many sub-agents?
├── 1-3 → Direct orchestration (return reports to main)
├── 4-10 → Shared folder pattern
└── 10+ → Phased execution with manifest
Do teammates need direct communication?
├── No → Sub-agents (Task tool) — report results back only
└── Yes → Agent Teams — shared task list, inter-agent messaging
├── See agent-teams skill for full guide
└── Best for: parallel review, competing hypotheses, multi-module features
Do sub-agents need each other's output?
├── No → Parallel execution, merge results
└── Yes → Shared folder, dependency ordering
Is orchestrator context a concern?
├── No → Return full reports
└── Yes → Status-only returns + file paths
When multiple agents can transition the same work item (issue, task, label) through states, silent race conditions cause duplicate work or skipped transitions.
Three-step guard (apply before every state write):
1. READ — Re-fetch current state immediately before mutation (never use cached state)
2. VERIFY — Confirm state matches expected pre-condition
3. WRITE — Apply transition in a single atomic operation
Implementation pattern:
CURRENT_STATE = fetch_state(item_id) # live read, not cached
If CURRENT_STATE != EXPECTED_PRE_STATE:
ABORT — log stale-race, do not mutate
Else:
apply_transition(item_id, NEW_STATE) # single atomic call
For GitHub labels specifically:
CURRENT_LABELS = gh issue view {id} --json labels
If EXPECTED_LABEL not in CURRENT_LABELS:
ABORT — another agent already transitioned this item
Else:
gh issue edit {id} --remove-label {old} --add-label {new} # one call
Decision table:
| Scenario | Action |
|---|---|
| State matches expectation | Apply transition atomically |
| State already at target | Skip silently (idempotent) |
| State at unexpected value | Abort, log conflict, do not retry |
| Item not found | Abort, log missing item |
Why single atomic call matters: Two separate --remove-label and --add-label calls create a window where another agent reads the item in an intermediate state. Combine into one gh issue edit invocation.
| Pattern | Problem | Fix |
|---|---|---|
| Slash commands as orchestration | Context exhaustion before work starts | Move to sub-agents |
| Orchestrator relays all context | Bottleneck, signal loss | Shared folder |
| One skill per micro-task | Fragile, hard to maintain | Handbook chapters |
| Sub-agents return full reports | Context overflow at 10+ agents | Path-only returns |
Most multi-agent systems evolve through:
Skip earlier stages when building new systems.
When workers need to communicate directly with each other — not just report back to an orchestrator — use Agent Teams instead of sub-agents. Agent Teams provide shared task lists, inter-agent messaging, and independent context windows.
Key differences from sub-agent patterns above:
When to upgrade from sub-agents to Agent Teams:
For full setup, operations reference, and orchestration patterns, apply the agent-teams skill.