🚀 Advanced & cross-environment

A fleet is a named set of subagents with distinct roles that the orchestrator can scale horizontally: one agent per task, N tasks in parallel.

Without the concept of a fleet, you’re limited to linear pipelines. With it, the workload grows without increasing the complexity of the main prompt.

Fleet = group + role + parallelism; the orchestrator manages, not executes; each member reports to the hub.

The orchestrator relaunches subagents until there are no more items to process. The loop ends when the queue is empty, not after a fixed number of attempts.

Research, code audit, and log analysis tasks never have a predictable size. The loop-until-dry ensures completeness without an arbitrary hard cap.

Stop condition = empty queue; safety guard = iteration limit; progress report between rounds.

A separate subagent receives the main agent’s result and actively tries to refute it — looking for errors, gaps, and contradictions — without access to the original reasoning.

LLMs tend to confirm what they generated. The adversarial verifier breaks this confirmation bias without requiring human review on every iteration.

Context isolation; explicit role of "devil's advocate"; binary output: approved / list of failures.

A critical agent compares the initial scope with the final deliverable and lists what was left incomplete or not addressed. It differs from the adversarial verifier: the focus here is coverage, not correctness.

Large projects silently lose entire sections of scope. The completeness critic acts as an automated checklist and closes the loop.

Scope as a contract; coverage × correctness distinction; output: a list of gaps to relaunch or report.

The three-stage pattern for large-scale research: a finder gathers evidence, a verifier checks each piece, and a synthesizer produces the final report with sources tracked.

Separates concerns—search, verification, and synthesis into dedicated agents—making each stage replaceable and the result auditable.

Decoupled stages; handoff via artifact (file or JSON); source traceability.

A minimal orchestrator template that delegates to N subagents, collects results, and decides whether to relaunch or stop — the skeleton you copy and adapt.

Building a harness from scratch every time is repetitive work. The skeleton exposes extension points without tying down the domain logic.

Entry point; agent list; collection loop; stopping condition; structured output.

A subagent is a pattern — isolated context, a defined role, and a report back — that exists in any runtime that supports agent calls, not just Claude Code.

Frees you from depending on a single vendor. The ability to design multiagent systems is valuable in any tool you use.

Standard vs. implementation; concept portability; mapping primitives across runtimes.

OpenAI’s Codex CLI uses `.md` files in `.codex/agents/` with the same philosophy: persona + tools + disallowed-tools. The structure is analogous to `.claude/agents/`.

Teams use multiple tools. Knowing how to map your Claude agent to Codex lets you reuse the logic without rewriting it from scratch.

`.codex/agents/` ↔ `.claude/agents/`; equivalent fields; syntax differences and limitations.

Polyskill is the standard for writing a single skill source that adapts to the detected runtime — Claude Code, Codex, or another — without forking the file.

Keeping two parallel files inevitably leads to drift. polyskill keeps a single source of truth and handles the differences in the adaptation layer.

One source, N outputs; conditional sections; adaptation layer vs. domain logic.

Side-by-side mapping of the main tools across runtimes: Claude Code’s Bash/Read/Write/Edit and their equivalents in Codex and other environments.

Explicit translation avoids surprises. Knowing that “Bash” becomes “shell” and “Edit” becomes “patch” speeds up portability and reduces adaptation bugs.

Common primitives (read, write, execute); tools without a direct equivalent; strategy for gaps.

A portable skill uses domain language in its body—never specific tool names—and delegates the “which tool to use” decision to the adaptation section.

Skills with hardcoded `Bash:` fail silently in runtimes that don't have Bash. Portability starts with the choice of words.

Tool abstraction; “Tool mapping” section; portability tests across runtimes.

Walkthrough of a `code-reviewer` agent that runs in Claude Code and Codex CLI without modification, showing where adaptation happens and what stays identical.

Seeing the concrete example reinforces the pattern. It's the difference between understanding the concept and knowing where to make changes when something breaks in portability.

Invariant sections vs. adaptation sections; annotated diff; cross-runtime test checklist.

Each agent role (reasoning, execution, verification, summarization) has different requirements for cost, speed, and depth. Using the same model for everything is wasteful or risky.

The cost difference between Opus and Haiku can be 50×. With a fleet of 20 agents, choosing the wrong model is expensive and slow for no reason.

Role = requirements; model = resource; optimize by role, not by project.

Opus = complex reasoning, planning, high-risk decisions. Sonnet = balanced execution, code, analysis. Haiku = triage, summarization, high-volume repetitive tasks.

The Model × Role table is the backbone of any well-sized fleet. Without it, you test in the dark and either pay too much or get lower-than-expected quality.

Deep reasoning × throughput; cost per token; response latency; context limits per model.

GPT-4 can fill execution roles where the team already has credits or existing integrations. Codex (GPT-4-turbo fine-tuned for code) has an advantage in code generation in specific contexts.

Heterogeneous fleets are the reality in companies. Knowing where each model has a comparative advantage avoids team conflicts and optimizes the vendor portfolio.

Comparative advantage; lock-in vs. flexibility; API abstraction layer to switch models without rewriting agents.

Orchestrator = Opus (plans). Execution workers = Sonnet (code, analysis). Triage and summarization = Haiku. Final verification = Opus or Sonnet, depending on risk.

The concrete example turns the principle into a decision. You leave with a model allocation template that you can adapt for any project.

Allocation template; upgrade criteria (when to use a more expensive model); downgrade criteria (when it's safe to use a cheaper one).

Signals that indicate switching providers by role: recurring unavailability, cost above the benchmark, tool limitations, unmet latency requirements.

The decision to switch is often emotional or political. Having objective criteria for each role makes the decision technical and defensible.

SLO by role; migration cost; abstraction layer; model A/B test.

Exercise: map the roles in your current—or planned—system and choose the most suitable model for each, with cost and risk justification.

The matrix is the fleet’s design document. It communicates intent, makes onboarding easier, and serves as a reference when optimizing.

Role, selected model, rationale, estimated cost, alternative fallback model.

An agent `.md` file from an unknown source may contain malicious instructions embedded in the text that the LLM executes as commands while processing the context.

The attack surface grew with public catalogs. The risk is real: an imported agent could exfiltrate data, modify files, or create backdoors.

Zero trust in external sources; audit before running; `.md` review checklist.

Prompt injection is the insertion of instructions for the LLM into data the agent will read—code comments, file contents, API results—causing it to deviate from its expected behavior.

An agent that reads code from a repository or a response from an API could potentially be instructed by that content. Ignoring this is the biggest vulnerability in multi-agent systems.

Data vs. instructions; context contamination; suspicious pattern detection; input sandboxing.

An agent with `disallowed-tools: [Bash, Edit, Write]` that can only read — never execute, never modify, never send data outside. The isolation is declared in the `.md` file itself.

Suspicious content (a third-party `.md` file, a configuration file) must be checked by an agent that cannot cause harm even if compromised.

`disallowed-tools`; principle of least privilege; separation between reading and acting; structured report with no side effects.

Explicitly define which tools each agent can use, periodically reviewing whether permissions still match its current role—and removing anything no longer needed.

Permissions accumulate silently. A documentation agent that gained Bash access "for convenience" is a risk that won’t show up in the logs until it’s too late.

Least privilege; periodic audits; explicit vs. default permissions; scope creep risk.

MCPs expose external tools to the agent. A compromised or malicious MCP can exfiltrate data, run remote commands, or escalate privileges without the agent noticing.

MCP is the most powerful integration point — and the most dangerous. The attack surface grows with every MCP added without a security review.

Zero trust in external MCPs; review MCP server code; minimize the scope of exposed tools; log calls.

An 8-point checklist for reviewing any `.md` before putting it into production: source, declared permissions, hidden instructions, network access, tool scope, exfiltration, bypass backdoors, and review by a second pair of eyes.

A repeatable process is the only way to audit consistently. The checklist becomes the approval gate before any external `.md` file enters the repo.

Approval gate; mandatory manual review; quarantine before production; minimum viable security process.

Public repositories like `awesome-claude-code-subagents` bring together hundreds of ready-to-use agents — security-auditor, test-runner, doc-writer, db-expert — maintained by the community.

Creating from scratch takes time and introduces errors that others have already solved. Learning the ecosystem is the first step toward speeding up your library.

Curated vs. uncurated catalogs; quality criteria; maintainer reputation; license.

Starting with a community-tested agent and adapting it is systematically faster and more reliable than creating one from scratch, even if the final result is almost identical.

NIH (not invented here) is costly in time and quality. The reuse principle shifts the starting point from “create” to “find + adapt.”

Smart starting point; adaptation vs. rewrite; comparative maintenance cost.

Four steps: download the `.md` from a trusted source, audit it with the security checklist (M4.4), adapt the name/persona/tools to your context, put it in `.claude/agents/`, and test it.

The structured flow avoids the dangerous shortcut of downloading and using without auditing. The audit step is not optional, even for trusted sources.

Quarantine; audit gate; minimal vs. complete adaptation; smoke test after import.

Walkthrough of adapting a generic `security-reviewer` to the context of a specific Python project: adjusting the persona, project context, tools, and inline examples.

Adaptation is where most people get it wrong — either they don't adapt anything (the agent is too generic) or they rewrite everything (losing the benefits of reuse). The example shows the right balance.

What to adapt (persona, context, examples) vs. what to keep (decision logic, output format, safety).

Imported agents may receive updates from the source repository. You need to decide whether to sync with the original, maintain a local fork, or freeze the version. Each choice has trade-offs.

The lifecycle management of an imported agent is ignored during adoption and becomes technical debt later. Deciding on a strategy early saves rework.

Fork vs. upstream sync; changelog tracking; minimum tested version; update policy.

When and how to publish your adapted agents back—anonymizing project context, adding a README, choosing a license, and submitting a PR to curated catalogs.

Catalog quality depends on contributions. Publishing forces you to generalize the agent well, which often improves the internal version too.

Sensitive data anonymization; minimal README; catalog quality criteria; compatible license.

A personal set of reusable agents organized in `.claude/agents/` — security-auditor, test-runner, doc-writer, db-expert, code-reviewer — that you maintain and evolve over time.

The library is an asset that grows with you. Each successfully completed project adds an agent to the collection; over time, you start new projects with specialists already at hand.

Personal collection; library versioning; README for each agent; categories (security, testing, docs, infra, data).

The 5 agents that cover 80% of needs in most software projects: security-reviewer (read-only), test-runner, doc-writer, code-reviewer, and db-migration-checker.

Having a defined starter pack eliminates decision paralysis. You start with a cohesive set and expand based on real needs, not anticipation.

80% coverage; smallest cohesive set; criterion for adding (demonstrated real need); don't anticipate.

`.md` templates with a standard structure (name, persona, description, tools, disallowed-tools, examples) that you can fill out in minutes for any new agent role.

A well-made template ensures you don’t forget critical fields (disallowed-tools, usage examples) and maintains consistency across all agents in the library.

Minimum template vs. complete template; required vs. optional fields; consistency as the goal.

A 10-point gate before putting any agent into real use: reviewed permissions, explicit disallowed-tools, tested examples, clear persona, no ambiguous instructions, security audit.

Agents that don’t go through a checklist before production accumulate unexpected behavior. The checklist is the equivalent of a code review for `.md`.

Production gate; peer review; smoke test; "ready to use" criterion.

The course capstone exercise: map the roles in your actual work, choose models for each one, create 3 agents from your personal library, and document the fleet you designed.

Learning is consolidated in the application. The final project closes the loop: from the mental model (T1) to the production fleet (T4).

Application to a real-world context; at least 3 agents; fleet documentation; verification criterion — “how do I know I got it right?”

Synthesis of the four tracks: T1 (mental model) → T2 (create the `.md`) → T3 (orchestrate and save) → T4 (scale, protect, and reuse). A panoramic view of what you learned.

The recap brings together the complete mental model and shows the progression from fundamentals to an advanced system—making it easier to review, teach, or adapt to new contexts.

T1→T4 progression; anchor concepts for each track; next steps; where to go deeper.