A mini code agent with Docker Agent - Part 7: `commands` (slash) + `instruction_file`

A useful agent is a reusable and drivable agent. This step adds no new raw capability to it: it improves its ergonomics, with two settings that make our agent easier to use and to configure.

instruction_file: we move the system prompt out of the YAML configuration and into a Markdown file.
commands — slash shortcuts (/audit, /explain) instead of retyping long instructions.

`instruction_file`: the prompt in a file

We replace the instruction: | entry with a path to an external Markdown file. The content of that new file becomes the agent's instruction at startup:

yaml

agents:
  root:
    instruction_file: AGENTS.md

Why it beats an inline prompt:

Readability: the YAML stays short and structural; the agent's "personality" lives in a real structured Markdown document, with headings, lists...

Reuse: instruction_file accepts a list of files, concatenated in order:

yaml

instruction_file:
  - instructions/common-preamble.md
  - instructions/reviewer.md

Versioned separately: the prompt is read and diffed like code, independently of the config.

`commands`: slash shortcuts

A command is a shortcut the user types (/audit) instead of writing out the whole instruction. Each agent declares its own under commands::

yaml

commands:
  # Simple form: the string becomes the instruction sent to the agent.
  audit: "Do a general review of the project and list your 3 most important remarks."

  # With an argument: ${args[0]} = the first word typed after the command.
  explain:
    description: "Explain a file: /explain <path>"
    instruction: "Read the file ${args[0]} and explain its role in a few sentences."

Interpolating the parameters

Commands use ${...}:

Pattern	Gives you
`${args[0]}`, `${args[1]}`	the positional arguments typed after the command
`${args}` / `${args.join(" ")}`	the full list of arguments
`${env.VAR}`	an environment variable (with a default: `${env.VAR \|\| 'x'}`)
`${tool({key: value})}`	calls one of the agent's tools and inserts its output

If the instruction uses no ${args...} at all, the text typed after the slash is simply appended to the resolved instruction.

Where it works

Commands work in the TUI (/audit), on the CLI (docker agent run agent.yaml /audit) and through the HTTP API (yes, docker-agent also exposes a REST API: https://docker.github.io/docker-agent/features/api-server/).

You can also share one set of commands between several agents through a top-level commands: section — handy as soon as you have a team of agents (we'll talk about agent teams in a future blog post).

The complete `AGENTS.md` and `agent.yaml` for this lesson

agent.yaml:

yaml

agents:
  root:
    model: mellum
    description: A Rust code reviewer, driven by slash commands.
    instruction_file: AGENTS.md

    toolsets:
      - type: shell
      - type: filesystem
        allow_list:
          - "."

    commands:
      # Simple form: the string becomes the instruction sent to the agent.
      review: "Read the Rust file you are given and list what breaks the team's conventions, one bullet per problem, each with the offending line."
      # Object form: a description (shown in completion) + the instruction.
      docs:
        description: "Find the public items with no rustdoc comment"
        instruction: "List the .rs files in the current directory, then name every `pub` item that has no `///` comment above it."
      # Using an argument: ${args[0]} = the first word typed after the command.
      explain:
        description: "Explain a file: /explain <path>"
        instruction: "Read the file ${args[0]} and explain in a few sentences what it is for."

models:
  mellum:
    provider: dmr
    model: huggingface.co/jetbrains/mellum2-12b-a2.5b-instruct-gguf-q4_k_m:Q4_K_M
    base_url: http://localhost:12434/engines/v1
    # base_url: http://host.docker.internal:12434/engines/v1  # if you run the agent in a container

AGENTS.md:

markdown

# Agent: Rust code reviewer

You are the team's Rust code reviewer, working in the current directory.

## Non-negotiable

Never state anything you have not read. Open the file before commenting on it, quote the line you are
commenting on, and when you cannot check something, say so instead of guessing.

## Method

1. Explore with `shell` (`ls`, `find`, `git status`) to get your bearings before concluding anything.
2. Read the files with the `filesystem` tools rather than assuming their contents.
3. Be concrete: one remark = the file, the line, and an applicable fix.

## What you look at first

- `unwrap()` / `expect()` where the function could return a `Result` instead.
- Public items with no `///` documentation.
- Readability: meaningful names, short functions, early returns.

## Tone

Direct but courteous. Explain the *why* of a remark, not just the *what*.

📝 You'll find all the configuration files over here: 07-commands-instructions

Running Docker Agent

bash

cd 07-commands-instructions

# TUI
docker agent run localhost.agent.yaml

# Or TUI with sbx (sandbox):
sbx run docker-agent --kit . -- run agent.yaml

Prompts to try

Try these slash commands in the TUI:

/review demo.rs

/explain demo.rs

Key takeaways

instruction_file moves the system prompt out of the YAML: more readable, reusable, versioned separately.
commands gives you slash shortcuts, in simple form (a string) or object form (description + instruction).
Interpolating ${args[0]}, ${env.VAR}, ${tool({...})} makes the commands parameterisable.
These settings do not change what the agent can do, they make using it smoother.

In the next blog post we'll see how to bring together everything we have seen so far to build a complete agent.

A mini code agent with Docker Agent - Part 7: `commands` (slash) + `instruction_file`

0 Comments