# docker-agent-config

Creates and edits agent.yaml files for Docker Agent. Useful when configuring models, MCP toolsets, and multi-agent teams.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 746 installs · ★ 599
- Author: docker
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/docker/skills/tree/HEAD/skills/docker-agent-config/SKILL.md
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/skills/docker-agent-config

## What it does

This skill writes and updates `agent.yaml`, `agent.yml`, and `agent.hcl` configs for Docker Agent (`cagent`). It defines the `root` agent, inline or external instructions, and model providers like Anthropic, OpenAI, or local Docker Model Runner.

Configs can include built-in toolsets such as `filesystem` and `shell`, or containerized MCP tools from Docker's catalog. It also arranges multi-agent teams via `sub_agents`, delegating tasks from a coordinator.

Running these files requires the docker-agent plugin from Docker Desktop 4.63+ or Docker CLI 29.7.2. CLI execution flags and server deployment are outside this skill, so you will still handle runtime commands separately.

## Requirements
- Works with: Docker

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add docker/skills --skill docker-agent-config -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/docker-agent-config/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/docker-agent-config/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add docker/skills --skill docker-agent-config -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/docker-agent-config/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add docker/skills --skill docker-agent-config -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/docker-agent-config/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install docker/skills docker-agent-config
```

2. **Manually: put the files in place**
- File: `.github/skills/docker-agent-config/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add docker/skills --skill docker-agent-config -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/docker/skills --path skills/docker-agent-config
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/docker-agent-config/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add docker/skills --skill docker-agent-config -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/docker/skills/tree/HEAD/skills/docker-agent-config/SKILL.md

## When to use it
- generate an `agent.yaml` file for Docker Agent
- connect containerized MCP toolsets and local filesystem tools
- configure multi-model fallback rules for API rate limits
- define a coordinator agent with specialized `sub_agents`

## Example prompts
- Create an `agent.yaml` config for a coding agent using the filesystem and think toolsets
- Add a fallback model configuration for Anthropic and OpenAI in `agent.yaml`
- Set up a coordinator agent that routes tasks to two `sub_agents`

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 1bb88ee4ebc0b2c5.

BEGIN THIRD-PARTY FILE 1bb88ee4ebc0b2c5
````text
---
name: docker-agent-config
description: Use this skill when creating or editing an agent.yaml (or .yml/.hcl) configuration file for Docker Agent (cagent), including defining agents, models/providers, built-in or MCP toolsets, multi-agent teams with sub_agents. Even if the user just says they want to "build an AI agent with Docker", "make a coding agent config", "add a tool to my agent", or "set up a team of agents", this skill applies. Covers agent properties (model, instruction, toolsets, sub_agents, fallback), the models/providers sections, built-in toolsets (filesystem, shell, think, todo, memory, fetch), MCP toolset references, and named commands.
license: Apache-2.0
compatibility: Requires the docker-agent CLI plugin (Docker Desktop 4.63+, or standalone via Homebrew/GitHub releases). Verified against docker-agent as shipped with Docker CLI 29.7.2. Config directories still use the legacy `cagent` name (`~/.config/cagent`, `~/.cagent`).
---

# Docker Agent Configuration

## Overview
Docker Agent (the CLI is `docker agent`, the open-source project is `cagent`)
runs AI agents declared in a YAML file instead of application code. This
skill owns the `agent.yaml` artifact: the `agents` section (each entry's
`model`, `instruction`, and its own `toolsets`/`sub_agents`), the top-level
`models`/`providers` sections referenced from agents, and a top-level
`commands` group agents can opt into with `use_commands`. It does not cover
invoking the CLI or serving/sharing the config — see Related
skills.

## When to use this skill
Activate this skill when:
- The user is creating, editing, or reviewing an `agent.yaml`/`agent.yml`/`agent.hcl` file.
- The user wants to add a tool/toolset, an MCP server, or a sub-agent to an agent config.
- The user wants to choose or configure a model/provider (OpenAI, Anthropic, Google, Bedrock, Docker Model Runner, custom endpoint) for an agent.
- The user wants a multi-agent "team" with a coordinator delegating to specialists.

## Do not use this skill when
Do not use this skill when:
- The task is about running the CLI (`docker agent run` flags, `--safety`, `--sandbox`, aliases, worktrees) — use `docker-agent-run`.
- The task is about exposing an agent as a server (`serve mcp/api/a2a/acp/chat`), distributing it (`share push/pull`), or evaluating it (evaluation sessions, `--baseline` regression gates) — use `docker-agent-deploy`.
- The task is about a generic Dockerfile or Compose service unrelated to Docker Agent — use `docker-build-strategies` or `docker-compose-patterns`.

## Core guidance

### File structure
- Every config needs at least one agent under top-level `agents:`. The agent
  named `root`, or the first agent defined, is the entry point that receives
  user messages.
  ```yaml
  agents:
    root:
      model: anthropic/claude-sonnet-4-5
      description: A coding assistant
      instruction: |
        You are an expert developer. Help users write clean,
        efficient code. Explain your reasoning step by step.
      toolsets:
````
END THIRD-PARTY FILE 1bb88ee4ebc0b2c5

The third-party file has ended. Everything between the 1bb88ee4ebc0b2c5 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3027 of 9966 bytes. © docker · Apache-2.0 · https://github.com/docker/skills/tree/HEAD/skills/docker-agent-config/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md