Agent.md and System Prompts

Agent.md and System Prompts

Posted on by Toma Velev

agent.md (or similar files like system.md, instructions.md, policy.md) are becoming the externalized, version-controlled equivalent of what used to live entirely in a hidden system /admin prompt.

What’s changed conceptually

Historically:

  • System / admin prompts were:
    • Hidden
    • Hard-coded
    • Difficult to version, diff, or audit
  • They lived “inside” the model invocation.

Anyone that have programmed agains a LLM – either locally or on API – have probably touched it. If you just used ChatGPT – you may have never heard it.

Now:

  • agent.md acts as:
    • A persistent behavioral contract
    • A source-controlled system prompt
    • A portable identity for an agent

Think of it as:

System prompt → configuration artifact

Why agent.md emerged

Several pressures converged:

  1. Reproducibility
    • You can’t diff or review a hidden system prompt.
    • agent.md enables deterministic agent behavior across runs.
  2. Governance & compliance
    • Enterprises need auditable instructions.
    • Regulators don’t accept “it’s in the prompt somewhere.”
  3. Agent orchestration
    • Multi-agent systems need clearly defined roles.
    • Files > magic strings.
  4. Tooling & CI/CD
    • Prompt changes can now:
      • Go through PRs
      • Be tested
      • Be rolled back

What agent.md typically contains

It usually maps almost 1:1 to a system message, but structured:

# Agent Identity
You are a retrieval-augmented research agent.

# Objectives
- Produce verifiable answers
- Cite sources
- Avoid speculation

# Constraints
- Do not fabricate citations
- Ask clarifying questions when ambiguous

# Style
- Concise
- Neutral tone

This is functionally:

  • System prompt
  • Policy layer
  • Role definition

…just no longer implicit.

Important nuance

agent.md is not magic.

It only works if:

  • The runtime actually injects it as a system message (or equivalent)
  • The framework treats it as higher-priority than user messages

So the real shift is not the file itself, but:

System prompts are moving from “hidden strings” → “first-class artifacts.”

Mental model

Old world New world
Hidden system prompt agent.md
Prompt engineering Agent configuration
Chat session Executable agent
Role = text Role = contract

Bottom line

agent.md is effectively the new system/admin prompt, but:

  • Externalized
  • Versioned
  • Auditable
  • Composable