Skip to content

Blog

Your whole agent in one file

Leif ·

File formats Agents Building in the open

An agent is usually scattered. A system prompt over here, a folder of skill files over there, some glue code deciding which skill to load. The pieces drift apart, and at runtime you tend to shove all of it into the context window just in case.

So I tried packing the whole thing into one file, using 3md. The result is a convention I am calling agent.3md: plane 0 is the agent, every other plane is a skill. The frontmatter is the manifest, each plane's attributes are a queryable index, and cross-plane links are the skill dependency graph. The same file reads as documentation and parses as a skill index, so the two cannot fall out of sync.

What it looks like

---
3md: 1.0
axis: skill
agent: atlas
model: claude-opus-4-8
---
@plane z=0 label="Atlas"
# Atlas
Route each task to the skill that matches, then load only that skill.

@plane z=1 label="web-research" triggers="search, find, latest"
# Skill: web-research
Turn the request into queries, read the best sources, cite them.

Plane 0 is the agent. Plane 1 is a skill with trigger words. Add more planes for more skills. A loader parses it and answers four questions: what is this agent (manifest), which skill handles this request (route), give me that skill (get), and what does it depend on (resolve). Routing is a one-liner:

route("find the latest on fusion ignition")  ->  web-research

Why this is good for agents

Progressive disclosure. The agent loads only the one skill a request needs, not the whole file. That is the same idea behind loading a skill on demand, except the whole catalog lives in one artifact you can read top to bottom.

Flat cost at scale. If you keep the skill index out of the prompt and query it as a tool, per-turn in-context cost stays roughly flat as you add skills (around 520 tokens whether the agent has 10 skills or 100), while loading the whole file grows with every skill. That is not free: it trades a tool call and a server-side index for a prompt that no longer grows with skill count. On the real six-skill example, loading one skill instead of the whole file is about 64 percent fewer tokens per turn at full routing accuracy.

Portable. 3md has conformance-verified parsers in Swift, TypeScript, and Rust, so the same agent.3md loads and routes identically in all three. We wrote a loader in each to prove it, byte for byte the same behavior.

MCP-ready. Point an MCP client at the file and its skills show up as tools (list, route, get, resolve). Any agent that speaks MCP can use an agent.3md without knowing anything about the format.

Checkable. There is a spec with MUST and SHOULD rules, a validator, and a set of labeled valid and invalid test documents so an implementation in any language can self-check. A standard is only real if you can fail it.

Try it

It is early, version 0.1, a reference standard rather than a finished product. But it runs today.

Write an agent.3md, validate it, route a request, serve it over MCP. One plain-text file, human-readable and machine-queryable, holding a whole agent and loading only the skill it needs.

← All posts