agents-format(7)¶

NAME¶

agents-format - specifications and concepts for Agent Smith

DESCRIPTION¶

Agent Smith implements a dynamic version of the AGENTS.md pattern.

The AGENTS.md Standard¶

Refer to https://agents.md/. An AGENTS.md file defines the context, behavior, and capabilities of an AI agent. It acts as a “system prompt” or “instruction set” for LLMs interacting with a repository.

Dynamic Context¶

Standard AGENTS.md is static. Agent Smith makes it dynamic by introducing Personas and a Canonical Target.

Personas¶

A Persona is a specialized AGENTS.md file, named using the convention AGENTS.<name>.md.

AGENTS.coder.md
AGENTS.writer.md
AGENTS.architect.md

Canonical Target¶

The Canonical Target is a specific symbolic link (defaults to $XDG_CONFIG_HOME/agents/AGENTS.md).

This link is the Source of Truth.

If it points to AGENTS.coder.md, the system is in “Coder” mode.
If it points to AGENTS.writer.md, the system is in “Writer” mode.

Drift and Reconciliation¶

Because the Canonical Target is a standard filesystem symlink, you can modify it using standard tools (ln -sf).

Source of Truth Pattern:

agents(1) inspects the Canonical Target to determine the Active Persona.
If the Canonical Target has changed manually (Drift), agents(1) accepts this as the new valid state.
agents(1) (via reconcile) forces all other configured targets (copies, other links) to match the Active Persona.