# Docker Skills teaches agents to build and debug containerised apps

> Docker Skills is a set of portable SKILL.md directories, authored by Docker, that give coding agents specific guidance on Dockerfiles, Compose files, sandboxes and Docker Agent. They install through a skills CLI or as plugins, and the catalogue is generated from a YAML file rather than maintained by hand.

**docker/skills** — A collection of Docker skills for AI coding agents to help them build, test, debug, and optimize containerized apps with consistent, reusable workflows.

- Repository: https://github.com/docker/skills
- Website: https://docs.docker.com/ai/skills/
- Stars: 594 · Forks: 34
- Language: Python
- License: Apache-2.0
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/docker-skills

## Skills as portable directories, not a plugin per product

Docker Skills is a collection of Docker-authored knowledge skills that improve AI coding agent output for Docker-related tasks. The mechanism is deliberately portable. Skills are authored once as portable `SKILL.md` directories and discovered automatically by any compliant agent through standard skill paths, and the repository carries a badge linking to the Agent Skills specification. The repository layout shows the same idea applied across the ecosystem of agents, with a `.claude-plugin/` directory, a `.codex-plugin/`, a `.cursor-plugin/`, a `.gemini/` directory and a `gemini-extension.json` alongside a `.claude/` directory and an `.agents/` one. The topics list names the agents explicitly, covering Claude Code, Codex, Cursor, Copilot, the Gemini CLI, antigravity and skills generally. The point of the design is that the same directory works in more than one agent, so a team does not maintain a Claude Code copy and a Codex copy of the same knowledge.

## The catalogue is generated, so edit catalog.yaml not the table

The README's skills table is generated from `catalog.yaml` by `task catalog`, and the instruction is explicit: edit the catalog, not the table. The repository has a `Taskfile.yml` for that task and a `catalog.yaml` at the top level. This is a small but meaningful choice. A hand-maintained table in a README drifts, because when a skill is added, renamed or rescoped, somebody has to remember to edit two places. Generating the table from a structured file means the inventory in the README is always consistent with what the skills CLI reads, and the same `skills.sh.json` index is what the installation path consumes. The `resources/` and `scripts/` directories sit alongside, and the repository also has an `evals/` directory and a `tests/` directory, which suggests the skills are checked in CI rather than only reviewed by eye. The consequence for a user is that the README is a view, not the source, so anyone extending the set should start from `catalog.yaml`.

## What is actually in the catalogue

The catalogue is grouped by Docker product, and each skill carries a one-line description of what it covers. For Dockerfile and Build there are two, `docker-project-foundations` for initialising and structuring a Dockerised project, and `docker-build-strategies` for efficient, secure and optimised image builds. Docker Compose has one, `docker-compose-patterns`, for maintainable Compose configurations. Docker Sandboxes has four, covering the `sbx` CLI lifecycle for creating, reattaching to and tearing down local sandboxes, network egress policy and credential provisioning, plus two marked experimental, one for declarative `sbxenv.yaml` environments and one for reusable sandbox and mixin kits with a spec.yaml schema v2. Docker Agent has three, for authoring `agent.yaml` configs, for running agents locally with safety and approval modes, and for exposing agents as servers distributed through OCI registries. Two cross-product skills close the set: `docker-docs`, marked experimental, which answers questions from current official Docker documentation using a docs MCP search tool, and `docker-destructive-guardrails`, a policy for confirming irreversible or destructive Docker operations before running them.

## No entry point skill, and a stated load order

One design decision will change how you write instructions for your agent. Each skill triggers directly from its own description, and there is no entry-point skill to load first. That means you do not have to teach an agent to load a Docker manual before it can use a Dockerfile skill, which removes a whole category of prompt engineering. The second decision is the load order, which the README specifies for when a task spans several skills. `docker-project-foundations` comes before `docker-build-strategies` or `docker-compose-patterns` when the project has no Docker setup yet. `docker-build-strategies` comes before `docker-compose-patterns` when both a Dockerfile and a compose.yaml change. For sandboxes, `docker-sandboxes-lifecycle` before `docker-sandboxes-network-credentials`, and both before `docker-sandboxes-env` or `docker-sandboxes-kits`. For Docker Agent, `docker-agent-config` before `docker-agent-run` before `docker-agent-deploy`. The skills marked experimental cover features whose schemas may still change, which is a useful signal for how much to trust them.

## Installing through the skills CLI, and what it touches

The `skills` CLI installs into every major coding agent, and the README names them, including Claude Code, Codex, Cursor, GitHub Copilot, the Gemini CLI, OpenCode, Windsurf, Cline and Kiro. The command reads the `skills.sh.json` index in the repository, so skills are listed grouped by product.

```bash
npx skills add docker/skills
```

It prompts for which skills and which agents to install to, and there are non-interactive variants for scripts and CI.

```bash
# Browse the catalog without installing anything
npx skills add docker/skills --list

# Install one skill, no prompts (project scope; add -g for user scope)
npx skills add docker/skills --skill docker-compose-patterns --yes

# Install every skill into one agent
npx skills add docker/skills --skill '*' --agent codex --yes
```

There is also a way to keep installed skills current, and a way to pin to a reviewed release, which is the part that matters for a team that does not want instructions changing under it.

```bash
# Keep installed skills current
npx skills update

# Pin a skill to a reviewed release (replace vX.Y.Z with a release tag)
npx skills add https://github.com/docker/skills/tree/vX.Y.Z \
  --skill docker-compose-patterns --yes
```

Note what the CLI does not do. The skills CLI, Docker Sandboxes and manual copies install skills only, whereas plugin and extension installs also register the remote Docker docs MCP server at `https://ai-backend-service.docker.com/mcp`, which is what `docker-docs` uses. If your policy forbids that outbound call, install through the CLI path.

## Plugin installs come with their own update path

There is a second installation route, and it behaves differently. Plugin installs are managed by each agent's marketplace, so updates arrive through the agent rather than through `npx skills update`. That is a real operational difference, not a detail. If you install through a plugin, your skills are versioned by the agent's plugin mechanism and you upgrade them by upgrading the plugin. If you install through the skills CLI, you upgrade them with the skills CLI, and you can pin a skill to a release tag when you want a reviewed version. For Claude Code the install is two commands run in the Claude Code prompt.

```text
/plugin marketplace add docker/skills
/plugin install docker-skills@docker
```

For OpenAI Codex the documented command is `codex plug`. The manifest of the repository shows how many surfaces are supported, with the plugin directories and the MCP configuration, `plugin-mcp.json`, at the top level alongside `skills.sh.json` and `catalog.yaml`. The licence is Apache 2.0, so the content can be vendored, adapted and shipped inside your own tooling without copyleft obligations, and the repository carries a `SECURITY.md` and a `CODE_OF_CONDUCT.md` alongside a `CHANGELOG.md` and a `CONTRIBUTING.md`.

## Conclusion

Adopt Docker Skills if you run coding agents against containerised code and you want their Dockerfile and Compose output to follow current Docker practice rather than a model's memory of it. Skip it if your agents never touch containers, and skip it if you cannot accept that plugin installs also register a Docker docs MCP server for remote documentation. Before you commit, read catalog.yaml, since the table in the README is generated from it, and check which skills are still marked experimental because their schemas may change under you.

## FAQ

### How do I install the Docker Skills for coding agents?

Run `npx skills add docker/skills`, which prompts for which skills and which agents to install to. Non-interactive variants include `npx skills add docker/skills --skill docker-compose-patterns --yes` for a single skill and `npx skills add docker/skills --all` for every skill in every detected agent.

### Do Docker Skills need an entry point skill to be loaded first?

No. Each skill triggers directly from its own description, and there is no entry-point skill to load first. The README does specify a load order for tasks that span several skills, such as `docker-agent-config` before `docker-agent-run` before `docker-agent-deploy`.

### How do I keep installed Docker Skills up to date?

Run `npx skills update` for CLI installs. Plugin installs are managed by each agent's marketplace, so updates arrive through the agent rather than through the skills CLI. You can also pin a skill to a reviewed release tag when installing.

### What does the Docker Skills install do to my agent configuration?

The skills CLI, Docker Sandboxes and manual copies install skills only. Plugin and extension installs also register the remote Docker docs MCP server at `https://ai-backend-service.docker.com/mcp`, which is what the `docker-docs` skill uses.

## Sources

- [docker/skills on GitHub](https://github.com/docker/skills)
- [License: Apache-2.0](https://github.com/docker/skills/blob/main/LICENSE)
- [Project website](https://docs.docker.com/ai/skills/)
- [README](https://github.com/docker/skills/blob/main/README.md)
- [Releases](https://github.com/docker/skills/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/docker-skills