Your agents

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. The account a step spends through is a profile, 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.