A reusable Codex skill for structured multi-agent research and problem solving.
multi-agent is designed for problems where a single linear pass is likely to converge too early. It organizes research around genuinely different approach families, explicit evidence, falsification, validation, and controlled escalation.
The skill provides three operating modes:
- LIGHT — focused verification / cheap investigation.
- DEEP — structured multi-agent investigation.
- MAX — exhaustive adversarial orchestration.
Invocation:
$multi-agent light <task>
$multi-agent deep <task>
$multi-agent max <task>
$multi-agent <task>
A bare invocation now defaults to LIGHT.
Important
This is an independent community skill. It is not an official OpenAI skill and is not endorsed or maintained by OpenAI.
Multi-agent systems can fail in a surprisingly ordinary way: several agents explore minor variations of the same idea, converge too early, and then spend the remaining budget confirming the first plausible answer.
This skill is built around a different research model:
CLASSIFY
↓
DEFINE SUCCESS + CONSTRAINTS
↓
BUILD DISTINCT APPROACH FAMILIES
↓
COLLECT EVIDENCE
↓
MAINTAIN RESEARCH STATE
↓
ADVERSARIAL FALSIFICATION
↓
VALIDATION
↓
VERIFIED RESULT OR JUSTIFIED STOP
The central idea is:
Previous conclusions are research state, not truth.
| Mode | Agents | Rounds | Families | Automatic selection |
|---|---|---|---|---|
LIGHT |
root + max 1 subagent | max 1 delegation round + focused review | max 2 | YES, default |
DEEP |
bounded multiple agents | multiple | multiple | only for strong concrete need |
MAX |
aggressive use of available capacity | multiple | broad portfolio | NEVER |
The agent/subagent limits above are skill-level orchestration constraints. They are not hard counters enforced by the underlying platform.
Full mode semantics are documented in references/modes.md.
LIGHT is optimized for useful information per unit of orchestration cost.
It prefers:
- existing context;
- known files and findings;
- focused inspection;
- micro-probes;
- existing relevant tests;
- at most two genuinely different approach families;
- root + at most one subagent;
- one delegation round;
- a focused adversarial review;
- concise evidence-backed output.
LIGHT should not automatically perform a repository-wide exploration when the target is already known.
LIGHT never promotes itself to DEEP.
If the problem cannot be resolved inside the LIGHT orchestration budget, it stops and reports:
LIGHT_BUDGET_EXHAUSTED
RECOMMENDED_MODE: DEEP
The user can then explicitly choose whether the additional research cost is justified.
This is the main design lesson behind version 0.2.0.
LIGHT should limit exploration, not falsification.
A cheaper mode should not become an uncritical mode.
LIGHT reduces:
- number of agents;
- number of research rounds;
- breadth of exploration;
- duplicated work;
- unnecessary repository scanning.
It preserves the ability to challenge the leading conclusion and actively look for evidence that would falsify it.
DEEP is intended for ambiguous, cross-component, or structurally difficult problems.
It can use:
- multiple agents;
- multiple approach families;
- multiple rounds;
- explicit research registry updates;
- model or dependency reconstruction;
- cross-pollination between research paths;
- independent adversarial review;
- dynamic reprioritization.
DEEP may be automatically selected only when there is a strong and concrete reason that LIGHT would be insufficient.
DEEP never automatically promotes itself to MAX.
MAX is intended for unusually difficult, high-impact, high-uncertainty, or explicitly exhaustive investigations.
It emphasizes:
- broad research portfolios;
- neglected and secondary surfaces;
- repeated synthesis;
- aggressive falsification;
- dynamic agent redirection;
- multiple independent reviews;
- preservation of competing hypotheses;
- strong stop conditions;
- willingness to change the current ranking.
MAX must not become merely "DEEP with more tokens".
MAX is explicit-only:
$multi-agent max <task>
It is never selected automatically.
The skill separates four phases:
RESEARCH → PLAN → EXECUTION → VALIDATION
Inspect, measure, compare, test hypotheses, and collect evidence.
Convert validated findings into a concrete implementation or remediation plan.
Only when requested, perform the approved changes.
Verify the result against the original success criteria.
Completion of implementation is not itself proof of success.
The registry prevents duplicated effort and invisible assumption drift.
A research entry tracks externally useful state such as:
- approach family;
- candidate hypothesis;
- evidence for;
- evidence against;
- status;
- falsification condition;
- next useful action;
- confidence.
The registry must contain conclusions and evidence, not private chain-of-thought.
See references/research-registry.md.
The skill has been evaluated on a complex private Python codebase using progressive research:
LIGHT → DEEP → MAX
Observed behavior included:
- LIGHT identifying an initial evidence-backed shortlist;
- DEEP reconstructing a broader system model and comparing alternatives;
- MAX treating previous conclusions as hypotheses to falsify;
- MAX opening previously underexplored research families;
- ranking changes when new evidence justified them.
The important result was not increased answer length. It was a change in research methodology.
See docs/benchmark.md.
A later real-world test provided an additional lesson.
A private Python system had undergone three remediation phases. Existing targeted and regression suites were green.
LIGHT was then used as an independent read-only reviewer.
Instead of accepting the remediation reports, it treated each claimed fix as a hypothesis to falsify.
The checkpoint identified seven concrete regression classes that had not been covered by the previous suites:
- authorization scope mismatch;
- validation/sanitization ordering;
- alternative authority path;
- revocation race / TOCTOU;
- incomplete sensitive-field coverage;
- sanitizer fail-open;
- mutable audit/trace state.
The lesson is simple:
green tests != independent falsification
This does not mean ordinary regression testing is ineffective. It means a reviewer using a different failure model can discover assumptions that implementation-oriented tests did not encode.
The checkpoint also revealed that the original LIGHT configuration was too expansive for its intended role. Concurrent subagents and repeated research expansion can amplify orchestration cost even when elapsed wall-clock time appears modest.
That observation motivated the bounded LIGHT semantics introduced in version 0.2.0.
The selection policy is intentionally conservative.
$multi-agent <task>
means LIGHT.
DEEP can be selected automatically only when the task presents a strong concrete need for broader multi-agent investigation.
MAX is never selected automatically.
Escalation between modes requires a new explicit invocation by the user.
Clone the repository and run:
./scripts/install.sh
By default the skill is installed into:
${CODEX_HOME:-$HOME/.codex}/skills/multi-agent
You may also copy the runtime skill files manually:
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills/multi-agent"
cp SKILL.md "${CODEX_HOME:-$HOME/.codex}/skills/multi-agent/"
cp -R agents references "${CODEX_HOME:-$HOME/.codex}/skills/multi-agent/"
Start a new Codex session after installation.
Run:
python3 scripts/validate.py
The validator checks the repository structure and core skill invariants.
Repository validation is a sanity check. It does not guarantee future behavioral compliance by the underlying model or platform.
docs/methodology.md— orchestration model.docs/benchmark.md— anonymized behavioral evaluation.docs/design-rationale.md— design decisions.docs/limitations.md— limitations and non-guarantees.references/modes.md— detailed mode semantics.references/research-registry.md— registry format and rules.
The repository follows the Codex skill layout:
SKILL.md- optional
agents/metadata - bundled
references/ - documentation and validation scripts.
The numerical agent and round limits defined by this skill are orchestration instructions, not platform-enforced resource quotas.
MIT. See LICENSE.