# Subagent Brief

> Write a sub-agent brief that survives the messaging asymmetry — explicit inputs, explicit outputs, and a degraded-mode paragraph so the sub-agent completes instead of silently stalling. Use when the user says "brief a sub-agent", "spawn an agent to…", "subagent brief", or is designing a multi-agent / swarm step.

- Skill: `aimasteracc/subagent-brief` (Agent Skill)
- Install (CLI): `npx skillmds@latest add aimasteracc/subagent-brief`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aimasteracc/subagent-brief/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: aimasteracc (https://skillmd.com/u/aimasteracc)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aimasteracc/subagent-brief

---


# subagent-brief — Brief sub-agents so they don't silently fail

## Purpose

The single most common way multi-agent setups break: a lead spawns a sub-agent and assumes
it can wait for messages, coordinate with siblings, or call tools it doesn't actually have.
Sub-agents are usually **stateless one-shot workers** — no inbox, no ability to wait, often
without the coordination tools the prompt assumed. A brief that ignores this produces an agent
that aborts cleanly or runs on stale assumptions. This skill writes a brief that *works*.

## How to run

1. **Clarify the job:** what this one agent must produce, and what it needs to start.
2. **Resolve coordination to a bus, not to messaging.** Inter-agent state goes through a
   shared medium the lead controls (memory keys, files, a scratch dir) — never "wait for a
   message from another agent."
3. **Write the brief** using the template. Every brief MUST include a degraded-mode paragraph.
4. **State the spawn rule** to the lead: parallelize only genuinely independent work; spawn
   dependent agents only *after* the lead has verified upstream outputs exist.

## The brief template

```
ROLE: <one-line role, e.g. "API contract extractor">

DEGRADED MODE (read first): If your expected coordination tools (messaging, task-update,
swarm/hive tools) are missing or error, do NOT abort. Read your inputs directly from the
paths/keys below, do the work, and write your outputs to the specified destinations. Then end.

INPUTS (read these exact sources):
- <file path / memory key / dir> — <what it contains>
- ...

TASK:
- <the concrete deliverable, with any constraints / format>

OUTPUTS (write exactly here, then stop):
- <destination path / memory key> — <shape of what you write, e.g. JSON schema>

DONE = <observable condition the lead can verify, e.g. "file exists and parses as JSON">
Do NOT wait for messages. Do NOT depend on sibling agents. If a needed input is missing,
write a `<dest>.blocked` note explaining what's missing, and stop.
```

## Spawn rules (give these to the lead)
- **Parallelize only independent work** — siblings with no dependency between them.
- **Chain dependents through the lead.** Lead spawns A → verifies A's output exists → spawns B
  with A's output path in its brief. Never tell B to "wait for A."
- **Name every agent** so the lead can address it; sub-agents can't address each other.
- **After spawning, the lead verifies outputs** before the next phase — the bus is the source
  of truth, not a message that may never arrive.

## Anti-patterns (these silently fail — never write them into a brief)
- "Wait for a message from X before starting." (No mechanism to wait → it aborts or runs open-loop.)
- "Send your findings to <other agent>." (Peers can't receive.)
- "Coordinate with the other agents to divide the work." (No peer channel exists.)
- Spawning N interdependent agents in one batch expecting them to chain via messages.

## Notes
- The degraded-mode paragraph is mandatory. It's what converts a fragile assumption into a
  worker that finishes regardless of which coordination tools happen to be present.