cagent name (~/.config/cagent, ~/.cagent).Docker Agent (the CLI is docker agent, the open-source project is cagent)\nruns AI agents declared in a YAML file instead of application code. This\nskill owns the agent.yaml artifact: the agents section (each entry's\nmodel, instruction, and its own toolsets/sub_agents), the top-level\nmodels/providers sections referenced from agents, and a top-level\ncommands group agents can opt into with use_commands. It does not cover\ninvoking the CLI or serving/sharing the config — see Related\nskills.
Activate this skill when:
\nagent.yaml/agent.yml/agent.hcl file.Do not use this skill when:
\ndocker agent run flags, --safety, --sandbox, aliases, worktrees) — use docker-agent-run.serve mcp/api/a2a/acp/chat), distributing it (share push/pull), or evaluating it (evaluation sessions, --baseline regression gates) — use docker-agent-deploy.docker-build-strategies or docker-compose-patterns.agents:. The agent\nnamed root, or the first agent defined, is the entry point that receives\nuser messages.\nagents:\n root:\n model: anthropic/claude-sonnet-4-5\n description: A coding assistant\n instruction: |\n You are an expert developer. Help users write clean,\n efficient code. Explain your reasoning step by step.\n toolsets:\n - type: filesystem\n - type: shell\n - type: think\nmodel, description, instruction (or\ninstruction_file). description is not decoration — other agents read it\nto decide whether to delegate to this one, so keep it accurate.instruction_file (a relative path, no ..) instead of an inline\ninstruction for long prompts; this keeps diffs focused on behavior, not\nYAML escaping. instruction and instruction_file are mutually exclusive.\ninstruction_file is not supported for agents loaded from an OCI reference\nor URL — inline instruction there.provider/model shorthand, or a named\nentry under top-level models: referencing a provider. Use the named\nform whenever you need temperature, max_tokens, thinking_budget, or\nreuse across agents.\nmodels:\n claude:\n provider: anthropic\n model: claude-sonnet-4-5\n max_tokens: 64000\n\nagents:\n root:\n model: claude\nopenai, anthropic, google, amazon-bedrock,\ndmr (Docker Model Runner, local, no API key), ollama (local). Dozens of\nadditional built-in aliases exist (mistral, groq, xai, together,\nazure, github-copilot, openrouter, ...) — each needs its own\n<PROVIDER>_API_KEY-style env var; run docker agent models --all to see\nwhat's resolvable, and docker agent setup to register credentials\ninteractively instead of hand-editing env vars.agent.yaml. Provider credentials come from\nenvironment variables (token_key for custom providers) or from\n~/.config/cagent/.env written by docker agent setup.dmr/<model> for agents that must run offline or must not send data\nto a third party; it costs nothing and needs no credential. Use a paid\ncloud provider only when the task needs it.fallback so a provider outage or rate\nlimit does not stop the run:\nagents:\n root:\n model: anthropic/claude-sonnet-4-5\n fallback:\n models: [openai/gpt-5, google/gemini-3.5-flash]\n retries: 2 # per model, for 5xx errors\n cooldown: 1m # stick with fallback after a 429\nproviders: entry with base_url and token_key\nrather than putting the URL inline on every model:\nproviders:\n my_gateway:\n base_url: https://api.example.com/v1\n token_key: MY_API_KEY\nmodels:\n my_model:\n provider: my_gateway\n model: gpt-4o\nfilesystem, shell,\nthink, todo, tasks, memory, fetch, background-jobs, script,\nlsp, api. Add one per list entry:\ntoolsets:\n - type: filesystem\n - type: shell\ntype: todo\n(or shell) — a common symptom of an agent missing the tool it needs to\nact, not a model problem.toolsets:\n - type: mcp\n ref: docker:duckduckgo\nreferences/toolsets-and-providers.md.defer: true on a toolset (MCP or otherwise) to load its tools\non-demand instead of at startup, when the agent has many toolsets and\nstartup latency matters.readonly: true on an agent to restrict every toolset it uses to\nread-only tools — use this for reviewer/analysis agents that must not\nmutate anything.sub_agents: [name, ...]; listing sub-agents\nautomatically enables the transfer_task tool on the parent.\n# Fragment: coder and reviewer are defined separately in the full asset.\nagents:\n root:\n sub_agents: [coder, reviewer]\nassets/team-agent.yaml for the complete runnable team, including\nthe reviewer's readonly: true restriction. Keep that restriction when\nadapting the template; a filesystem toolset alone also exposes writes.sub_agents also accepts external OCI references (myorg/agent:tag).\nPin external references to a digest (name@sha256:...) in production\nconfigs to skip the per-run registry lookup that a tag incurs.transfer_task (via sub_agents) for delegation with a clean,\nisolated result; use a commands: entry with an agent: field only when\nyou want the user to become that agent for the rest of the session.redact_secrets: true on any agent that runs shell/fetch tools against\nuntrusted input. It scrubs recognized secret patterns from tool arguments,\noutgoing messages, and tool output. This is defense in depth, not a\nguarantee: arbitrary passwords, tokens, or customer data may go undetected.max_iterations on any agent that loops autonomously (default is\nunlimited) to bound cost and prevent runaway loops; max_consecutive_tool_calls\n(default 5) already guards against identical-call loops.instruction,\ninstruction_file, and command prompts, whether literal or interpolated.\n${env.VAR} expands values into prompt text sent to the model; storing a\nvalue in an env file does not prevent this disclosure. Use interpolation\nonly for non-sensitive context.docker agent setup or the provider's\nsupported environment variables. For custom providers, token_key: MY_API_KEY\nnames the environment variable, not its value; do not interpolate it.\nConfigure tool/MCP credentials through that integration's authentication\nmechanism, not through prompts or model-supplied tool arguments. Prompts\nshould describe the authenticated capability without containing its secret.\nDo not ask the agent to read or print credential files or environment values\nto check authentication.docker agent run, safety modes, sandbox, aliases), use docker-agent-run.docker-agent-deploy.references/toolsets-and-providers.md — full built-in toolset list, MCP connection modes, and the provider/env-var table.references/sources.md — provenance of every rule in this skill.assets/team-agent.yaml — a runnable multi-agent team template (coordinator + coder + reviewer).checks/verification.md to confirm its\nresolved config, exposed tools, and provider connectivity, then smoke-test it.