Skip to main content

​
MDA Overview

MDA (Markdown for Agent) is a Markdown superset for agent-facing documents. One .mda source compiles into the .md files every major agent runtime already loads — SKILL.md, AGENTS.md, MCP-SERVER.md, CLAUDE.md. On top of those plain outputs, MDA layers a real dependency graph, structured capability declarations, and reproducible signed identity. All optional. Standard Markdown still renders.

​
The problem MDA solves

In 2026 a single agent-facing skill routinely needs to ship as four files:
  • SKILL.md for the agentskills.io ecosystem (Claude Code, OpenCode, Codex, Hermes, OpenClaw, skills.sh, Cursor, Windsurf).
  • AGENTS.md for AAIF-aligned runtimes (Codex CLI, Copilot, Cursor, Windsurf, Amp, Devin, Gemini CLI, VS Code, Jules, Factory).
  • MCP-SERVER.md plus its sidecar mcp-server.json for MCP servers.
  • CLAUDE.md for Claude Code’s project-memory file.
Maintained as separate copies, they drift. A typo fix on Tuesday in SKILL.md doesn’t reach AGENTS.md. A version bump in AGENTS.md doesn’t propagate. A month in, the four files quietly disagree on what the skill actually does. The deeper problem is what you can’t say in any of those formats. You can’t declare “this skill depends on that one, version ^1.2.0, with this digest pin.” You can’t say “this file was signed by this identity at this Rekor index.” You can’t say “the relationship between this document and that one is supports, not cites.” There’s nowhere to put that information, so it lives in prose, where neither agents nor humans can act on it reliably. MDA puts those things into structured frontmatter and typed footnotes that a JSON Schema can validate. The Markdown body still renders. The standard fields still load. Everything new is optional.

​
The three MDA additions

A .mda source is just standard Markdown plus three optional layers.

​
1. Rich YAML frontmatter

Beyond the open-standard name and description baseline that every consumer already reads, MDA carries doc-id, version, requires, depends-on, relationships, and tags under a metadata.mda.* namespace. Vendor-specific extensions live alongside under reserved metadata.<vendor>.* namespaces. Strict JSON Schema 2020-12 validation, with unevaluatedProperties: false so unknown top-level fields fail fast. Spec section: §02 Frontmatter.

​
2. Typed footnote relationships

Standard Markdown footnotes whose payload is a JSON relationship object: parent, child, related, cites, supports, contradicts, extends. The compiler mirrors them to metadata.mda.relationships in body order. Standard renderers display them as plain footnotes with the JSON literal; MDA-aware tools traverse the typed graph. Spec section: §03 Relationships.

​
3. Optional cryptographic identity

A reproducible integrity digest derived through JCS canonicalization, with multi-file boundary semantics for skills that bundle scripts and references. DSSE PAE-enveloped signatures anchored in Sigstore by default, with a did:web air-gap fallback. The conformance runner enforces signatures[].payload-digest == integrity.digest byte-for-byte. Spec sections: §08 Integrity and §09 Signatures.

​
Three authoring modes

MDA artifacts may be produced three ways. They’re equivalent under validation.
  1. Agent mode — an AI agent writes the .md directly. The primary near-term use case. The v1.0 contract requires an LLM with only the spec in context to be able to produce conforming output.
  2. Human mode — a human writes the .md directly with standard hashing and DSSE-capable signing tools. See docs/create-sign-verify-mda.md.
  3. Compiled mode — an author writes a .mda source; the MDA compiler emits one or more .md outputs.
Whichever path you take, the artifact is judged against the same JSON Schema 2020-12 target schema, the same conformance suite, and the same cross-field check that signatures[].payload-digest equals integrity.digest. There’s no second code path for “this came from an agent.”

​
Why MDA, in plain terms

  • One source of truth. Stop maintaining four near-identical files.
  • A real dependency graph. Pin versions and content digests in frontmatter. The resolver refuses load when a candidate’s digest doesn’t match.
  • Typed relationships, not prose. Knowledge-graph and RAG indexers have something machine-readable to traverse.
  • Verifiable trust at load. Integrity checks and signatures that must match an operator trust policy.
  • Strict validation early. JSON Schema rejects “almost conformant” artifacts before they ship, instead of letting them silently drift in a runtime.
  • Open spec. Vendor-neutral. Per-vendor extensions live under reserved namespaces. Loaders read only their own namespace.

​
Status, honestly

v1.0 ships the contract, not the entire ecosystem around it. What works today: you can author a .mda, compile it to one or more conforming .md outputs, and validate them against the JSON Schema target schemas and the conformance suite. What’s still being built: a bundled signature verifier, a working dependency resolver, a central artifact registry, a graph indexer, and harnesses that route through metadata.mda.requires. The .mda you write today still produces conforming .md outputs that load in every runtime listed above. For the truthful gap, see What v1.0 doesn’t ship. For the long version of the value proposition, two documents go deeper:

​
Next

  • Quickstart — author a minimal .mda and compile it.
  • Architecture — deeper on the three additions and the parsing flow.
  • Specification — the normative entry point with links to every §.