agentleFS
TheGoat395TheGoat395/Codex-Skills/skills/agent-orchestration-architecture/SKILL.md

agent-orchestration-architecture

Skill136 starsChanged 5 months agoMITView on GitHub

Resolve agent ownership and handoff design.

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 5 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Do not use an agent swarm as a substitute for an owned workflow.

    line 18
  2. Distinctive:

    Use a manager when one agent must enforce shared policy, combine specialist work, or own the user-facing answer.

    line 35
  3. Distinctive:

    Use a handoff when the specialist needs a focused interaction and clear transfer of responsibility.

    line 36
  4. Distinctive:

    Keep the parent thread as the canonical decision owner.

    line 41
  5. Distinctive:

    Use inherited authorization for routine reversible in-scope writes, drafts and configuration.

    line 42

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Agent Orchestration Architecture

Design in escalating complexity

Choose the lightest design that satisfies the outcome:

  1. Deterministic program or promptless automation.
  2. One agent with bounded tools and structured output.
  3. One manager agent that calls specialists as bounded tools.
  4. Handoffs only when a specialist should own the rest of the interaction.
  5. Durable workflow runtime only when work survives interruptions, waits, or external callbacks.

Do not use an agent swarm as a substitute for an owned workflow.

Define the operating contract

Before implementation, record:

  • outcome, success evidence, and named final-output owner;
  • inputs, output schema, permitted tools, and forbidden actions;
  • model and reasoning choice by decision difficulty, not task size;
  • state owner, memory lifetime, tenant boundary, and source of truth;
  • approval checkpoints, budgets, timeouts, stop conditions, and escalation;
  • retry, idempotency, compensation, and human-handoff behavior.

Parallelize only independent work whose outputs can be reconciled without conflicting writes.

Make control explicit

  • Use a manager when one agent must enforce shared policy, combine specialist work, or own the user-facing answer.
  • Use a handoff when the specialist needs a focused interaction and clear transfer of responsibility.
  • Pass structured task packets, not vague conversation history. Minimize context to the specialist's need.
  • Delegate only a concrete, independent workstream with a defined output. Parallelism can reduce latency, but every subagent performs separate model and tool work and therefore increases usage.
  • Designing a delegation architecture does not authorize spawning agents. Follow current global and native tool constraints: preserve the selected parent model/effort and apply the current global child-model and reasoning policy. Do not freeze a session-specific model or effort into this specialist. Use only supported context controls and sufficient task context; do not override native inheritance constraints for a preferred packet format.
  • Give each specialist the exact sources, constraints, output schema, stopping condition, and useful result-size limit. Ask for distilled findings instead of raw logs or copied source material.
  • Keep the parent thread as the canonical decision owner. Do not spawn several agents to reread the same corpus, and do not use subagents merely to avoid doing a bounded task locally.
  • Use inherited authorization for routine reversible in-scope writes, drafts and configuration. Require explicit authorization for actual sends, spending, binding commitments, publication and materially irreversible actions at their real boundaries; do not reopen an already clear authorization.
  • Design every loop with a maximum attempt count and a useful terminal state.

Required outputs

For a material architecture request, produce the smallest useful combination of an execution diagram, role/tool matrix, state/approval map, operating limits, and evaluation plan. Do not create every artifact for a simple routing decision. Route persistent-context design to $agent-memory-provenance; route quality and release testing to $agent-evaluation-operations; route external events to $integration-contract-reliability.

Optional specialists

For external events, integration-contract-reliability is optional. Without it, define typed inputs/outputs, authentication, idempotency, retries, duplicate handling, uncertain-effect reconciliation and the actual success boundary in the project contract.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.