Skip to content

What is agent.3md?

Getting started

One file is a whole agent

An agent.3md file is a complete agent in one plain-text document: its identity plus all of its skills. It is built on 3md, Markdown extended along a single named Z axis. The mapping is simple:

  • Plane 0 is the agent. Its body is the identity, the operating rules, the system prompt.
  • Every other plane is a skill. Its label is the skill's name and its body is the skill's instructions.

The frontmatter is the manifest. Each skill plane's attributes (triggers=, typed inputs=, optional tool=, optional cost=) form a queryable index, and [[z=N|label]] links in skill bodies are the dependency graph between skills.

One artifact, two readers

The same bytes are human-readable documentation and a machine-queryable skill index. Read the file top to bottom and it is the agent's docs. Parse it and it is a structured catalog. Because the skill index and the skill instructions are the same bytes, they cannot drift apart.

That shape also enables progressive disclosure. A loader reads the manifest once, then fetches only the single skill plane a request needs, instead of stuffing every skill into the model's context every turn.

Skills are real: route then fill then run

A skill can bind to an actual command via tool=. When it does, its typed inputs are that command's arguments, so using the agent is not "read some prose," it is a concrete loop:

  1. Route a request to the skill whose triggers match it.
  2. Fill that skill's typed inputs with concrete values.
  3. Run the exact command the loader produces.

A tool is optional. A skill with no tool is guidance only: a playbook the agent follows using whatever capabilities the host already gives it (web search, a judgment call, an action handed to a host or MCP tool). A real agent is usually a mix of command-backed and guidance-only skills.

A small example

---
3md: 1.0
axis: skill
agent: dev
tools: rg, fd
---
A terminal-first dev agent. No model line: the runner picks the model.

@plane z=0 label="dev" kind=identity
# dev
Route each request to the matching skill, fill its inputs, run its command.

@plane z=1 label="search" kind=skill triggers="find, search, grep, code" inputs="pattern:string, path:string" tool="rg --line-number {pattern} {path}"
# Skill: search
Find code by regex. For filenames instead of contents, see [[z=2|files]].

@plane z=2 label="files" kind=skill triggers="files, list, locate, glob" inputs="glob:string, dir:string" tool="fd {glob} {dir}"
# Skill: files
List files matching a name pattern under a directory.

Routing "find every TODO" selects search; filling pattern=TODO path=src yields rg --line-number 'TODO' 'src'.

Why it is good for agents

  • Progressive disclosure. Load only the one skill a request needs, not all of them, which keeps per-turn context small as the skill count grows.
  • One artifact, two readers. Docs and index never diverge.
  • Portable and checkable. The same file loads and routes identically in TypeScript, Rust, and Swift, and a conformance validator plus a language-agnostic vector set keep it honest.

Next steps