AGENT.md: Why Your AI Agent's Config Should Be a Markdown File

The code-per-agent trap

In most agent frameworks, adding an agent means writing a new Python or JavaScript file. You define tools as functions, wire up prompts as strings, configure models in code. The result: your agent system is a codebase that only developers can modify.

We had 8 agents in production. Every time someone wanted to change an agent's behavior — adjust a cycle time, add a tool, tweak a prompt rule — it required a code change, a syntax check, and a service restart. For a system that's supposed to be autonomous, it was remarkably dependent on human developers.

The AGENT.md pattern

In Klawty, adding an agent means creating one Markdown file. No JavaScript. No Python. No compilation step.

---
name: leila
role: Client Operations Manager
model: tier-2
cycle: 15m
channel: client-comms
tools:
  allow: [email-read, email-draft, tracker-update, calendar-read, invoice-handoff]
  deny: [deploy, db-write, git-push]
skills: [client-management, email-triage, invoice-processing]
discovery:
  prompt: "Check Gmail for new client emails. Check tracker for overdue items."
  sources: [gmail, tracker-db]
---
<h2 class="font-extrabold text-xl mt-10 mb-4">Identity</h2>
You are Leila, the Client Operations Manager. You handle all client-facing
communication with professionalism and precision.
<h2 class="font-extrabold text-xl mt-10 mb-4">Rules</h2>
- Never promise delivery dates without checking with the project manager
- Always CC the relevant team member when forwarding client requests
- Flag invoices over 10,000€ for manual review
- Respond to urgent emails within one cycle (15 minutes)
<h2 class="font-extrabold text-xl mt-10 mb-4">Voice</h2>
Professional, warm, direct. Never use corporate jargon. Write like a
competent human, not a chatbot.

That's it. The runtime reads this file, extracts the YAML frontmatter for configuration, and uses the Markdown body as the agent's system prompt. No runner file. No tool wiring. No boilerplate.

Why Markdown

Version control — AGENT.md lives in git. Every change to an agent's behavior is a commit with a diff. You can blame, revert, and audit. Try doing that with agent behavior defined across 12 Python files.

Non-developer editing — A business owner can open AGENT.md in any text editor and change the rules section. They don't need to understand JavaScript to tell their agent "never auto-approve orders over 5,000€."

Hot reload — The runtime watches AGENT.md for changes. Edit the file, save it, and the agent picks up the new config on its next cycle. No restart required.

Portability — Moving an agent between systems means copying one file. The AGENT.md carries its identity, tools, skills, and rules. The runtime handles everything else.

The frontmatter contract

The YAML frontmatter is a strict contract between the agent definition and the runtime:

- model — tier alias (not a model name), resolved by the LLM router - cycle — heartbeat interval, how often the agent wakes up - tools.allow — explicit whitelist of tool names this agent can call - tools.deny — explicit blacklist, overrides allow - skills — domain skills to inject into the prompt (matched by keyword) - discovery — what the agent looks for when its task queue is empty - channel — which communication channel this agent posts to

The runtime reads frontmatter, resolves the model tier to an actual model name, loads the allowed tools, injects matching skills, and assembles a token-budgeted prompt. The agent never sees its own configuration — it just receives a well-constructed context and a task to complete.

One file per agent. Zero code per agent. That's the design.