--- title: "Overview" description: "What MDA Open Spec is, what problem it solves, and how it sits between standard Markdown and the agent-runtime ecosystem." --- # 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..*` namespaces. Strict JSON Schema 2020-12 validation, with `unevaluatedProperties: false` so unknown top-level fields fail fast. Spec section: [§02 Frontmatter](https://github.com/sno-ai/mda/blob/main/spec/v1.0/02-frontmatter.md). ### 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](https://github.com/sno-ai/mda/blob/main/spec/v1.0/03-relationships.md). ### 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](https://github.com/sno-ai/mda/blob/main/spec/v1.0/08-integrity.md) and [§09 Signatures](https://github.com/sno-ai/mda/blob/main/spec/v1.0/09-signatures.md). ## 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`](https://github.com/sno-ai/mda/blob/main/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](https://github.com/sno-ai/mda/blob/main/ai-doc/what-v1.0-does-not-ship.md). For the long version of the value proposition, two documents go deeper: - [Core value for AI agents](https://github.com/sno-ai/mda/blob/main/ai-doc/ai-agent-core-value.md) — five points framed for runtimes, harnesses, validators, and dispatchers. - [Core value for human authors and curators](https://github.com/sno-ai/mda/blob/main/ai-doc/human-curator-user-core-value.md) — six points framed for the people who write and curate agent-facing instruction libraries. ## Next - [Quickstart](/quickstart) — author a minimal `.mda` and compile it. - [Architecture](/mdx/architecture) — deeper on the three additions and the parsing flow. - [Specification](/mdx/specification) — the normative entry point with links to every §.