# Your agents

> Agents are markdown files on your machine. devpit reads them, never copies them.

Agents are markdown files on your machine — the ones you wrote, and the ones
your tooling already installed. None ship with devpit: the ones you see are the
ones that are there. Nothing to recompile, nothing to register.

These are subagents, the *who* of an [agent step](/docs/agent-steps). The
account a step spends through is a [profile](/docs/profiles), and the two are
unrelated.

## Where they are read from

Three places, in this order:

1. `~/.devpit/agents` — your own, read first so one of yours shadows a
   plugin's of the same name.
2. The agent CLI's own agents directory, `~/.claude/agents` unless you moved
   its configuration.
3. Every `agents/` directory inside the CLI's installed plugins.

Every directory, not the best one. Picking a single best needs a rule for which
plugin wins, and any such rule is wrong for someone; reading all of them,
first-wins on a name clash, gets the union with no rule at all.

devpit **references them, never copies them**: whatever owns a catalogue keeps
owning it. Nothing is written into those directories, and a file you edit is
read again the next time a step runs.

## What makes a file an agent

A `.md` file whose frontmatter opens with `---` and carries a `name`. That name
is what a step asks for. `description`, `model` and `tools` are read when they
are there; keys devpit has no opinion about are ignored, because the format is
shared rather than devpit's. The body is the agent's prompt.

Two failures, told apart on purpose:

- **No frontmatter at all** — ignored in silence. These directories also hold
  `AGENTS.md` and READMEs, and a file that never claimed to be an agent is not
  a broken one.
- **Frontmatter that does not read** — listed as rejected, with the reason, and
  the rest of the catalogue still loads.

## In a step

The **Agent** field of an agent step suggests the names it found. A step naming
an agent that is not on this machine is refused when you save it — *"no agent
named `<name>` on this machine"* — rather than failing when a card lands on the
lane.

Only the agent a step names is handed to the turn. Passing the whole catalogue
would make every step's behaviour depend on files it never mentions.
