v1.0.0

agent.3md: a format for agents in one file

One plain-text 3md file is a whole agent. Plane 0 is the agent (identity,
rules); every other plane is a skill. The frontmatter is the manifest, each
plane's attributes (triggers=, typed inputs=, tool=, cost=) are a
queryable index, and [[z=N|..]] links are the skill dependency graph.

Skills are real. A skill can bind to an actual CLI command (tool=), and
then its typed inputs are that command's arguments, so routing is not "read some
prose," it is route -> fill -> run: pick the skill, fill its inputs, get the
exact command to run.

@plane z=1 label="search" kind=skill triggers="search, find, grep" inputs="pattern:string, path:string" tool="rg --line-number {pattern} {path}"

A tool is optional. Skills that are not command-shaped (web research, a
judgment call, anything the host's own tools handle) carry no tool and are
pure guidance the agent follows with whatever capabilities it has. So a real
agent is usually a mix: some skills run a command, some are a playbook.

The same file is human-readable documentation and a machine-queryable skill
index, so the two can never drift. And because skills are addressable planes, an
agent loads only the one skill it needs per turn (progressive disclosure)
instead of stuffing every skill into context.

Quickstart (2 minutes)

There are two ways in, by design. TypeScript is the reference implementation,
the package you embed in an agent; it carries the spec, the validator, and the
MCP server. Rust is the default native CLI, a single fast binary for the
command line with no runtime to install.

Embed the library (TypeScript, the default for code). It's on the public
npm registry, no token or .npmrc needed:

npm install @corvidlabs/agent3md

import { Agent, validateAgent } from "@corvidlabs/agent3md";
import { readFileSync } from "node:fs";

const src = readFileSync("agent.3md", "utf8");
console.log(validateAgent(src).ok);                  // true
const agent = new Agent(src);
const top = agent.route("find every TODO")[0].skill; // -> "search"
console.log(agent.command(top.name, { pattern: "TODO", path: "src" }));
// -> rg --line-number 'TODO' 'src'   (route -> fill -> run)

Install the CLI (Rust, the default for the command line). A fast native
binary, nothing to run it on top of:

cargo install agent3md
agent3md run agent.3md "find every TODO" pattern=TODO path=src          # route -> command
agent3md run agent.3md "find every TODO" pattern=TODO path=src --exec   # and run it
agent3md validate agent.3md                                            # exit non-zero on errors

Or scaffold and drive it from this repo:

git clone https://github.com/CorvidLabs/agent-3md && cd agent-3md
bun run cli new my-agent              # writes a valid starter my-agent.3md (real CLI skills)
bun run validate my-agent.3md         # PASS
bun run cli run my-agent.3md "find every TODO" pattern=TODO path=src
bun run mcp my-agent.3md              # serve its skills to any MCP client

Why it's good for agents

• Progressive disclosure. The agent loads only the one skill a request needs,
  not all of them. On the real 6-skill example that is about 73% fewer tokens
  per turn at 100% routing accuracy (bun run benchmark). With realistic
  ~300-token skills, loading one instead of dumping the whole file is about 96%
  fewer per turn at 100 skills (bun run scale). Routing accuracy depends on
  writing distinct triggers, and the benchmark measures it, it is not assumed.
• Flat at scale, honestly. Move the catalog out of the prompt and query it
  with a routing tool, and per-turn in-context cost stays roughly flat (about
  520 tokens whether the agent has 10 skills or 100, bun run scale2). That
  is not free: it costs a tool round-trip per turn plus a catalog that lives in
  the loader, but it decouples per-turn prompt size from skill count.
• One artifact, two readers. Read it as docs; parse it as an index.
• Portable, proven. The same agent.3md loads and routes identically in
  TypeScript, Rust, and Swift (loaders/), each on the canonical 3md parser.
  Plus a JSON projection (bun run export) for non-3md consumers.
• Checkable. A conformance validator + a language-agnostic vector set
  (examples/conformance/) make it checkable, not a vibe.

The spec

SPEC.md defines agent3md/1: manifest frontmatter, the one
identity plane vs skill planes, the skill contract (triggers / typed inputs /
tool command templates / cost / dependency links), the loader contract
(manifest / route / get / resolve / command), and the MUST/SHOULD
conformance rules.

What's here

file	what
agent.3md	the flagship agent (dev): a terminal-first toolbox, identity + 7 skills (6 command-backed + 1 guidance-only)
SPEC.md	the agent3md/1 spec
src/threemd.ts	the canonical 3md parser (vendored)
src/runtime.ts	reference loader: manifest / route / get / resolve / command
src/validate.ts	conformance validator (+ examples/invalid/ fixtures)
src/cli.ts	agent3md CLI (incl. run [--exec])
src/mcp.ts	MCP server: exposes an agent's skills as MCP tools
src/export.ts	JSON manifest projection (agent3md/1) for any consumer
loaders/rust, loaders/swift	the same agent loaded via the Rust + Swift parsers
examples/agents/	more real agents (corvid, devops, support); proves generality
examples/conformance/	labeled valid/invalid vectors for any implementation
src/benchmark.ts, src/scale/	token-savings proof, single + scaled + flat

Try it

bun run demo          # load the dev agent, route requests, fetch one skill
bun run run           # route -> fill -> command (the real CLI each request maps to)
bun run validate agent.3md   # conformance check (exit non-zero on errors)
bun run test          # validator conformance suite
bun run benchmark     # token savings on the example agent
bun run scale         # the savings curve at 10/25/50/100 skills
bun run cli run agent.3md "find every TODO" pattern=TODO path=src
bun run mcp:selftest  # spawn the MCP server and call its tools

Use it from any MCP client

Point an MCP-capable agent at the server; its skills appear as tools
(list_skills, route_skill, get_skill, resolve_skill):

{ "command": "bun", "args": ["src/mcp.ts", "agent.3md"] }

---

Full Changelog: v0.3.0...v1.0.0

v0.3.0

First public npm release with CLI-backed skills. npm install @corvidlabs/agent3md (no token needed). See the docs at https://corvidlabs.xyz/agent-3md/docs/ . Skills bind to real commands (route -> fill -> run), with typed inputs, guidance-only skills, optional model, and cross-language loaders (TS, Rust, Swift).

v0.2.1 - hardened parser

Re-vendors the hardened 3md parser (CorvidLabs/3md#42): null-prototype attribute maps remove the prototype-key landmine from untrusted documents. Also: the Rust loader now uses the published threemd crate from crates.io (no vendoring).

v0.2.0 - council fixes

Fixes from an adversarial review council: one dependency-link grammar across all loaders, reconciled spec/validator/runtime rules, Routing v2 (identical in TS/Rust/Swift), an honest accuracy-measured benchmark, MCP security hardening, shipped .d.ts, and CI. See docs/ROADMAP-1.0.md.

v0.1.0 - agent.3md standard kit

First release of the agent.3md standard: one 3md file is a whole agent (identity + on-demand skills). Includes the spec, the TS reference loader (@corvidlabs/agent3md), Rust + Swift loaders, a validator + conformance vectors, a CLI, an MCP server, JSON projection, and the token-savings/flat-scaling proofs.