| name | openclaw-agent-teams |
| description | Use when the user wants to design an agent team, write SOUL.md files, set up agent hierarchy, configure agent tools and permissions, understand memory architecture, set up cron schedules for agents, or follow best practices for organizing an OpenClaw agent team.
|
Agent Team Design & Operations
Guide the user through designing, building, and operating a production agent team following ClawPort best practices.
Hierarchy Design
Agent teams follow a three-tier hierarchy:
| Tier | Role | Example |
|---|
| Orchestrator | Top-level coordinator. Routes work, holds team memory, delivers briefings. | Jarvis (reportsTo: null) |
| Team Lead | Owns a domain pipeline end-to-end. Manages a sub-team. | VERA (Strategy), LUMEN (SEO), HERALD (LinkedIn) |
| Specialist | Does one thing well. Reports up, never manages others. | TRACE (Market Research), QUILL (LinkedIn Writer) |
Hierarchy Rules
- One root. Exactly one agent has
"reportsTo": null — the orchestrator.
- Team leads own pipelines. Each lead runs end-to-end delivery for their domain.
- Leaf agents are specialists. One job, no scope creep.
- Max depth of 3. Deeper nesting adds latency with little benefit.
- Keep directReports consistent. If B has
"reportsTo": "A", then A's directReports must include B.
SOUL.md — Agent Character Documents
Every agent needs a SOUL.md that defines identity, expertise, constraints, and relationships.
# AGENT_NAME -- Role Title
## Identity
Who the agent is. Personality. Communication style.
First-person voice: "I am VERA, the Chief Strategy Officer."
## Expertise
Domains this agent knows deeply.
What it defers to other agents.
## Operating Rules
Hard constraints. What it must always/never do.
Output format requirements.
## Relationships
Reports to. Direct reports. Peer collaborators.
## Memory
What it remembers between sessions.
Where its persistent knowledge lives.
Guidelines:
- Be specific about personality. Distinct voices prevent agents from sounding the same.
- Define what the agent does NOT do. Negative constraints are as important as positive ones.
- Include output format examples. If the agent produces structured data, show the format.
- Keep it under 500 lines. Long SOUL files dilute focus.
Naming Conventions
| Pattern | When to Use | Examples |
|---|
| UPPERCASE | Pipeline/team agents (callsign feel) | VERA, LUMEN, SCOUT, QUILL |
| Title Case | Standalone/personality agents, orchestrator | Jarvis, Robin, Pulse |
IDs are always lowercase slugs: vera, lumen, herald.
Tool Assignment (Least Privilege)
| Tool | Purpose | Who Gets It |
|---|
read | Read workspace files | Almost everyone (base capability) |
write | Write/create files | Content producers (WRITER, ANALYST) |
exec | Run shell commands | Orchestrator + team leads only |
web_search | Search the web | Research agents (TRACE, SCOUT, Pulse) |
web_fetch | Fetch a URL | Scraper/monitor agents (ECHO, KAZE) |
message | Send to other agents | Coordinators (Jarvis, Robin, Pulse) |
sessions_spawn | Spawn sub-sessions | Orchestrator + team leads only |
memory_search | Search team memory | Orchestrator only |
Never give exec to leaf agents. If a specialist needs a command run, it asks its team lead.
Memory Architecture
Three tiers working together:
| Tier | What | Lifespan | Who Manages |
|---|
| Daily Logs | Raw session output, timestamped | 7-14 days | Each agent writes its own |
| MEMORY.md | Curated persistent knowledge | Indefinite (updated weekly) | SCRIBE compresses weekly |
| Team Memory | Shared cross-agent knowledge | Indefinite | Team leads + orchestrator |
Full guide: See openclaw-memory skill for the four-layer memory model, bootstrap file setup, shared memory access patterns, SCRIBE compression rules, failure mode defenses, retrieval setup, and the /oc-memory command.
Agent Communication
Prefer files over messages:
- Upstream: Agent writes output file, team lead reads it next run.
- Downstream: Lead writes brief, specialist reads and executes.
- Cross-team: Agents read from
team-memory/ shared files.
The message tool is for urgency only (e.g., Pulse alerting about a breaking trend).
Cron Patterns
- Assign to the right tier: Research crons on leaf agents, pipeline crons on leads, briefing crons on orchestrator.
- Stagger schedules: Upstream agents finish before downstream agents read their output.
- One cron, one job: "Scan subreddits" is good. "Scan, analyze, write, and publish" is four crons pretending to be one.
- Error isolation: A failed cron only affects its own output. Stale data beats cascade failure.
Design Principles
- Agents are characters, not functions. Distinct names, personalities, expertise.
- Least privilege, always. Start without a tool; add it when proven necessary.
- Files over messages. Inspectable, diffable, persistent.
- One agent, one job. If the description needs "and" twice, split into two agents.
- Depth of 3, max. Add lateral agents instead of deeper nesting.
- Let SCRIBE handle memory. Single responsibility for memory compression.
See references/best-practices.md for the full implementation guide with registry examples, SCRIBE workflow, cron schedules, and workspace setup scripts.
