Multi-Agent Architecture Skill

Multi-Agent Architecture

Design principles for orchestrating many sub-agents without context overflow.

Core Philosophy

Treat agent design like human hiring: write a job description first, then translate to architecture. The framing shapes every decision.

The Job Description Method

Before writing any agent code:

Write a human JD — What would you want this person to do? What qualities? What indicates success?
Identify handoff points — Where would a human need to check in or escalate?
Define the onboarding — What handbook would you give a new hire?
Translate to agents — Each JD section becomes architecture

| JD Section | Architecture Element | |------------|---------------------| | Responsibilities | Agent workflows | | Required skills | Tool permissions | | Success indicators | Output schemas | | Escalation criteria | Error handling | | Onboarding materials | Skills/handbook |

The Shared Folder Pattern

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:

Orchestrator context stays minimal
Sub-agents get full upstream context
No signal loss from summarization relay

The Handbook Pattern

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)

Context Budget Strategies

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

Architecture Decision Tree

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

Shared-State Mutation Safety

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.

Anti-Patterns

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

Iteration Path

Most multi-agent systems evolve through:

Slash commands — Quick start, context limits emerge
Orchestrator + sub-agents — Solves context, creates relay bottleneck
Shared folder — Solves relay, reveals skill fragmentation
Handbook consolidation — Unified knowledge, maintainable

Skip earlier stages when building new systems.

Agent Teams

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:

Teammates message each other directly (not just back to caller)
Shared task list with self-claiming and dependency auto-unblock
Each teammate is a full Claude Code session with own context

When to upgrade from sub-agents to Agent Teams:

Sub-agents need to share findings mid-task
You need adversarial debate or competing hypotheses
3+ workers need self-organizing coordination

For full setup, operations reference, and orchestration patterns, apply the agent-teams skill.

Agent Skills: Multi-Agent Architecture

Install this agent skill to your local

Skill Files