Agent 3md

npm version crates.io version CI Build Status spec coverage Spec Status License

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

There are multiple 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. Swift is the native iOS/macOS loader, bringing full portability.

Embed the library (TypeScript)

It is 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)

A fast native binary with no runtime:

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

Swift Loader

A clean Swift Package Manager loader depending on the canonical ThreeMD package:

import Agent3MD

let agent = try Agent(source: sourceString)
let routed = agent.route("find every TODO")

---

Why it is 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. 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. Fully verified by native test suites in TypeScript, Rust, and Swift.

---

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.

---

Repository Structure

File/Dir	What it does
agent.3md	The flagship agent (dev): a terminal-first toolbox, identity + 7 skills (6 command-backed + 1 guidance-only)
SPEC.md	The authoritative agent3md/1 standard
src/runtime.ts	Reference TypeScript loader: manifest / route / get / resolve / command
src/validate.ts	Conformance validator (+ examples/invalid/ fixtures)
src/cli.ts	TypeScript agent3md CLI
src/mcp.ts	MCP server: exposes an agent's skills as MCP tools
loaders/rust	Native Rust CLI and loader, with native conformance tests
loaders/swift	Native Swift loader, with XCTest conformance tests
examples/conformance/	Labeled valid/invalid vectors for any implementation

---

Verifying Local Changes

Run the CI gate lane via fledge:

fledge lanes run verify

This verify lane runs the TypeScript reference tests, compiles the typed bundle, runs Rust fmt/clippy/conformance tests, and executes Swift conformance unit tests.

---

Status: v1.0.0 (Production Ready)

Version 1.0.0 is the production release of the agent3md/1 standard. It is fully verified with native conformance tests across TypeScript, Rust, and Swift, featuring typed inputs, per-skill tool bindings, CLI-backed executable tools, and a built-in MCP server.