Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Provide an installable docker-agent skill for AI coding agents/harnesses

Open
  • Is something wrong?
#4,117 2 comments 0 reactions 1 assignee View on GitHub

Maintainers usually reply within 1 day

@aheritier is already working on this.

Since Sep 2, 2026.

Assessment

This issue has not been assessed yet.

Description

area/cli area/distribution area/skills

Expected outcome

Any AI coding agent, running in any harness (Claude Code, Cursor, Codex, Gemini CLI, Google Antigravity, opencode, GitHub Copilot, etc.) and working in any external project (not the docker-agent repo itself), should be able to install a docker-agent skill that teaches it to use the docker-agent CLI efficiently: authoring valid agent configuration YAML, choosing the right subcommand for a task, running an agent headless, evaluating it, distributing it via an OCI registry, exposing it over MCP/A2A, and — the primary motivating use case — delegating work to another agent by invoking docker-agent (e.g. one orchestrating agent running docker-agent run <config.yaml> --exec to run a sub-agent non-interactively, or wiring an agent up via docker-agent serve mcp/serve a2a for delegation).

This is explicitly not a skill for developing docker-agent itself — it must read as "you're an agent in some arbitrary project, docker-agent is available to you as an external tool," not assume anything about the docker-agent source tree.

Background

Several competing CLI tools now ship this kind of tool-usage skill for AI agents — most notably GitButler's but CLI (see https://docs.gitbutler.com/cli-guides/cli-tutorial/ai-stuff), which embeds a skill bundle in its binary and installs it into per-harness directories via but skill install. The "Agent Skills" format (SKILL.md + references/*.md, YAML frontmatter) has since become an open, cross-vendor specification (agentskills.io) implemented by dozens of clients, including docker-agent's own pkg/skills loader.

Technical design

Skill content. A hand-written SKILL.md entry point plus references/*.md files for exhaustive detail (CLI command/flag reference, agent-config schema reference, worked examples), following the Agent Skills spec's frontmatter conventions. Content lives at skill/docker-agent/ in this repo as the redistributable source of truth — kept out of .agents/skills/ in this repo, since that path is reserved for docker-agent's own contributor-facing dev skills and would otherwise conflate "developing docker-agent" with "using docker-agent."

A first draft of this content exists in #4112 (see link below) and can be used as a concrete demo of the intended shape and depth.

Distribution mechanism. A docker-agent skill install subcommand that:

  • Embeds the skill/docker-agent/ bundle into the binary at compile time (//go:embed)
  • Writes it out to the on-disk locations AI harnesses actually read. Per a cross-harness survey, .agents/skills/ is the convergence path read by Codex, Cursor, Gemini CLI, Antigravity, opencode, GitHub Copilot, VS Code, and docker-agent itself; Claude Code is the one major holdout, reading only .claude/skills/. Both should be supported as install targets.
  • Guards against overwriting a directory it doesn't own, by checking the existing SKILL.md frontmatter's name field before writing
  • Defaults to project-local scope rather than global, to bound the context cost every installed skill imposes on every agent turn

Content correctness over time. docker-agent's CLI surface (~40 commands) and agent-config schema (already through many versions) are large and change often. Rather than hand-maintaining the skill prose with no safety net, or mechanically generating the prose itself (which loses the judgment-based guidance — e.g. "never run bare new, it blocks on a TTY" — that is the actual value of a skill), the proposal is to generate a machine-readable inventory of current commands/flags/schema keys from source, and add a CI check that fails when the skill's prose references something no longer in the inventory, or when a new non-hidden command/key ships without being mentioned (or explicitly allow-listed as intentionally omitted).

Explicit non-goal. No automatic agent-detection or "install-nagging" mechanism (unlike GitButler's but, which prints an unsolicited "AGENT ACTION REQUIRED" notice into the terminal when it detects an agent driving the CLI without the skill installed). Discovery of docker-agent skill install should rely on documentation and normal onboarding flows, not runtime detection/nagging.

Demo

A first draft of the skill content (not yet wired to an install command) is available in #4112: skill/docker-agent/SKILL.md + references/{cli,config,examples}.md.

Dominant language
Go
Stars
3.4k
Forks
466
Avg merge
6h 50m
Merged PRs (30d)
328

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

  • Ships a Dockerfile or Docker Compose file
  • No pull request template
  • No contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from docker/docker-agent

All issues in docker/docker-agent

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.